session-execution

Original：🇺🇸 English

Translated

Use when working on or reviewing session execution, command handling, shell state, FIFO-based streaming, or stdout/stderr separation. Relevant for session.ts, command handlers, exec/execStream, or anything involving shell process management. (project)

1installs

Sourcecloudflare/sandbox-sdk

Added on2026-02-26

NPX Install

npx skill4agent add cloudflare/sandbox-sdk session-execution

SKILL.md Content

View Translation Comparison →

Session Execution

Read

docs/SESSION_EXECUTION.md

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

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

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

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

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