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)

41installs
Sourcecloudflare/sandbox-sdk
Added on

NPX Install

npx skill4agent add cloudflare/sandbox-sdk session-execution

Tags

Translated version includes tags in frontmatter
session-executionshell-process-managementfifo-streamingstdout-stderr-separationconcurrency-control

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:
  1. Check if operations happen within the same session (mutex protects)
  2. Check if operations are per-session vs cross-session (cross-session races are real)
  3. 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