sandbox_procs

sandbox_exec の background: true で始めたコマンドを一覧し、終了を待ち、止めます。フォアグラウンドのコマンドも execId で取得したり待ったりできます。pkill -f や pgrep -f の代わりに使います。それらのパターンは、コマンドラインにそれを含むすべてのプロセスに一致し、ほかのジョブも含まれるからです。

sandbox_exec の background: true で始めたコマンドにはそれぞれ bgId があり、出力は logPath、つまり /work/.sbx/logs/<bgId>.log に書かれます。sandbox_procs はそれらのコマンドを扱います。

sandbox_procs { "id": "<id>" }
sandbox_procs { "id": "<id>", "action": "list", "bgId": "<bgId>" }
sandbox_procs { "id": "<id>", "action": "wait", "bgId": "<bgId>", "timeoutSec": 300 }
sandbox_procs { "id": "<id>", "action": "stop", "bgId": "<bgId>" }

• list（action なしの呼び出しも同じ）は { "procs": [...] } を返します。動作中のバックグラウンドコマンドを古い順に並べ、それぞれに bgId、running、note（sandbox_exec に渡したもの）、cmd（先頭 120 文字。シークレットの値は隠されます）、startedAt、logPath、cpu（そのすべてのプロセスの %CPU の合計。100 で 1 コア）、mine（この会話が始めたものかどうか）が付きます。foreground は、ボックスを使っているすべての会話の、いま動作中のフォアグラウンドのコマンドを同じ形で、execId を bgId として並べます。複数の会話で共有しているボックスでは、cpu と mine で誰の作業がマシンを使っているかがわかります。終わったものを省いたときは、finished にその数、hint に見る方法が出ます。all: true なら終わったものも exitCode 付きで並びます（動作中のものには付きません）。bgId を指定すると、動作中かどうかにかかわらずそのコマンドだけを、ログの末尾である logTail 付きで返します。
• 普通の list には logTail が付きません。bgId 付きの list、wait、stop はログの最後の 4096 バイトを返し、tailBytes（1〜16384）でその量を変えられます（普通の list にも効きます）。中のシークレットの値は **** になります（sandbox_exec）。ログファイル自体は変わりません。
• wait はそのコマンドが終わるか、timeoutSec（既定 600、最大 600）が尽きるまで待ち、{ "proc": {...}, "stillRunning": false } を返します。proc には exitCode が付きます。先に時間が尽きたときはエラーではなく stillRunning: true を返すので、もう一度呼びます。バックグラウンドで始めた長いビルドやテストはこれで待ちます。sandbox_exec で sleep しながらポーリングする必要はありません。
• until: "ready" を付けると、代わりにコマンドの準備ができた時点で戻ります。その readyPort が接続を受け付けるか、ログの行が readyLog に一致したとき（どちらも sandbox_exec に渡したもの）で、ready: true と readyAt が付きます。wait に readyPort や readyLog を渡すと、条件なしで始めたコマンドにその条件を設定（または置き換え）し、until: "ready" も指定したことになります。ログは先頭から探すので、呼び出し前に出力された行も数えます。準備ができる前にコマンドが終わると、wait はそれを終わったものとして ready: false 付きで返します。
• フォアグラウンドのコマンドの execId は bgId として使えます。動作中は、それを指定した list と wait が foreground: true 付きで示し、そこまでの出力を logTail として返します。終わると、proc.result にその sandbox_exec が返したもの（stdout、stderr、exitCode、truncated、durationMs、timedOut、出力が切り詰められたときは outputPath）が入ります。その呼び出しが途中で切れたときに使ってください。直近 200 件のフォアグラウンドの結果が保存されます。
• steps（コマンド 1 つのときだけ）は、その中で psbx-step が記録したものを並べます。各ステップの name、exitCode、ms、startedAt で、まだ動いているものには running: true が付きます（sandbox_exec を参照）。
• シグナルで終わったコマンドには signal があり、何がそれを送ったかを endReason が示します：stopped by sandbox_procs stop、OOM killer（ボックスのメモリが足りなくなった）、またはほかのプロセスです。
• stop はコマンドのプロセスグループ全体を終わらせます。SIGTERM を送り、5 秒後にまだ残っていれば SIGKILL を送ります。コマンドが起動したものも一緒に終わるので、npx や npm run で起動したサーバーも止まり、ポートが空きます。{ "proc": {...}, "stopped": true } を返し、止めたコマンドの exitCode は -1 です。すでに終わっていたコマンドには、そのときの状態をそのまま返します。
• バックグラウンドコマンドはこれで止め、sandbox_exec の pkill -f や pgrep -f は使わないでください。コマンドはスクリプトファイルから動くので、パターンが自分の sandbox_exec を動かしているシェルに一致することはもうありませんが、コマンドラインにそれを含むほかのプロセスにはすべて一致し、ほかのバックグラウンドジョブも含まれます。バックグラウンドで起動していないプロセスには、プロセス名に完全一致する pkill -x <名前> を使ってください。kill <pid> はそのプロセス 1 つにしかシグナルを送らず、それが起動したプロセス（npx の下のサーバーなど）は動き続けることがあります。stop はグループ全体を終わらせます。
• バックグラウンドコマンドは /work/.sbx/procs に記録されるので、ボックスのエージェントである boxd の再起動（更新、クラッシュ、メモリ不足での強制終了）をまたいで残ります。動作中のものはこれまでどおり一覧でき、止められます。boxd が止まっている間に終わったものは exitCode が -1 で、本当の終了コードはわからないと示す endReason が付きます。これより古いイメージから起動したボックスは、boxd が再起動するとこの記録を失い、bgId not found と答えます。
• エラー：ボックスが知らない bgId には、考えられる理由付きで box <id>: bgId not found: …、bgId のない wait や stop には bgId is required: list them first with action list、それ以外の action には action must be list, stop or wait が返ります。
• 呼び出しはほかのツールと同じくボックスの使用に数えるので、長いジョブを wait で待っている間、ボックスがアイドルで凍結されることはありません。凍結したボックスには先に起こします（ボックスの状態）。バックグラウンドコマンドは凍結と解凍をまたいで動き続け、ボックスを起こしておくのは最後の使用から最大 1 時間です。フォアグラウンドの sandbox_exec の中で & で起動したプロセスはこれに含まれません。このツールでは一覧も停止もできず、起動した呼び出しが leftoverChildren: true で知らせます（sandbox_exec）。

すべてのツールとトピックはツールリファレンスに並んでいます。