/watch (bro)
All mechanics live in the bro CLI. This skill is policy only — the
arming decision (when a session should run a watcher) lives here, the
snapshot mechanics live in bro review watch.
Prereq: bro on PATH or npx -y @broject/bro@0, bd initialized.
Commands
| Command |
What it does |
bro review watch [--once] |
One snapshot — the heartbeat call: attention list + open molecules + act gates per fleet PR + fleet rows |
bro review watch --every N --for S |
The session pulse — tick the snapshot every N seconds: holds <git-common>/bro/pulse.lock (one per repo, a duplicate stands by), refuses under BRO_AGENT_ID; --for is required for a session-owned pulse — the window's exit is the session's wake event; omitting it leaves an unbounded watcher only an external supervisor may own |
bro review watch --notify |
Drop the initial snapshot plus each transition into the mailbox (<git-common>/bro/notify/) — a notify connector drains it into the parent session |
bro review watch --json |
Machine-readable {ts, attention, mols, gates, fleet, janitor?} |
bro review watch install [--every N] [--print] |
Arm the session pulse — writes <git-common>/bro/pulse.json (the want-marker session-start rearms from) and strips any legacy systemd/cron entry; cadence is --every N or watch.intervalSec (default 60). No OS timer is installed |
bro review watch uninstall |
Disarm the marker + strip any legacy timer/cron entry; a live pulse exits on its own |
Every tick also rewrites <git-common>/bro/heartbeat.json — the durable
last-known-state file. Mailbox drops expire after ~1h; this file does
not, so overnight state is a read (bro fleet status row, session-start
context), never an inference from whether a session was polled.
Policy
- Read the attention list, not the table. The snapshot leads with
what needs a decision: ready human gates,
lost — respawn? agents,
blocked PR exit gates, failed gate probes. (quiet) means no
listed attention condition fired — not an all-clear: check the
degraded / unavailable / probe-failed lines before treating the
snapshot as healthy, and don't go hunting for work the heartbeat
didn't raise.
- The session owns the cadence — the attended leg is
bro pulse.
A live orchestrator session arms bro pulse <S> in a visible
background shell (the /pulse skill) — a continuous metronome whose
mailbox ticks are the wakes. The bounded form, bro review watch --every N --for S --notify (watch.pulseSec suggests the window,
default 900s), is the unattended leg — what the checkpoint respawns
from pulse.json when no session's pulse holds the lock. Never sit
in a foreground poll, never nohup an unbounded --every.
- Armed-but-dead rearms itself.
bro review watch install (and
every bro pulse start) writes bro/pulse.json — the durable
want-record. A session start (or post-compaction) that finds the
marker armed but no live pulse lock gets the rearm nudge; the
orchestrator re-arms the leg. OS timers are retired — systemd/crontab
installs no longer exist; install only strips the legacy entries
they left.
- Only orchestrators pulse. Sessions with
BRO_AGENT_ID set —
spawned workers — never see the nudge and get refused by bro pulse,
bro review watch --every, and bro review drive --every: recursion is
how the watcher tree multiplies.
--notify is how a watcher reaches its parent. With a notify
connector installed, mailbox drops surface mid-turn in the parent
session — the initial snapshot plus each transition. Dedup is
per-process.
- The mailbox is pull-based. A drop never wakes a sleeping
parent — it lands in context on the session's next tool call (the
postTool drain). The bounded window's end is the wake boundary;
between ticks, delivery follows the session's own tool cadence.
- Watch never touches your work. It never claims steps, never
mutates beads, never respawns agents — a
lost — respawn? row is the
decision surface; respawning is a manual act (bro fleet agents up <step>).
The writes besides --notify drops are the heartbeat file (each
tick's snapshot, atomically replaced) and the janitor: each tick
reaps dead session/agent state under <git-common>/bro/ (retention,
not workflow) and reports it in the attention list.
- Degraded is not dead. A backend whose
list() failed renders its
rows unknown, never lost — don't respawn on a failed read.
- Report progress in words, not IDs. When relaying snapshot state
to the user, translate every code:
bro-mol-3n2 → "the notify
connector molecule", bro-mol-0io → "the bro review watch molecule".
A status line must say what the agent is doing and what just
landed ("PR for X merged, session moved to Y") — bare mol/bead/PR
IDs alone are not a report. IDs may appear in parentheses.
- Never report a merge you didn't verify. A landed claim comes
from
gh pr view <N> --json state,mergedAt in hand — never from
memory, a worker's exit line, or another digest. What the probe
didn't confirm is reported as "unverified", not "merged".
- Report times only against a verified clock. The snapshot's
clock field is the tick's own check — skewed or error means
every stamp it carries (ages, merge times) is unverifiable and the
digest flags that instead of trusting the numbers.
Watchdog tick (lane watch between turns)
When a session supervises a lane over long windows (rate walls, model
resets, queue refills), each inspection is a bounded read-only tick —
usually a subagent handed the brief below — that reports facts and never
acts. The session chains the ticks; the tick itself only reads.
Read-only contract. bro/gh/ls/cat/tail/ps/stat/find/
date/sleep and systemctl --user is-active|show only. No kill,
start, restart or respawn — not even on a rate-limit: the tick says RATE-LIMIT: park (+reset …at HH:MM UTC) quoting the reset time from the error text, and
the operator acts. A spawn that died into a wall is normal
constatation, not a failure to fix.
Anti-fabrication. Every fact comes from command output produced
this tick — never from memory or the previous report. Sync clocks once
per snapshot (date -u vs the Date: header of a gh api response).
Merges, PR states and counts come only from gh output. The window's
boundary is the timeout, not what the tick meant to see.
PR counting and classification. Count with gh api 'search/issues?q=repo:{owner}/{repo}+type:pr+state:open&per_page=1' --jq '.total_count' — one call, exact even past 100 open PRs.
gh pr list silently truncates at --limit and gh api pulls
without per_page undercounts. Classify from gh pr list --state open --json headRefName --limit 1000: work/*, loop/*, stack/* and
fix/bro-* are ours (the fleet — FLEET_BRANCH_PREFIXES in
packages/cli/src/commands/drive.ts), everything else is foreign —
report two numbers (fleet merges / total). A fleet merge counts only
from gh's merged state, corroborated by the loop log's merge line —
never from a branch disappearing.
Baselines at tick start. Record before waiting: the exit-file
boundary (find <git-common>/bro/agents -name '*.exit' -newermt '<now>'),
the PR count, and the supervisor pids/unit. Worker logs are append-only —
an old rate line is history; a fresh wall must be dated after the
worker's spawn. Liveness is the run record or unit, never a grep over ps and never a
pidfile — the loop writes no loop.pid. Each
<git-common>/bro/loop/<slug>.json carries pid/pidStart, so
ps -p <pid> on the record's pid is the check (bro review watch
renders this same read — a record whose pid is gone is a crashed run's
residue). The supervisor itself holds bro/loop.lock (a lock, not a
pid). systemctl --user is-active <loop-unit> covers a unit-managed
loop; a climbing NRestarts means the auto-restart is working —
constatation, not an alarm.
Bounded wait. Poll 60–90 s (8–10 min across a long reset window)
and stop at the first of: a new exit file (classify rate vs clean code),
PR count changed (re-verify with numbers + branches), a supervisor down,
a new spawn in the loop log, or the budget. Sleep past a reset to
boundary + 30 s instead of hopping every minute. Answer: WAKE|TIMEOUT,
lane state, wake reason, PR count (+classification), anomalies — then
the next tick's plan carrying the new baselines. Cap refusals, foreign
devin sessions, ETIMEDOUT and store-sync warnings are background — never
a wake.
1---23name: watch4description: "Use when supervising parallel convoys/agents — 'watch the fleet', 'what needs attention', a monitor loop over mols/PRs, or a read-only watchdog tick over a lane ('watch the lane', rate walls, resets). Thin wrapper over the bro CLI: `bro review watch` is the deterministic heartbeat — one snapshot of molecules, PR exit gates, and the fleet. Requires `bro` (npx -y @broject/bro@0) and bd."5metadata:6 source: https://skillmd.com/skills/theplenkov/watch7---89# /watch (bro)1011**All mechanics live in the `bro` CLI.** This skill is policy only — the12arming decision (when a session should run a watcher) lives here, the13snapshot mechanics live in `bro review watch`.1415Prereq: `bro` on PATH or `npx -y @broject/bro@0`, `bd` initialized.1617## Commands1819| Command | What it does |20| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |21| `bro review watch [--once]` | One snapshot — the heartbeat call: attention list + open molecules + act gates per fleet PR + fleet rows |22| `bro review watch --every N --for S` | The session pulse — tick the snapshot every N seconds: holds `<git-common>/bro/pulse.lock` (one per repo, a duplicate stands by), refuses under `BRO_AGENT_ID`; `--for` is required for a session-owned pulse — the window's exit is the session's wake event; omitting it leaves an unbounded watcher only an external supervisor may own |23| `bro review watch --notify` | Drop the initial snapshot plus each transition into the mailbox (`<git-common>/bro/notify/`) — a notify connector drains it into the parent session |24| `bro review watch --json` | Machine-readable `{ts, attention, mols, gates, fleet, janitor?}` |25| `bro review watch install [--every N] [--print]` | Arm the session pulse — writes `<git-common>/bro/pulse.json` (the want-marker session-start rearms from) and strips any legacy systemd/cron entry; cadence is `--every N` or `watch.intervalSec` (default 60). No OS timer is installed |26| `bro review watch uninstall` | Disarm the marker + strip any legacy timer/cron entry; a live pulse exits on its own |2728Every tick also rewrites `<git-common>/bro/heartbeat.json` — the durable29last-known-state file. Mailbox drops expire after ~1h; this file does30not, so overnight state is a read (`bro fleet status` row, session-start31context), never an inference from whether a session was polled.3233## Policy3435- **Read the attention list, not the table.** The snapshot leads with36 what needs a decision: ready human gates, `lost — respawn?` agents,37 blocked PR exit gates, failed gate probes. `(quiet)` means no38 listed attention condition fired — not an all-clear: check the39 degraded / unavailable / probe-failed lines before treating the40 snapshot as healthy, and don't go hunting for work the heartbeat41 didn't raise.42- **The session owns the cadence — the attended leg is `bro pulse`.**43 A live orchestrator session arms `bro pulse <S>` in a visible44 background shell (the `/pulse` skill) — a continuous metronome whose45 mailbox ticks are the wakes. The bounded form, `bro review watch46 --every N --for S --notify` (`watch.pulseSec` suggests the window,47 default 900s), is the unattended leg — what the checkpoint respawns48 from `pulse.json` when no session's pulse holds the lock. Never sit49 in a foreground poll, never nohup an unbounded `--every`.50- **Armed-but-dead rearms itself.** `bro review watch install` (and51 every `bro pulse` start) writes `bro/pulse.json` — the durable52 want-record. A session start (or post-compaction) that finds the53 marker armed but no live pulse lock gets the rearm nudge; the54 orchestrator re-arms the leg. OS timers are retired — systemd/crontab55 installs no longer exist; install only strips the legacy entries56 they left.57- **Only orchestrators pulse.** Sessions with `BRO_AGENT_ID` set —58 spawned workers — never see the nudge and get refused by `bro pulse`,59 `bro review watch --every`, and `bro review drive --every`: recursion is60 how the watcher tree multiplies.61- **`--notify` is how a watcher reaches its parent.** With a notify62 connector installed, mailbox drops surface mid-turn in the parent63 session — the initial snapshot plus each transition. Dedup is64 per-process.65- **The mailbox is pull-based.** A drop never wakes a sleeping66 parent — it lands in context on the session's next tool call (the67 postTool drain). The bounded window's end is the wake boundary;68 between ticks, delivery follows the session's own tool cadence.69- **Watch never touches your work.** It never claims steps, never70 mutates beads, never respawns agents — a `lost — respawn?` row is the71 decision surface; respawning is a manual act (`bro fleet agents up <step>`).72 The writes besides `--notify` drops are the heartbeat file (each73 tick's snapshot, atomically replaced) and the janitor: each tick74 reaps dead session/agent state under `<git-common>/bro/` (retention,75 not workflow) and reports it in the attention list.76- **Degraded is not dead.** A backend whose `list()` failed renders its77 rows `unknown`, never `lost` — don't respawn on a failed read.78- **Report progress in words, not IDs.** When relaying snapshot state79 to the user, translate every code: `bro-mol-3n2` → "the notify80 connector molecule", `bro-mol-0io` → "the `bro review watch` molecule".81 A status line must say what the agent is _doing_ and what just82 _landed_ ("PR for X merged, session moved to Y") — bare mol/bead/PR83 IDs alone are not a report. IDs may appear in parentheses.84- **Never report a merge you didn't verify.** A landed claim comes85 from `gh pr view <N> --json state,mergedAt` in hand — never from86 memory, a worker's exit line, or another digest. What the probe87 didn't confirm is reported as "unverified", not "merged".88- **Report times only against a verified clock.** The snapshot's89 `clock` field is the tick's own check — `skewed` or `error` means90 every stamp it carries (ages, merge times) is unverifiable and the91 digest flags that instead of trusting the numbers.9293## Watchdog tick (lane watch between turns)9495When a session supervises a lane over long windows (rate walls, model96resets, queue refills), each inspection is a **bounded read-only tick** —97usually a subagent handed the brief below — that reports facts and never98acts. The session chains the ticks; the tick itself only reads.99100**Read-only contract.** `bro`/`gh`/`ls`/`cat`/`tail`/`ps`/`stat`/`find`/101`date`/`sleep` and `systemctl --user is-active|show` only. No kill,102start, restart or respawn — not even on a rate-limit: the tick says `RATE-LIMIT: park103(+reset …at HH:MM UTC)` quoting the reset time from the error text, and104the _operator_ acts. A spawn that died into a wall is normal105constatation, not a failure to fix.106107**Anti-fabrication.** Every fact comes from command output produced108_this tick_ — never from memory or the previous report. Sync clocks once109per snapshot (`date -u` vs the `Date:` header of a `gh api` response).110Merges, PR states and counts come only from gh output. The window's111boundary is the timeout, not what the tick meant to see.112113**PR counting and classification.** Count with `gh api114'search/issues?q=repo:{owner}/{repo}+type:pr+state:open&per_page=1'115--jq '.total_count'` — one call, exact even past 100 open PRs.116`gh pr list` silently truncates at `--limit` and `gh api pulls`117without `per_page` undercounts. Classify from `gh pr list --state open118--json headRefName --limit 1000`: `work/*`, `loop/*`, `stack/*` and119`fix/bro-*` are ours (the fleet — `FLEET_BRANCH_PREFIXES` in120`packages/cli/src/commands/drive.ts`), everything else is foreign —121report two numbers (fleet merges / total). A fleet merge counts only122from gh's merged state, corroborated by the loop log's merge line —123never from a branch disappearing.124125**Baselines at tick start.** Record before waiting: the exit-file126boundary (`find <git-common>/bro/agents -name '*.exit' -newermt '<now>'`),127the PR count, and the supervisor pids/unit. Worker logs are append-only —128an old rate line is history; a fresh wall must be dated after the129worker's spawn. Liveness is the run record or unit, never a grep over `ps` and never a130pidfile — the loop writes no `loop.pid`. Each131`<git-common>/bro/loop/<slug>.json` carries `pid`/`pidStart`, so132`ps -p <pid>` on the record's pid is the check (`bro review watch`133renders this same read — a record whose pid is gone is a crashed run's134residue). The supervisor itself holds `bro/loop.lock` (a lock, not a135pid). `systemctl --user is-active <loop-unit>` covers a unit-managed136loop; a climbing `NRestarts` means the auto-restart is working —137constatation, not an alarm.138139**Bounded wait.** Poll 60–90 s (8–10 min across a long reset window)140and stop at the first of: a new exit file (classify rate vs clean code),141PR count changed (re-verify with numbers + branches), a supervisor down,142a new spawn in the loop log, or the budget. Sleep past a reset to143boundary + 30 s instead of hopping every minute. Answer: `WAKE|TIMEOUT`,144lane state, wake reason, PR count (+classification), anomalies — then145the next tick's plan carrying the new baselines. Cap refusals, foreign146devin sessions, ETIMEDOUT and store-sync warnings are background — never147a wake.