session-execution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Execution

会话执行

Read

docs/SESSION_EXECUTION.md

before working in this area. It explains the architecture for reliable command execution with stdout/stderr separation.

在开展此领域的工作前，请阅读

docs/SESSION_EXECUTION.md

，该文档阐述了实现可靠命令执行并分离stdout/stderr的架构。

Key Concepts

核心概念

Two execution modes:

Foreground (exec): Runs in main shell, state persists. Uses temp files for output capture.
Background (execStream/startProcess): Runs in subshell via FIFOs. Labelers prefix output in background.

Binary prefix contract:

Stdout:
```
\x01\x01\x01
```
prefix per line
Stderr:
```
\x02\x02\x02
```
prefix per line
Log parser reconstructs streams from these prefixes

Completion signaling:

Exit code written to
```
<id>.exit
```
file via atomic
```
tmp
```
+
```
mv
```
Hybrid fs.watch + polling detects completion (robust on tmpfs/overlayfs)
Background mode uses
```
labelers.done
```
marker to ensure output is fully captured

两种执行模式：

前台模式（exec）：在主shell中运行，状态会持久化。使用临时文件捕获输出。
后台模式（execStream/startProcess）：通过FIFO在子shell中运行。标签器会为后台输出添加前缀。

二进制前缀约定：

Stdout：每行前缀为
```
\x01\x01\x01
```
Stderr：每行前缀为
```
\x02\x02\x02
```
日志解析器会根据这些前缀重构流数据

完成信号机制：

退出码通过原子操作（先写入.tmp文件再移动）写入
```
<id>.exit
```
文件
混合使用fs.watch + 轮询的方式检测执行完成（在tmpfs/overlayfs环境下稳定性强）
后台模式使用
```
labelers.done
```
标记以确保输出被完整捕获

When Developing

开发注意事项

Understand why foreground uses temp files (bash waits for redirects to complete)
Understand why background uses FIFOs (concurrent streaming without blocking shell)
Test silent commands (cd, variable assignment) - these historically caused hangs
Test large output - buffering issues can cause incomplete logs

理解前台模式使用临时文件的原因（bash会等待重定向操作完成）
理解后台模式使用FIFO的原因（实现并发流处理且不会阻塞shell）
测试无输出命令（如cd、变量赋值）——这类命令曾导致挂起问题
测试大输出场景——缓冲问题可能导致日志不完整

When Reviewing

评审注意事项

Correctness checks:

Verify exit code handling is atomic (write to .tmp then mv)
Check FIFO cleanup in error paths
Ensure labelers.done is awaited before reading final output (background mode)

Race condition analysis:

Session execution has a mutex that serializes command execution per session. Before flagging race conditions:

Check if operations happen within the same session (mutex protects)
Check if operations are per-session vs cross-session (cross-session races are real)
Refer to
```
docs/CONCURRENCY.md
```
for the full concurrency model

Common false positives:

"Concurrent reads/writes to session state" - mutex serializes these
"FIFO operations might race" - labelers are per-command, not shared

Actual concerns to watch for:

Cross-session operations without proper isolation
Cleanup operations that might affect still-running commands
File operations outside the mutex-protected section

正确性检查：

验证退出码处理是否为原子操作（先写入.tmp再移动）
检查错误路径中的FIFO清理逻辑
确保在读取最终输出前等待
```
labelers.done
```
完成（后台模式）

竞争条件分析： 会话执行机制包含一个互斥锁，用于序列化每个会话的命令执行。在标记竞争条件前，请先：

检查操作是否在同一会话内（互斥锁会保护此类操作）
检查操作是单会话还是跨会话的（跨会话竞争是真实存在的）
参考
```
docs/CONCURRENCY.md
```
获取完整的并发模型

常见误判：

"对会话状态的并发读写"——互斥锁会序列化这些操作
"FIFO操作可能存在竞争"——标签器是按命令独立分配的，并非共享资源

需要关注的实际问题：

跨会话操作未进行适当隔离
清理操作可能影响仍在运行的命令
互斥锁保护区域外的文件操作

Key Files

核心文件

packages/sandbox-container/src/session.ts

- Session class with exec/execStream

packages/sandbox-container/src/managers/SessionManager.ts

- Mutex and lifecycle

packages/sandbox/src/clients/CommandClient.ts

- SDK interface to session commands

packages/sandbox-container/src/session.ts

——包含exec/execStream的Session类

packages/sandbox-container/src/managers/SessionManager.ts

——互斥锁与生命周期管理

packages/sandbox/src/clients/CommandClient.ts

——会话命令的SDK接口