job-babysitter

ジョブの見守り役

目的

長時間実行されるバックグラウンドジョブを手動で何度も確認するのをやめましょう。完了を推測しながらls -lhやpsで何十回、何百回と確認する代わりに、バックグラウンドの監視プロセスを1つ起動します。このプロセスは、停滞のヒューリスティクスを使って終端状態を検出し、判定結果（完了、要対応、またはブロック）と、次に実行する正確なコマンドを通知します。

バックグラウンドジョブの夜勤看護師のようなものです。スケジュールに従ってバイタルを確認し、実際に問題がある場合にのみエスカレーションします。

使用する場面

手動で見守ると注意力が無駄になるほど長時間実行されるジョブに使用します。

• メディアのエンコード／トランスコード（ffmpeg、video-transcribe、音声抽出）
• 埋め込みやベクトルDBの構築（qmd embed、インデックス構築）
• バックグラウンドで実行するバッチエージェント／LLMパイプライン
• ハングしやすいブラウザー／スクレイピングデーモン（real-browser、agent-browser）

数秒で完了するジョブや、単一のBash呼び出しですでに結果が返るジョブには使用しないでください。

基本方針：薄く保ち、ハーネスに頼る

このスキルはClaude Code独自のプリミティブを調整するものであり、それらを再実装しないでください。

• **run_in_background: true**を指定して監視プロセスを起動します。監視プロセスが終了すると、ハーネスがエージェントを自動的に再呼び出しするため、手動のポーリングループは不要です。
• 監視プロセス（scripts/watch_job.py）が決定論的な処理を担います。バックオフしながらポーリングし、停滞を検出し、完了と停止状態を区別して、判定結果のJSONを出力します。
• このスキルの価値は、ジョブタイプごとのヒューリスティクス、安全な復旧手順、通知の振り分けにあります。これらはすべてreferences/playbook.mdに記載されています。

ワークフロー

1. ジョブのシグナルを特定する

監視できるものを、信頼性の高い順に確認します。

• PID — プロセスID（最も信頼性の高い完了シグナル）。ジョブの起動時、pgrep、またはpsから取得します。
• 出力ファイル — ジョブの進行に合わせて大きくなるファイル（例：ffmpegの出力先）。
• ログファイル — 追記されるログ（例：埋め込みの進行状況ログ）。

特定のジョブタイプ（ffmpeg、embed、batch、browser）に適したフラグを選ぶには、references/playbook.mdの「ジョブタイプごとの完了ヒューリスティクス」を読んでください。

2. 監視プロセスをバックグラウンドで起動する

run_in_background: trueを指定して実行します。PIDが分かっている場合は必ず--pidを渡し、補強材料としてファイル／ログのシグナルも追加します。判定結果は既知のパスに書き込みます。

scripts/watch_job.py \
  --label "lab05 stream encode" \
  --pid <PID> \
  --output-file /path/to/output.mp4 \
  --plateau-bytes 65536 --plateau-polls 5 --stuck-after 120 \
  --max-wait 7200 \
  --verdict-out /tmp/job-babysitter-<label>.json

監視プロセスはポーリングごとに1行のJSONハートビートを出力します（進行状況をリアルタイムで確認するには末尾を追跡します）。終了時には最終判定結果のJSONを--verdict-outに書き込みます。

調整方法はプレイブックに記載されています。適切なデフォルト値は、--interval 10（最大60までバックオフ）、--plateau-polls 4、--stuck-after 300、--max-wait 7200です。

3. 監視プロセスの終了後、判定結果を読み取って振り分ける

バックグラウンドの監視プロセスが終了すると、ハーネスがエージェントを再呼び出しします。判定結果のJSONを読み取ってください。statusには{done, needs-attention, blocked}のいずれかが入り、reason、suggested_next、経過時間、最終サイズが含まれます。

• done → 出力が実際に有効か確認し（プレイブックのジョブタイプ別「完了チェック」を参照。例：メディアならffprobe、埋め込みなら件数の一致を確認）、元のタスクを続行します。
• needs-attention → ジョブが実行中のまま停滞しました（ウェッジ状態の可能性があります）。復旧手順に従って、まず読み取り専用の方法で診断します。ユーザーに確認せずに、プロセスの強制終了や破壊的な復旧（pkill、WALチェックポイント、VACUUM）を行わないでください。
• blocked → --max-waitを過ぎたため、監視プロセスが待機を断念しました。正直に「待機を打ち切りました」と報告してください。「待機を打ち切った」ことは「失敗した」ことを意味しません。再確認するか、上限を延長するかを提案します。

4. 選択されたチャネルで通知する

デフォルトではセッション内で再開します。ユーザーがチャネル（Telegram、音声／TTS、デスクトップ通知）を選んだ場合は、references/playbook.mdの「通知の振り分け」に従って通知します。ステータスの絵文字、ラベル、経過時間、次に実行する正確なコマンドを必ず含めてください。

ガードレール（必ず守ること）

• 単発のポーリングが遅かっただけで行動しないでください。 「停止した」と判断するには、停滞に加えて --stuck-after で指定された時間を超過している必要があります。ウォッチャーは needs-attention を返す前に、すでにこの条件を適用しています。
• 破壊的な復旧を行う前に、必ず確認してください — pkill、kill、WAL チェックポイント、VACUUM、デーモンの再起動です。まず読み取り専用で診断してください。
• 正直に報告してください。 完了、「待機を諦めた」、そして「応答不能」を区別してください。ウォッチャーが確認していない成功を示唆してはいけません。
• 短い間隔で繰り返しポーリングせず、間隔を徐々に延ばしてください — これはウォッチャーが処理します。手動の高速ポーリングループでウォッチャーを囲んではいけません。

リソース

• scripts/watch_job.py — バックグラウンドウォッチャー：停滞検知、停止と完了の判定、判定結果の JSON。標準ライブラリのみを使用し、Python 3.11 以降が必要です。
• references/playbook.md — ジョブタイプごとの完了判定基準、安全な復旧方法の表、通知ルーティングが記載されています。ウォッチャーのフラグを選ぶとき、または needs-attention／blocked の判定に対処するときに読み込んでください。