# 無人実行ジョブが「働いたのに何も残らない」を潰す設計 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 されたら、何が残るか？」** > 「何も残らない」なら、成果ゼロと成功が区別できない設計になっている。 ---