無人AIセッションの「バックグラウンド委譲」が静かに殺される事故を潰す

無人・ヘッドレスで起動した AI エージェント（<agent-cli> -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、ツール実行前フックとして起動される想定）:

#!/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/…/<worktree>/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 ではなく成果物の存在になっている