All mechanics live in the bro CLI. This skill is policy only —
the pass logic, occupancy guard, and fixer spawn live in
packages/cli/src/commands/drive.ts.
bro review drive is the write-side counterpart of bro review watch's gates plane:
watch reports PR #N blocked — open_threads; drive acts on it. It
exists for the orphaned-PR gap — a convoy/loop session ends at PR-open,
and review threads that arrive afterwards have no owner.
What a pass does
For every open PR on a fleet branch (worktree branches + local
work/*, loop/*, stack/* branches):
| Gate says | Occupied? | Action |
|---|---|---|
open_threads > 0 |
yes | skip — the live owner works its own threads |
open_threads > 0 |
no | spawn/respawn the PR's fixer agent on its fixer bead (-l fixer, external_ref drive:pr:<N>) in the PR's worktree |
mergeable = CONFLICTING |
yes | skip — the live owner works its own conflicts |
mergeable = CONFLICTING |
no | spawn the same fixer agent with a rebase work order — fetch + rebase onto the PR's base, resolve, --force-with-lease push — bounded by the fixRounds > maxRounds cap |
gate.ok |
yes, fresh | report — the owner's merge step lands it |
gate.ok |
yes, silent past the TTL | adopt as an orphan → bro review act merge |
gate.ok |
no | bro review act merge, retire the worktree when clean, close the fixer bead |
| PR merged/closed | — | close a dangling fixer bead |
Occupancy = the agents facade + a live foreign watch marker on the PR
(a bro flow loop heartbeat, act wait, convoy — drive only owns
unsupervised PRs, so a live supervisor is an occupant) + the
worktree's own fresh claim marker (<gitdir>/bro/work, stamped by
bro work enter) + fresh .work markers + a /proc cwd scan that
follows a process's ancestry to an agent-shaped root — agent CLIs sit
at their launch dir while their tool shells hold the worktree cwd — or
matches a BRO_AGENT_ID/AI_AGENT env badge, which detached
descendants keep. Occupied is always the safe verdict.
The merge path is the one place occupancy ages out (bro-ihnlv): every
occupancy proof carries a last-proven-activity stamp — agent log mtime
or spawn record, marker mtime, the worktree's own churn — and a green
PR under an owner silent for drive.occupancyTtlSec (2h, floor 60s)
counts as orphaned: drive adopts it and merges rather than reporting
green-occupied forever. Freshness is judged on the freshest proof —
a stale fixer beside a live session still vetoes. Non-green verdicts
never age: an occupied thread/conflict PR stays occupied.
Commands
| Command | What it does |
|---|---|
bro review drive [--once] |
one supervision pass (default) |
bro review drive --every [N] |
a pass every N seconds — runs in-process, spawn it detached (nohup/tmux/daemon); a bare --every uses drive.intervalSec |
bro review drive --no-merge |
supervise only — never merge (config: drive.merge: "never") |
bro review drive --connector <name> |
spawn fixers on one backend |
bro review drive --json |
one JSON line per PR verdict |
bro review drive install [--every N] [--print] |
arm the merge path — writes bro/drive.json (the want-marker session checkpoints rearm a dead supervisor from) and brings bro fleet daemon up; cadence --every N or drive.intervalSec |
bro review drive uninstall |
disarm the marker + stop the supervisor |
Config: drive.intervalSec (300), drive.merge (auto|never),
drive.occupancyTtlSec (7200 — the merge-path activity bound).
The fixer agent's command resolves exactly like bro fleet agents up —
agents.<backend>.command → loop.agent.
Policy
- The orchestrator's pulse runs single passes. The session-pulse
model (bro-killn): a bounded
bro review watch --every --forwindow ends →bro review driveonce → digest → re-arm.bro review drive --everystays the long-lived detached supervisor when one is wanted — both--everyforms refuse underBRO_AGENT_ID(spawned workers never arm cadences). No systemd/crontab installs exist — a session start rearms a dead pulse frombro/pulse.json. bro review drive installis the always-on merge path. Armingbro/drive.jsonmakes supervision infrastructure, not an opt-in: session checkpoints rearm a dead supervisor on every lifecycle event (sessionStart + postTool, orchestrator-only).bro fleet daemon downunder an install is a transient stop — the next checkpoint brings it back;uninstallis the disarm.- Occupied is not an error. A skipped PR means a live session owns it — report and move on; never force-spawn into someone's worktree.
- The fixer bead is the handle.
bro fleet agents status <bead>shows the fixer,bro fleet agents down <bead>stops it (the fixer is a standalone task, not a molecule step —bro fleetdoesn't list it). A dead fixer respawns on the same agentId — that is the contract. - Merge is the exit gate's call, not the driver's.
bro review drivenever bypassesbro review act merge— a non-green PR is supervised, not forced.