pulse

/pulse (bro)

All mechanics live in the bro CLI. This skill is policy only — the metronome mechanics live in bro pulse, the snapshot shape in bro review watch.

Prereq: bro on PATH or npx -y @broject/bro@0.

Commands

Command	What it does
bro pulse [S]	The session metronome — a long-lived child: beats every S seconds (default watch.intervalSec, 60), prints each tick, and drops it into the mailbox as the pulse.lock holder. The mail IS the wake: a background child's exit reaches no one, so the tick's drop is the only channel that lands mid-turn
bro pulse [S] --no-notify	Stdout liveness only — no mailbox drops (default is --notify)
bro pulse [S] --json	One structured object per beat — {ts, …snapshot, pulse:{sec,mailing}}, or {ts,sec,cmd,code,stdout,stderr,mailing} for a probe
bro pulse [S] -- <cmd>…	The tick is <cmd> instead of the watch snapshot — stdout/stderr echoed verbatim; a failing probe is beat content, never a kill

Policy

• Arm it in a visible background shell — then let go. bro pulse 60 in an exec-background shell; each mailbox drop lands in context on your next tool call. Never sit in a foreground poll, never a hand-rolled while sleep — the beat is one bro command, one child, continuous ticks.
• On each drop: digest, don't babysit. Look at what matters NOW — bro status, bro review watch --once, the loop shell's output, act gates — post the digest, get on with the turn. The pulse keeps beating whether you look or not; silence in your mailbox is the alarm (a dead pulse drops nothing).
• Only orchestrators pulse. Sessions with BRO_AGENT_ID set — spawned workers — get refused (exit 2). A worker never arms its own cadence: recursive watchers are the chaos the guard prevents.
• One mailer per repo, no silent pulses. pulse.lock arbitrates who mails — never who ticks. A second bro pulse prints every beat (visible liveness) and mails nothing while the incumbent lives; it takes the role over the moment the incumbent dies. There is no 'standing by' silence.
• pulse.json is the durable want. Every start rewrites <git-common>/bro/pulse.json — the marker a session-start nudge reads: armed but no live lock → rearm the unattended leg (bro review watch --every S --for S --notify, the bounded fallback for when no session is attending). bro review watch uninstall disarms.
• Usable anywhere. Outside a repo there is no marker, no lock, no mailbox — the warning says so once and the metronome still beats on stdout. A pure timer with an optional point-check.
• Stop it by killing it. The pulse runs until the shell is killed — it never exits on its own. Disarming the marker (uninstall) stops future rearm, not the live child.
• Report progress in words, not IDs. Same rule as /watch — a digest says what an agent is doing and what landed, never bare mol/bead/PR IDs.