地方の魚卸会社がClaude Codeエージェントの死活監視（watchdog）を実装した記録

• URL: https://zenn.dev/manahazime/articles/claudecode-agent-watchdog
• 日付: 2026-06-18
• Tier: Tier 3
• 要旨: 大分県の魚の卸売会社が、複数台PCで常時稼働するClaude CodeエージェントのためにPython製watchdogを実装した実機記録。エージェントの「固まり方」を(A)サイレントハング（プロセス生存・無応答）と(B)明示的サーバーエラー（Stream idle timeout等）の2種に分類し、前者は自動再起動・後者は人にエスカレートという設計が肝。昨夜の実際の事故（5時間停止）の一部始終を開示している。

詳細

死活監視の設計方針

PIDの生死ではなく、agentのtranscriptファイルの最終更新時刻（mtime）を監視する。エージェントが何かをするたびにログが書き込まれるため、mtimeが止まったら「固まっている」と判定できる。プロセスIDが変わる手動再起動でも検知できる点が利点。

復帰の段階

1. NUDGE（小突き）×3: 入力を送って反応を促す。一時的な詰まりはこれで戻る。
2. 判定: (A)サイレントハングなら自動再起動、(B)明示的サーバーエラーなら無駄打ちせず担当者へメール通知。
3. ESCALATE: 「機械では直せない」と判断したら人に渡す。

昨夜の事故の一部始終（実機記録）

• 20:44: 1台がStream idle timeoutで停止 → 小突き1発で20:47自動復帰
• 20:51: 同エラーが再発 → 3回小突きも戻らず
• 20:59: サーバーエラーと判定 → 再起動スキップ、担当者へメール通知
• 翌02:05: 担当者が手動でEnter1回 → watchdogがログ前進を検知し自動クローズ

5時間停止は設計通りの動作。サーバー側エラーは機械が再起動しても直らないため、無駄打ちせず人を待つ。

実装上の注意点

• read-timing artifact: 別マシンから監視ログを読みに行ったとき、書き込み直前のタイミングと重なると「止まって見える」。1回読んで止まって見えただけを故障の証拠にしない。
• 監視役は別マシンに置く: 被監視対象と同じマシンに置くと、マシンごと落ちたら道連れになる。独立した2経路で確認して「確定」とする。