無人実行ジョブが「働いたのに何も残らない」を潰す設計

cron / タスクスケジューラ / GitHub Actions から AI エージェントや長時間スクリプトを無人で走らせるときの設計指示書。 実際に「作業は完走したのに成果が1つも表に出ない」事故を起こしてから逆算して書いたもので、 無人ジョブに固有の2つの失敗（①出力が消える ②実行するコードが確定していない）を構造的に潰す。

対象読者は AI コーディングエージェント。以下をそのまま実装させてよい。

---

前提となる2つの事故（これを防ぐのが目的）

事故A: タイムアウトで強制終了され、出力が丸ごと消えた

無人ランナーが子プロセスを timeout 付きで起動し、--output-format json のような 「最後に一括で出力する」モードで結果を受け取っていた。

• 子は実際には作業を完遂していた（コード修正 → PR → CI → マージ → 本番検証まで）
• しかしタイムアウトで強制 kill され、一括出力は1バイトも届かなかった
• 結果、ログには timeout | 45分 | (取得できず) だけが残った
• 人間から見ると「夜間に何かやったのか分からない」＝成果ゼロと区別できない

さらに悪いことに、kill 直前に子がやっていたのは 「外部の定期ジョブの完了を55回ポーリングして待つ」だった。 作業ではなく待機でタイムアウトを使い切っていた。

事故B: 実行されるコードが「その瞬間の HEAD」で決まっていた

スケジュールタスクが、人間が日常的に使う作業ツリーの中のスクリプトを直接実行していた。 その作業ツリーは複数の作業者・複数のエージェントセッションが共有し、ブランチを切り替えている。

• 定期実行の時刻に HEAD が誰かの作業ブランチ（本流より古い）になっていた
• そのファイルは未コミットで編集途中だった
• → 本流にマージ済みの修正は実行に入らず、代わりに他人の作業中コードが走る寸前だった

配信されるコードを決めていたのは「マージ」ではなく「その瞬間の HEAD」。 CI もコードレビューも無関係に迂回される。

---

実装すること

1. 「kill されても残る」進捗ファイルを必ず持たせる

一括出力（stdout / 終了時サマリ / 終了時 webhook）だけに頼る設計は禁止。

親が子を起動する前に、進捗ファイルのパスを確定させて子に渡す
  runs/<日付>-<連番>.summary.md

• 連番の確保は起動前に行う。空ファイルを排他フラグ付き（wx 相当）で作って番号を所有する。 終了後に空き番号を探す実装だと、並行実行で衝突するうえ「kill されたら番号すら決まらない」。
• 子への指示に次を明記する:
  • 節目ごと（着手 / 中間成果 / 検証結果 / 残ったこと）に追記する
  • このファイルだけは強制終了されても残るので、やったことは必ずここに書く
  • 追記であること（全文上書き禁止）
• 親は子の終了後に必ずこのファイルを読み、通知本文に載せる（長すぎる場合は先頭 N 文字で切る）。
• 成果物の識別子（PR番号・発行ID・URL）を通知に載せるなら、 一括出力と進捗ファイルの両方から抽出する。片方だけだと kill 時に消える。

2. 「待機で持ち時間を使い切る」を禁止する

子への指示に上限を明記する。

• 外部の定期ジョブ（cron / スケジュール実行）の完了待ちポーリングは N 分（例: 5分）まで
• それを超える待ちが必要なら、待たずに次を行って終了する:
  1. 進捗ファイルに「検証は次回実行時に行う」と書く
  2. TODO リストの先頭に検証だけの1件を積む
• タイムアウトの T 分前（例: 10分前）にまとめ処理へ入るよう指示する （進捗ファイルの追記と TODO 更新を、打ち切られる前に済ませる）
• 親はタイムアウト値を子への指示に数値で埋め込む。子が自分の持ち時間を知らないと配分できない。

3. 一括出力が失われても実行の痕跡を特定できるようにする

多くのエージェント実行基盤は、実行ログを <ログ置き場>/<作業ディレクトリから導いたキー>/<実行ID>.<拡張子> のような場所に残す。 一括出力から実行IDが取れなかった場合は、ファイルシステム側から復元する。

候補 = ログ置き場の該当ディレクトリ内のファイルのうち
       「作成時刻(birthtime)」が [開始時刻 - 猶予, 終了時刻 + 猶予] に入るもの

• 更新時刻(mtime)で判定してはいけない。 並行して動いている別セッションのログを誤って掴む。 「その実行中に新規作成されたファイル」だけが候補になる = 作成時刻。
• ファイル名の形式（UUID 等）でフィルタし、候補が複数なら最も新しいものを採る。
• 例外は握りつぶして空を返す。復元の失敗で無人ジョブ本体を落としてはいけない。
• どの経路で得た値かを記録に残す（source: "stdout" | "recovered" | ""）。 後から「復元に頼った回がどれだけあるか」を数えられる。

4. 実行経路をブランチから切り離す（事故B の構造的対策）

定期実行が読むスクリプトは、人がブランチを切り替えるツリーに置いてはいけない。

専用の固定チェックアウトを作り、スケジューラはそこだけを見る。

初回:   git worktree add --detach <固定tree> origin/<本流>
毎回:   git -C <共有クローン> fetch origin <本流>
        git -C <固定tree> checkout --detach origin/<本流>
        git -C <固定tree> reset --hard origin/<本流>
        git -C <固定tree> clean -fd
        <固定tree> のスクリプトを起動

守るべき点:

• 共有クローンに対しては fetch しかしない。 checkout / pull / reset は 他の作業者・他セッションの HEAD を奪う。fetch は作業ツリーも HEAD も変えないので安全。
• 必ず --detach。 ブランチを占有すると共有側で同じブランチを checkout できなくなる。
• reset の前に checkout --detach を置く。 前回の実行が作業ブランチを checkout したまま終わっていると、 reset --hard はそのブランチの ref ごと動かしてしまう。detach が先なら巻き込まない。
• 更新に失敗しても、固定tree が既にあるなら古いままで実行する。 ネットワーク断で定期実行が丸ごと消えるほうが損失が大きい。警告だけ出して続行する。
• 用意できたかの判定は「ディレクトリの有無」ではなく「起動対象ファイルの有無」。 worktree の作成が途中で失敗すると空ディレクトリだけ残り、ディレクトリ判定を素通りする。
• 副作用として、固定tree が「スクリプトの基準ディレクトリ」になる。 自分の位置から基準を求める実装（path.resolve(<このファイルのディレクトリ>, '..') 等）なら 自動的に固定tree を指すので追加の設定は不要、かつ人の作業ツリーとファイルを取り合わなくなる。
• ランチャー自身も固定tree の中に置く。毎回 reset --hard されるのでランチャーが自己更新する （一度スケジューラに登録したら、以後の改修は本流にマージするだけで届く）。

5. 無人実行の「後片付け」を明示的に行う

対話 UI の「セッションを閉じる」操作は無人実行には存在しない。ログが溜まり続ける。

• 実行ログの掃除機構があるなら、完走した実行だけを「閉じた」として登録する。
• タイムアウト・失敗した実行は残す。 退避してしまうと、途中まで進んだ作業を 後から再開・追跡できなくなる。失敗こそ残す価値がある。
• 台帳ファイルへの追記は必ず 読み直してからマージする（read-modify-write の lost update 対策）。 並行して別プロセスが別IDを追記していても失わない。一時ファイルへ書いて rename で置換する。

---

テストで固定すべき観点

副作用のない純関数（コマンド列を「組み立てるだけ」で実行しない関数）に切り出して検証する。

1. 共有クローンに対して fetch 以外の更新操作を計画しないこと （checkout / pull / reset / clean が共有クローンを対象に現れない）
2. 固定tree に対するコマンド順が checkout → reset → clean であること（順序で固定する）
3. worktree 追加時に --detach が必ず付くこと
4. 実行時間窓の外に作られたログファイルを復元候補にしないこと （一時ディレクトリに実ファイルを作って作成時刻で検証する）
5. 更新に失敗しても固定tree があれば子を起動すること（実行関数を注入して失敗させる）
6. 台帳追記が既存の値を保持し、同じ値を二重登録しないこと
7. 壊れた台帳ファイルでも例外を投げず、正しい形で作り直すこと

合成フィクスチャだけで緑になっても信用しない。 実物のログディレクトリを1回食わせて 「実際の1件を正しく特定できるか」を目で確認する。合成データは「実物では0件」を隠す。

---

完了条件（これを満たすまで「直した」と言わない）

• 子を強制終了させても、進捗ファイルに「どこまで進んだか」が残る
• 通知に進捗ファイルの本文と成果物の識別子が載る（一括出力が空でも）
• 実行IDを一括出力なしで特定でき、実データ1件で照合済み
• スケジューラが実行するファイルが、誰の作業状態にも依存しない
• 共有ツリーの HEAD・ブランチ・未コミット変更が一切変わらないことを実測で確認
• ランチャーが自分自身を最新版へ更新することを実測で確認

---

一般則（他の無人ジョブにも効く）

「このジョブが実行するファイルは、誰かの手元の状態で変わりうるか？」 変わりうるなら、そのジョブは検証されていない。

「このジョブが kill されたら、何が残るか？」 「何も残らない」なら、成果ゼロと成功が区別できない設計になっている。