この記事は note / Zenn にも同じ内容で公開しています（筆者本人による転載）。

前の記事で、AIエージェントを17時間回した実測を書きました。その最後に「見張りスクリプト、状態ファイルの設計、判断待ちの出し方は別の記事に書く」と約束したので、それを書きます。

動くコードごと出します。

まず、なぜ書くことになったか

長時間かかるジョブ（データ収集、学習、バッチ）をAIエージェントに走らせていました。私は別の作業をしながら、定期的に状態を見る監視をひとつ立てていました。

途中で、その監視が不要になったと判断して止めました。

その34分後にジョブが落ちました。誰も気づきませんでした。

次に気づいたのは57分後です。

原因は単純でした。

監視を止めた本人が、「見る責任」を誰にも渡していなかった。

**人が見張りを持つと、その人が止めた瞬間に、見る目そのものが消えます。**しかも消えたことに誰も気づきません。監視は「止めました」というログを残して、静かに終わるからです。

**だから見張りは機械に持たせます。**以下がその実装です。

① 「動いている」と「進んでいる」を分ける

最初に作った版は、プロセスが生きているかだけを見ていました。それでは足りません。

プロセスは生きている + 進んでいる    → 正常
プロセスは生きている + 進んでいない  → **固まっている**（これを見逃す）
プロセスは死んでいる + ロックは残る  → **後続が永久に待つ**
プロセスは動いていない + 動くべき    → **落ちたことに誰も気づいていない**

4つ目が57分の空白の正体です。「動いていない」だけでは異常か正常か決まりません。「動くべきなのに動いていない」を判定できないと、落ちたことに気づけません。

状態をこう分けました。

if holds and alive is False:
    state = "DEAD_LOCK_STALE"   # ロックはあるがプロセスは死んでいる
elif holds and stalled:
    state = "STALLED"           # 生きているが進んでいない
elif holds:
    state = "RUNNING"
else:
    state = "NOT_RUNNING"

## 「動いていない」だけでは足りない。**動くべきかを別に判定する**
sr, why = _should_run(job, lock)
if state == "NOT_RUNNING" and sr:
    state = "SHOULD_BE_RUNNING"

SHOULD_BE_RUNNING を足したことが、この実装でいちばん効きました。

② 進捗の出所を、1つに決めない

これはこの記事を書いている当日に見つけた欠陥です。

進捗の古さを、こう測っていました。

## 悪い実装
return file_age_sec(job.get("progress_file") or job.get("log"))

or が問題でした。progress_file があるとき、log は「予備」ではなく**「使わない」**になります。

実際に何が起きたか。

progress_file   処理が1件終わるごとに追記される。平均26秒間隔
                → ただし**大きい入力を処理中は5分を超える**
log             30秒ごとに件数を出力
                → **明確に生きていた**

停止とみなす閾値は300秒でした。進捗の古さは303秒と出ました。

健全なジョブが「停止」と判定される寸前でした。

直した版:

def _progress_age(job):
    """**進捗の出所は1つに決めない。生きている証拠が1つでもあれば生きている。**

    粒度の粗い出所だけを見ると、偽の停止が出る。
    利用できる出所すべてのうち、**最も新しいもの**を採る。
    """
    ages = []
    if job.get("progress_table"):
        ages.append(_db_progress_age(job["progress_table"]))
    for key in ("progress_file", "log"):
        if job.get(key):
            ages.append(file_age_sec(job[key]))
    ages = [a for a in ages if a is not None]
    return min(ages) if ages else None

影響が非対称なことに注意してください。

このジョブは自動再起動を禁止していたので、機械が誤って再起動することはありませんでした。しかし「停止」の赤が出ると、見張りは新しい作業を投入しなくなります。

健全なジョブについた偽の赤が、無関係な作業まで止めます。

③ プロセスの生死を、正しく測る

Windows で os.kill(pid, 0) を生存確認に使ってはいけません。

Unix では signal 0 は「何もしない」ですが、Windows の os.kill は TerminateProcess を呼びうるため、確認するつもりで殺します。

def _pid_alive(pid):
    """Windows で pid の生存を見る。**os.kill は使わない**"""
    if not pid:
        return None
    try:
        import ctypes
        k = ctypes.windll.kernel32
        h = k.OpenProcess(0x1000, False, int(pid))   # QUERY_LIMITED_INFORMATION
        if not h:
            return False
        code = ctypes.c_ulong()
        ok = k.GetExitCodeProcess(h, ctypes.byref(code))
        k.CloseHandle(h)
        return bool(ok) and code.value == 259        # STILL_ACTIVE
    except Exception:
        return None

戻り値を3値にしています。True / False / None（判定できなかった）。

**「判定できなかった」を False に丸めないでください。**丸めると、確認に失敗しただけのジョブを「死んだ」と扱い、再起動して二重に走らせます。

④ 状態ファイル ― 何を宣言させるか

**ジョブごとに「進んでいる証拠がどこに出るか」が違います。**それを見張り側にハードコードすると、ジョブが増えるたびに見張りを直すことになります。

宣言させます。

jobs:
  - id: collect_raw
    name: 生データの一括取得
    owner: data-team
    log: /var/log/collect.log
    progress_file: /data/raw/_manifest.jsonl
    stall_sec: 300
    expected_total_files: 5121

    # **機械が再開してよいか。既定は false**
    auto_restart: false
    auto_restart_blocked_reason: >-
      サーバ側エラーの原因が未特定。原因を見ずに再開すると、
      配信側の異常を「順調」と読み続けることになる。

    # **「走るべきなのに走っていない」を機械が判定するための条件。**
    # 機械が評価できるものだけを書く
    should_run_when:
      - not_complete        # 進捗の行数 < 期待総数
      - resource_free       # 排他資源を生きたプロセスが握っていない

設計の要点は1つです。

should_run_when を書けないジョブは、見張りが「落ちた」と判定できない。

だから**書けないジョブは登録させません。**登録の条件にすることで、「見ているつもり」の状態がなくなります。

⑤ 機械が再開してよい条件、いけない条件

ここが最も間違えやすいところでした。

私は一度、サーバ側エラーで落ちたジョブを**自動で再開する設計にしていました。**壊れた入力を飛ばして続行する、という実装です。

もし自動で再開していたら、飛ばした期間は永久に欠測になっていました。

原因を調べる過程で、使っていたSDKに**「壊れたキャッシュを削除する関数」**があることが分かりました。**削除すれば次回に再取得されます。**つまり正しい復旧は「飛ばす」ではなく「消して取り直す」で、欠測は出ませんでした。

人を挟んで遅れる      数十分〜半日
挟まずに間違える      **復旧不能な欠測**
                      配信側の異常を「順調」と読み続ける

後者のほうが高くつくので、迷ったら人を挟みます。

**「早く再開する」ことと「正しく再開する」ことは別です。**自動再開で得られたのは数十分の短縮、失うところだったのは復旧可能なデータそのものでした。

規則にしました。

機械が再開してよいのは
  ・**原因が特定済みで、対処が手順として確定している**
  ・かつ設定に auto_restart: true と、その根拠が書かれている
  ・かつ 1日の再開回数に上限がある（既定6回）

それ以外は、見張りは「再開が必要」と表示して**止まる。**

「繰り返し落ちている」は、手順ではなく原因を見るべき合図です。

⑥ 判断待ちの出し方

見張りが見つけたものを、全部その場で人に投げると、人が見なくなります。

指示の順番を固定しました。

RESTART  →  RED  →  STALE  →  DISPATCH

赤（検査の失敗）があるうちは、新しい作業を投入しません。

**検査を書くこと自体は事故を防ぎません。赤を放置しないことだけが防ぎます。**赤があるまま次を積むと、赤は「いつもの表示」になって消えます。

人に上げるものも絞りました。

即時に上げる（これだけ）
  ① 人の操作でしか進まないもの
  ② 不可逆な操作の直前（削除・上書き・公開・送信・課金）
  ③ 守るべき規則が破れている状態を見つけたとき
  ④ 止まっていて、機械では再開できないとき

それ以外   ファイルに溜めて、1日1回まとめて出す

判断待ちを随時投げると、人の時間が細切れになって、結局どれも決まりません。

まとめ

① 「動いている」と「進んでいる」を分ける
   さらに「動くべきなのに動いていない」を別に判定する
② 進捗の出所は1つに決めない。**最も新しいもの**を採る
③ 生死は3値（生・死・不明）。不明を死に丸めない
④ 「進んでいる証拠がどこに出るか」はジョブに宣言させる
   宣言できないジョブは登録させない
⑤ 機械が再開してよいのは、原因が分かっていて手順が確定している場合だけ
⑥ 赤があるうちは新しい作業を投入しない

**この6つは、全部いちど失敗してから足したものです。**最初から思いついたものは1つもありません。

そして、いちばん大事なのはこれでした。

見張りは機械が持つ。人が持つと、その人が止めた瞬間に消える。

**人が持つべきなのは判断だけです。**生成はAIに、検証と見張りは機械に、判断を人に。

この連載

AIエージェントを実際に回して、かかった費用と壊れた箇所を測って書いています。推測は書きません。実測値だけです。

Claude Code のトークン使用量を実測したら1ターン23万 ― 節約に効いたのは「セッションを切る」だった
https://qiita.com/manabu49-ai/items/2598a30d5140e4445ab6
本記事 ― 57分間、死んだジョブを誰も見ていなかった ― AIエージェントの見張りを機械に渡す
AIに100通り試させたら、効果ゼロなのに5個が「有意」だった
https://qiita.com/manabu49-ai/items/397a018948e1ab7ef29e
仕様書は2日前から手元にあった ― 読まずに実装した対処が、データを永久に失う設計だった
https://qiita.com/manabu49-ai/items/9b947604d3dc4958fa36
次 ― AI初心者が3日でエージェントを24時間回すまで（未公開）

番外 ― Claude のモデル提供終了、猶予は告知から約60日 ― 過去9回を数えて、手元を検査するスクリプトを書いた
https://qiita.com/manabu49-ai/items/bc2a7be2a6ee4ceb6185

**無料記事は結論まで全部書きます。**出し惜しみはしません。

この記事は note / Zenn にも同じ内容で公開しています（筆者本人による転載）。