session-execution

セッション実行

この領域で作業する前に、docs/SESSION_EXECUTION.md を読んでください。標準出力と標準エラー出力を分離した、信頼性の高いコマンド実行のアーキテクチャについて説明しています。

主な概念

2 つの実行モード：

• フォアグラウンド（exec）：メインシェルで実行され、状態は保持されます。出力のキャプチャには一時ファイルを使用します。
• バックグラウンド（execStream/startProcess）：FIFO を介してサブシェルで実行されます。バックグラウンドでは、ラベラーが出力の先頭にプレフィックスを付けます。

バイナリプレフィックスの仕様：

• 標準出力：各行に \x01\x01\x01 プレフィックス
• 標準エラー出力：各行に \x02\x02\x02 プレフィックス
• ログパーサーは、これらのプレフィックスから各ストリームを再構成します

完了通知：

• 終了コードは、tmp への書き込みと mv による移動をアトミックに行い、<id>.exit ファイルに書き込まれます
• fs.watch とポーリングを併用して完了を検出します（tmpfs/overlayfs でも確実に動作します）
• バックグラウンドモードでは、出力が完全にキャプチャされるよう、labelers.done マーカーを使用します

開発時

• フォアグラウンドで一時ファイルを使用する理由を理解してください（bash はリダイレクトの完了を待ちます）
• バックグラウンドで FIFO を使用する理由を理解してください（シェルをブロックせず、同時にストリーミングできます）
• 無出力のコマンド（cd、変数の代入）をテストしてください。これらは過去にハングの原因になっていました
• 大量の出力をテストしてください。バッファリングの問題により、ログが不完全になることがあります

レビュー時

正確性の確認：

• 終了コードの処理がアトミックであることを確認してください（.tmp に書き込んでから mv）
• エラー処理パスで FIFO がクリーンアップされることを確認してください
• （バックグラウンドモードで）最終出力を読み取る前に、labelers.done が完了するまで待機することを確認してください

競合状態の分析：

セッション実行では、セッションごとにコマンド実行を直列化するミューテックスを使用します。競合状態を指摘する前に、次を確認してください。

1. 操作が同じセッション内で行われるか（ミューテックスが保護します）
2. 操作がセッション単位か、セッションをまたぐものか（セッションをまたぐ競合は実際に発生します）
3. 並行処理モデルの全容については、docs/CONCURRENCY.md を参照してください

よくある誤検出：

• 「セッション状態の読み取り／書き込みが並行して行われる」— ミューテックスによって直列化されます
• 「FIFO 操作で競合が起きる可能性がある」— ラベラーはコマンドごとに割り当てられ、共有されません

注意すべき実際の懸念点：

• 適切に分離されていない、セッションをまたぐ操作
• 実行中のコマンドに影響を及ぼす可能性のあるクリーンアップ操作
• ミューテックスで保護されたセクションの外部で行われるファイル操作

主なファイル

• packages/sandbox-container/src/session.ts - exec/execStream を備えた Session クラス
• packages/sandbox-container/src/managers/SessionManager.ts - ミューテックスとライフサイクル
• packages/sandbox/src/clients/CommandClient.ts - セッションコマンド用 SDK インターフェース