build-watchdog

name	build-watchdog
description	Change-gated progress monitor for long-running builds. Watches one canonical progress file (markdown task list) and only texts the operator on a real event — milestone completed, blocker appeared, build finished, or a stall — instead of a dumb clock that pings every N minutes. Use to babysit a long build/task without notification noise, or to replace a FREQ=MINUTELY check-in automation.
compatibility	Created for Zo Computer
metadata	{"author":"marlandoj.zo.computer","version":"1.0.0","category":"ops"}

Build Watchdog

A quiet babysitter for long-running work. Point it at one progress file; it notifies the operator only when something material changes — never on a fixed clock.

Why this exists

The instinctive way to monitor a long build is a FREQ=MINUTELY;INTERVAL=30 automation that texts "is this done yet?" every half hour. That fires whether or not anything happened, and each fire is a full chat session. This skill inverts it: a scheduled agent still wakes on a cadence, but watchdog.ts is the gate — it diffs the progress file against the last-seen snapshot and stays SILENT unless there's real news. You can therefore run it on a tight cadence cheaply, because most fires send nothing.

How it works

1. The script reads the progress file (any markdown with GFM task lists).
   • - [x] = done, - [ ] = pending.
   • Lines containing BLOCKED / ERROR / FAILED / ❌ = blockers.
   • status: complete, ✅ complete, or all boxes checked = build complete.
2. It compares to a state file (.watchdog-state.json, written next to the progress file).
3. It prints a JSON verdict and exits. It performs no side effects itself.
4. The calling agent reads verdict.notify; if true, it sends verdict.message via SMS.

Verdict reasons: COMPLETE, MILESTONE, BLOCKER, REGRESSION, STALL, BASELINE (first run / --reset, silent), MISSING (file gone, one-shot), SILENT (nothing to report).

Notify discipline (built in): the first run is a silent baseline (no spam on attach); each new milestone notifies once; completion notifies once; a stall notifies once until progress resumes.

Run it (single build)

bun /home/workspace/Skills/build-watchdog/scripts/watchdog.ts \
  --progress /home/workspace/Projects/<name>/PROGRESS.md \
  --label "<Name> build" \
  --stall-min 45

--help documents all flags. Use --reset to re-baseline (e.g. when starting a new build that reuses the same progress file). --stall-min 0 disables stall detection.

Auto-discovery — the standing sentinel (recommended, zero setup)

scripts/watchdog-sweep.ts removes the manual "point it at a file" step. It globs for PROGRESS.md files under /home/workspace/Projects, keeps only the ones modified within --fresh-hours (default 24 — i.e. an active build), runs watchdog.ts against each, and prints a combined manifest:

bun /home/workspace/Skills/build-watchdog/scripts/watchdog-sweep.ts --fresh-hours 24 --stall-min 45
# → { checked, active: [...], notifications: [{ label, reason, message }], ts }

This is wired as a standing automation so long sessions become self-monitoring with nobody asking for it:

• Automation: [SYS] Sweep Build Watchdogs, FREQ=MINUTELY;INTERVAL=15, Haiku, no auto-delivery. It runs the sweep and sends an SMS for each notifications entry; empty → silent.
• Behavioral rule (the glue): on any long/multi-phase build the agent writes & maintains a PROGRESS.md in the project dir. The sweep then discovers it automatically. A finished or abandoned build drops off the sweep once its file stops changing (or it's marked complete).

A new build that drops a fresh PROGRESS.md is picked up within 15 min, watched until complete, and forgotten afterward — no per-build wiring, no cleanup beyond deleting the build's state file.

Wiring a dedicated single-build agent (optional)

Create an automation (per the operator naming + invariant conventions) whose prompt is roughly:

Run the build-watchdog skill against <progress path> with label "". The script prints a JSON verdict. If notify is true, send message to me via SMS. If notify is false, do nothing and end the turn silently. If reason is COMPLETE, also remind me this watchdog can be deleted.

• Title convention: [SYS] Watch <X> Build.
• Model: Haiku 4.5 (set the agent to your own low-cost byok model id) — the judgment lives in the script, so the agent only needs to relay.
• Prefix the command with source /root/.zo_secrets && and wrap work in agent-logger.ts start/log per the operator invariants.
• A cadence of every 10–15 min is fine and cheap, because silent fires cost almost nothing and send no SMS.
• Delete the automation when the build is COMPLETE (the message reminds you).