# 無人AIセッションの「バックグラウンド委譲」が静かに殺される事故を潰す 無人・ヘッドレスで起動した AI エージェント（` -p "<指示>"` のような1回きりの実行）から、 実装役の別CLIや長時間ジョブを**バックグラウンドで起動して完了を待つ**と、 **ターンを終えた瞬間に親ごと死に、起動した子も一緒に殺される**。 しかも親の終了コードは **0（成功）** になるので、ログも通知も「成功」に見える。 これは「渡し方（argv / TTY / timeout）」の問題ではなく **プロセス寿命** の問題で、別軸の事故。 そのまま読ませれば適用できる粒度で書いてある。 --- ## 結論（これだけ守れば足りる） 1. **ヘッドレス実行では「バックグラウンドで起動 → ターン終了 → あとで確認」をしない** 2. 長い処理は **前景で** 実行し、**残り時間より短い上限時間**を必ず付ける 3. 待ち切れないなら待たず、**そこまでの成果を残して次回へ引き継ぐ**（draft PR / 作業ログ） 4. 文言の禁止だけでは再発する。**フック等で機械的に deny する** 5. **終了コード 0 を成功の証拠にしない**。成果物（PR、生成ファイル、差分）の存在で判定する --- ## なぜ（実際に起きた事故） 夜間の無人セッションが「不具合報告 → 原因調査 → 修正 → PR 作成」を担当していた。 ある晩の結果通知はこれだけだった。 ``` 1件試行し、1件でPRを作成できませんでした ``` 追いかけると、担当セッションは**正しく原因を特定していた**。そのうえで実装役CLIを バックグラウンドで起動し、「10分後に完了を確認する」というスケジュールを入れてターンを終了していた。 - 実装役CLIのログ末尾: 起動 **23秒後に `[killed]`** - 作業ツリーの差分: **ゼロ**（指示ファイルだけが置き去り） - 親の終了コード: **0 / status=success** ヘッドレスの1回きり実行には「あとで起こしてもらう」ループが存在しない。 ターン終了＝プロセス終了で、プロセスツリーごと片付けられる。 `sleep` を挟もうが、スケジュールAPIを呼ぼうが同じで、**待っているつもりの時間が存在しない**。 ### なぜ何日も気付けないか - 親は exit 0 なので、監視も「成功」として記録する - 通知は件数だけで、原因・作業ログの場所・再開手段が入っていない - 対象が「対応中」フラグ付きのまま残り、**次回以降の自動処理から除外され続ける**（後述） 「失敗しているのに失敗として観測できない」形なので、放っておくと**静かに毎晩空振りする**。 --- ## 直し方 ### 1. 機械的に禁止する（本丸） 無人実行であることを環境変数で判別できるようにし（例: 起動側が `HEADLESS=1` を渡す）、 ツール実行前フックで**バックグラウンド起動と「あとで起こして」系API**を deny する。 擬似コード（Node、ツール実行前フックとして起動される想定）: ```js #!/usr/bin/env node try { let raw = ''; process.stdin.setEncoding('utf8'); for await (const chunk of process.stdin) raw += chunk; if (process.env.HEADLESS !== '1') process.exit(0); // 対話セッションでは何もしない const input = JSON.parse(raw); const tool = String(input.tool_name || ''); let reason = ''; if (tool === 'ScheduleWakeup') { reason = '無人実行では「あとで起こす」は配送されません。ターン終了でプロセスごと終わり、' + '待っていた処理は kill されます。時間のかかる処理は前景で上限時間付きで実行してください。'; } else if (/^(Bash|Shell)$/.test(tool) && input.tool_input?.run_in_background === true) { reason = '無人実行ではバックグラウンド起動は使えません。ターン終了でプロセスツリーごと kill され、' + '起動しただけで終わります。前景で --timeout <秒> を付けて実行してください。'; } if (!reason) process.exit(0); console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason, }, })); } catch {} // フックの不具合で作業を止めない ``` 要点: - **対話セッションでは絶対に発火させない**（人が見ている場ではバックグラウンドは正当） - deny の理由文に**代替手段**まで書く。禁止だけ伝えても同じ場所で詰まる - 壊れた入力でも exit 0。ガードが作業を殺してはいけない テストは「無人フラグの有無 × 対象ツール」の組合せで、 `deny が出ること` と `出ないこと` の**両方**を必ず押さえる。 ### 2. 無人実行の指示文にも書く（フックの補助） ``` - このセッションは1回きりの無人実行である。ターンを終えた瞬間にプロセスごと終了し、 起動中の子プロセスはすべて kill される。 - バックグラウンド起動と「あとで起こす」系の待機は使用禁止（フックでも deny される）。 - 委譲は必ず前景で実行し、上限時間にはセッションの残り時間より短い秒数を渡す。 - 時間内に終わらない見込みなら待たず、そこまでの状態を作業ログに書き、 作りかけを draft として残すか次回へ引き継いで終了する。 ``` ### 3. 失敗通知に「次の一手」を必ず入れる 件数だけの通知は、調査コストを人間に丸投げしているのと同じ。最低限これを載せる。 - 対象（ID と**人が読める名前**）と、その URL - 子の終了状態（成功 / 失敗 / タイムアウト / 起動失敗を区別できる語）と終了コード - 作業ログファイルのパス - **再開コマンド**（セッションIDから復帰できるなら、その1行をそのまま） - 標準エラーの先頭200文字程度。ただし**トークン・鍵・webhook はマスクしてから** ### 4. 「対応中」フラグを必ず戻す 着手時に「対応中」ラベル等を立てて重複処理を防ぐ設計はよいが、 **外すのが「起動失敗のときだけ」になっていないか**を必ず確認する。 今回は「起動は成功／成果ゼロ」がフラグの外れない穴になり、 対象は**以後どの自動処理からも永久に拾われない**状態で放置されていた。 判定は「終了コード」ではなく **成果物の有無**（PRのURLが取れたか等）で行い、 成果が無ければフラグを戻して次回リトライさせる。 --- ## 一緒に踏みやすい落とし穴 ### Windows で作った git のリンク作業ツリーは、Linux 側から解決できない Windows 側で `git worktree add` すると、作業ツリーの `.git` ファイルが `gitdir: C:/…/.git/worktrees/<名前>` という**ドライブレター付き絶対パス**になる。 Linux 側（WSL 等）で動く実装役CLIはこれを解決できず、次のようなエラーを出し続ける。 ``` ERROR ...permissions: Resolved gitdir path /mnt/c/…//C:/Users/…/.git/worktrees/<名前> does not exist ``` ファイル編集はできても **git 操作が全滅**するので、コミットもブランチ作成もできない。 対策は相対パス化。**両側から同じように解決できる**ようになる（実測確認）。 ``` git -C <作業ツリー> -c worktree.useRelativePaths=true worktree repair ``` 委譲ラッパー側で、起動前に「`.git` がファイル」かつ「中身が `gitdir: <英字>:` で始まる」なら 上記を自動実行しておくと、人が気付く前に潰せる。冪等なので毎回走らせてよい。 さらに、**改行コード設定が両OSで異なる**と、Linux側から `git add` した瞬間に無関係な ファイルが差分として巻き込まれる。委譲先には「**git を一切触るな。編集と検証だけしろ。 コミットとPRは呼び出し元がやる**」と明示するのが安全。 ### 新しい作業ツリーには依存関係が入っていない 作業ツリーを切ったばかりの場所には `node_modules` 等が無く、 コミットフックが必要とするツールも入っていない。 委譲先が一時ディレクトリに入れて検証を通しても、**呼び出し元から見ると空**ということが起きる。 コミット直前に「フックが必要とするバイナリが実在するか」を確認し、 無ければ**素直に依存関係を入れる**。フックを飛ばして回避しない。 --- ## チェックリスト - [ ] 無人実行であることを環境変数で判別できる - [ ] 無人実行時、バックグラウンド起動と待機系APIがフックで deny される - [ ] 対話セッションでは deny されないことをテストで押さえた - [ ] 委譲は前景 + 上限時間（残り時間より短い） - [ ] 失敗通知に 対象名 / 状態 / ログのパス / 再開コマンド が入っている - [ ] 「対応中」フラグを外す条件が、終了コードではなく**成果物の有無**になっている - [ ] リンク作業ツリーの gitdir を相対パス化してから委譲している - [ ] 委譲先に「git を触るな」と明示している - [ ] 完了報告の根拠が exit 0 ではなく成果物の存在になっている ---