Job Babysitter
Purpose
Stop manually polling long-running background jobs. Instead of dozens-to-hundreds of
ls -lh / ps checks while guessing at completion, start one background watcher that
detects the terminal state via plateau heuristics, then routes a verdict — done,
needs-attention, or blocked — with the exact next command.
A night-shift nurse for background jobs: it checks vitals on a schedule and escalates
only when something is actually wrong.
When to use
Use when a job will run long enough that babysitting it by hand wastes attention:
- Media encodes / transcodes (ffmpeg, video-transcribe, audio extraction)
- Embedding or vector-DB builds (qmd embed, index builds)
- Batch agent / LLM pipelines run in the background
- Browser / scrape daemons (real-browser, agent-browser) prone to hanging
Do NOT use for jobs that finish in seconds, or where a single Bash call already
returns the result.
Core principle: stay thin, lean on the harness
This skill orchestrates Claude Code's own primitives — do not reimplement them:
- Start the watcher with
run_in_background: true. When it exits, the harness
re-invokes the agent automatically — no manual polling loop needed.
- The watcher (
scripts/watch_job.py) owns the deterministic part: poll with backoff,
detect plateau, distinguish done from stuck, emit a verdict JSON.
- The skill's value is the per-job-type heuristics, the safe-recovery playbook,
and notification routing — all in
references/playbook.md.
Workflow
1. Identify the job's signals
Determine what can be watched, in order of reliability:
- PID — the process ID (most reliable completion signal). Get it from the job's
launch,
pgrep, or ps.
- Output file — a file that grows as the job progresses (e.g. ffmpeg target).
- Log file — a log that gets appended (e.g. an embed progress log).
Read references/playbook.md § "Completion heuristics by job type" to pick flags for
the specific job type (ffmpeg, embed, batch, browser).
2. Launch the watcher in the background
Run with run_in_background: true. Always pass --pid when known; add file/log
signals as corroboration. Write the verdict to a known path.
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
The watcher prints a one-line JSON heartbeat per poll (tail it for live progress) and
writes the final verdict JSON to --verdict-out on exit.
Tuning lives in the playbook; sensible defaults: --interval 10 (backs off to 60),
--plateau-polls 4, --stuck-after 300, --max-wait 7200.
3. On watcher exit, read the verdict and route it
The harness re-invokes the agent when the background watcher finishes. Read the
verdict JSON. It has status ∈ {done, needs-attention, blocked}, a reason,
suggested_next, elapsed time, and final size.
- done → verify the output is real (see the job-type "Done check" in the playbook,
e.g.
ffprobe for media, count match for embeds), then proceed with the original task.
- needs-attention → the job plateaued while still alive (possibly wedged). Follow
the recovery playbook: diagnose read-only FIRST. Never kill or run destructive
recovery (pkill, WAL checkpoint, VACUUM) without asking the user.
- blocked → the watcher gave up after
--max-wait. Report honestly: "gave up
waiting" ≠ "failed". Offer to re-check or extend the ceiling.
4. Notify per the chosen channel
Default to in-session resume. If the user picked a channel (Telegram, voice/TTS,
desktop notification), route per references/playbook.md § "Notification routing".
Always include the status emoji, label, elapsed time, and the exact next command.
Guardrails (non-negotiable)
- Never act on a single slow poll. "Stuck" requires plateau AND elapsed past
--stuck-after — the watcher already enforces this before returning needs-attention.
- Ask before any destructive recovery —
pkill, kill, WAL checkpoint, VACUUM,
daemon restart. Diagnose read-only first.
- Report honestly. Distinguish done from "gave up waiting" from "wedged". Never
imply a success the watcher did not observe.
- Poll with backoff, not tight loops — the watcher handles this; never wrap it in
a manual fast-polling loop.
Resources
scripts/watch_job.py — background watcher: plateau detection, stuck-vs-done logic,
verdict JSON. Stdlib only, Python 3.11+.
references/playbook.md — per-job-type completion heuristics, the safe-recovery
table, and notification routing. Load when picking watcher flags or handling a
needs-attention/blocked verdict.
1---
2name: job-babysitter
3description: This skill should be used to watch a long-running background job (ffmpeg/media encode, qmd or other embedding/vector-DB run, batch agent/LLM pipeline, or a real-browser/agent-browser daemon) until it finishes or wedges, then deliver a verdict (done, needs-attention, or blocked) plus the exact next command, without burning dozens of manual poll commands. Triggers on "babysit this job", "watch this until it's done", "ping me when the encode/embed/batch finishes", "is this background process stuck", "monitor this ffmpeg/qmd run", or any request to wait on a long-running process and be told when it's complete or hung.
4metadata:
5 source: https://skillmd.com/skills/glebis/job-babysitter
6---
7
8# Job Babysitter
9
10## Purpose
11
12Stop manually polling long-running background jobs. Instead of dozens-to-hundreds of
13`ls -lh` / `ps` checks while guessing at completion, start one background watcher that
14detects the terminal state via plateau heuristics, then routes a verdict — done,
15needs-attention, or blocked — with the exact next command.
16
17A night-shift nurse for background jobs: it checks vitals on a schedule and escalates
18only when something is actually wrong.
19
20## When to use
21
22Use when a job will run long enough that babysitting it by hand wastes attention:
23- Media encodes / transcodes (ffmpeg, video-transcribe, audio extraction)
24- Embedding or vector-DB builds (qmd embed, index builds)
25- Batch agent / LLM pipelines run in the background
26- Browser / scrape daemons (real-browser, agent-browser) prone to hanging
27
28Do NOT use for jobs that finish in seconds, or where a single `Bash` call already
29returns the result.
30
31## Core principle: stay thin, lean on the harness
32
33This skill orchestrates Claude Code's own primitives — do not reimplement them:
34- Start the watcher with **`run_in_background: true`**. When it exits, the harness
35 re-invokes the agent automatically — no manual polling loop needed.
36- The watcher (`scripts/watch_job.py`) owns the deterministic part: poll with backoff,
37 detect plateau, distinguish done from stuck, emit a verdict JSON.
38- The skill's value is the **per-job-type heuristics**, the **safe-recovery playbook**,
39 and **notification routing** — all in `references/playbook.md`.
40
41## Workflow
42
43### 1. Identify the job's signals
44Determine what can be watched, in order of reliability:
45- **PID** — the process ID (most reliable completion signal). Get it from the job's
46 launch, `pgrep`, or `ps`.
47- **Output file** — a file that grows as the job progresses (e.g. ffmpeg target).
48- **Log file** — a log that gets appended (e.g. an embed progress log).
49
50Read `references/playbook.md` § "Completion heuristics by job type" to pick flags for
51the specific job type (ffmpeg, embed, batch, browser).
52
53### 2. Launch the watcher in the background
54Run with `run_in_background: true`. Always pass `--pid` when known; add file/log
55signals as corroboration. Write the verdict to a known path.
56
57```bash
58scripts/watch_job.py \
59 --label "lab05 stream encode" \
60 --pid <PID> \
61 --output-file /path/to/output.mp4 \
62 --plateau-bytes 65536 --plateau-polls 5 --stuck-after 120 \
63 --max-wait 7200 \
64 --verdict-out /tmp/job-babysitter-<label>.json
65```
66
67The watcher prints a one-line JSON heartbeat per poll (tail it for live progress) and
68writes the final verdict JSON to `--verdict-out` on exit.
69
70Tuning lives in the playbook; sensible defaults: `--interval 10` (backs off to 60),
71`--plateau-polls 4`, `--stuck-after 300`, `--max-wait 7200`.
72
73### 3. On watcher exit, read the verdict and route it
74The harness re-invokes the agent when the background watcher finishes. Read the
75verdict JSON. It has `status` ∈ {done, needs-attention, blocked}, a `reason`,
76`suggested_next`, elapsed time, and final size.
77
78- **done** → verify the output is real (see the job-type "Done check" in the playbook,
79 e.g. `ffprobe` for media, count match for embeds), then proceed with the original task.
80- **needs-attention** → the job plateaued while still alive (possibly wedged). Follow
81 the recovery playbook: diagnose read-only FIRST. **Never kill or run destructive
82 recovery (pkill, WAL checkpoint, VACUUM) without asking the user.**
83- **blocked** → the watcher gave up after `--max-wait`. Report honestly: "gave up
84 waiting" ≠ "failed". Offer to re-check or extend the ceiling.
85
86### 4. Notify per the chosen channel
87Default to in-session resume. If the user picked a channel (Telegram, voice/TTS,
88desktop notification), route per `references/playbook.md` § "Notification routing".
89Always include the status emoji, label, elapsed time, and the exact next command.
90
91## Guardrails (non-negotiable)
92
93- **Never act on a single slow poll.** "Stuck" requires plateau AND elapsed past
94 `--stuck-after` — the watcher already enforces this before returning needs-attention.
95- **Ask before any destructive recovery** — `pkill`, `kill`, WAL checkpoint, `VACUUM`,
96 daemon restart. Diagnose read-only first.
97- **Report honestly.** Distinguish done from "gave up waiting" from "wedged". Never
98 imply a success the watcher did not observe.
99- **Poll with backoff, not tight loops** — the watcher handles this; never wrap it in
100 a manual fast-polling loop.
101
102## Resources
103
104- `scripts/watch_job.py` — background watcher: plateau detection, stuck-vs-done logic,
105 verdict JSON. Stdlib only, Python 3.11+.
106- `references/playbook.md` — per-job-type completion heuristics, the safe-recovery
107 table, and notification routing. Load when picking watcher flags or handling a
108 needs-attention/blocked verdict.