/drive (bro)
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 --for window ends →
bro review drive once → digest → re-arm. bro review drive --every stays the
long-lived detached supervisor when one is wanted — both --every
forms refuse under BRO_AGENT_ID (spawned workers never arm
cadences). No systemd/crontab installs exist — a session start rearms
a dead pulse from bro/pulse.json.
bro review drive install is the always-on merge path. Arming
bro/drive.json makes supervision infrastructure, not an opt-in:
session checkpoints rearm a dead supervisor on every lifecycle event
(sessionStart + postTool, orchestrator-only). bro fleet daemon down
under an install is a transient stop — the next checkpoint brings it
back; uninstall is 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 fleet doesn'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 drive
never bypasses bro review act merge — a non-green PR is supervised, not
forced.
1---2name: drive3description: "Use when orphaned PRs need an owner — 'drive the review loop', 'watch the PRs and fix them', a post-PR supervisor. Thin wrapper over the bro CLI: `bro review drive` polls act exit gates, spawns fixer agents through the facade, and merges on green. Requires `bro` (npx -y @broject/bro@0), bd, and the configured review-host CLI (for example, `gh` or `glab`)."4metadata:5 source: https://skillmd.com/skills/theplenkov/drive6---78# /drive (bro)910**All mechanics live in the `bro` CLI.** This skill is policy only —11the pass logic, occupancy guard, and fixer spawn live in12`packages/cli/src/commands/drive.ts`.1314`bro review drive` is the write-side counterpart of `bro review watch`'s gates plane:15watch *reports* `PR #N blocked — open_threads`; drive acts on it. It16exists for the orphaned-PR gap — a convoy/loop session ends at PR-open,17and review threads that arrive afterwards have no owner.1819## What a pass does2021For every open PR on a fleet branch (worktree branches + local22`work/*`, `loop/*`, `stack/*` branches):2324| Gate says | Occupied? | Action |25| --------- | --------- | ------ |26| `open_threads > 0` | yes | skip — the live owner works its own threads |27| `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 |28| `mergeable = CONFLICTING` | yes | skip — the live owner works its own conflicts |29| `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 |30| `gate.ok` | yes, fresh | report — the owner's merge step lands it |31| `gate.ok` | yes, silent past the TTL | adopt as an orphan → `bro review act merge` |32| `gate.ok` | no | `bro review act merge`, retire the worktree when clean, close the fixer bead |33| PR merged/closed | — | close a dangling fixer bead |3435Occupancy = the agents facade + a live foreign watch marker on the PR36(a `bro flow loop` heartbeat, `act wait`, convoy — drive only owns37*unsupervised* PRs, so a live supervisor is an occupant) + the38worktree's own fresh claim marker (`<gitdir>/bro/work`, stamped by39`bro work enter`) + fresh `.work` markers + a `/proc` cwd scan that40follows a process's ancestry to an agent-shaped root — agent CLIs sit41at their launch dir while their tool shells hold the worktree cwd — or42matches a `BRO_AGENT_ID`/`AI_AGENT` env badge, which detached43descendants keep. Occupied is always the safe verdict.4445The merge path is the one place occupancy ages out (bro-ihnlv): every46occupancy proof carries a last-proven-activity stamp — agent log mtime47or spawn record, marker mtime, the worktree's own churn — and a green48PR under an owner silent for `drive.occupancyTtlSec` (2h, floor 60s)49counts as orphaned: drive adopts it and merges rather than reporting50`green-occupied` forever. Freshness is judged on the freshest proof —51a stale fixer beside a live session still vetoes. Non-green verdicts52never age: an occupied thread/conflict PR stays occupied.5354## Commands5556| Command | What it does |57| ------- | ------------ |58| `bro review drive [--once]` | one supervision pass (default) |59| `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` |60| `bro review drive --no-merge` | supervise only — never merge (config: `drive.merge: "never"`) |61| `bro review drive --connector <name>` | spawn fixers on one backend |62| `bro review drive --json` | one JSON line per PR verdict |63| `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` |64| `bro review drive uninstall` | disarm the marker + stop the supervisor |6566Config: `drive.intervalSec` (300), `drive.merge` (`auto`|`never`),67`drive.occupancyTtlSec` (7200 — the merge-path activity bound).68The fixer agent's command resolves exactly like `bro fleet agents up` —69`agents.<backend>.command` → `loop.agent`.7071## Policy7273- **The orchestrator's pulse runs single passes.** The session-pulse74 model (bro-killn): a bounded `bro review watch --every --for` window ends →75 `bro review drive` once → digest → re-arm. `bro review drive --every` stays the76 long-lived detached supervisor when one is wanted — both `--every`77 forms refuse under `BRO_AGENT_ID` (spawned workers never arm78 cadences). No systemd/crontab installs exist — a session start rearms79 a dead pulse from `bro/pulse.json`.80- **`bro review drive install` is the always-on merge path.** Arming81 `bro/drive.json` makes supervision infrastructure, not an opt-in:82 session checkpoints rearm a dead supervisor on every lifecycle event83 (sessionStart + postTool, orchestrator-only). `bro fleet daemon down`84 under an install is a transient stop — the next checkpoint brings it85 back; `uninstall` is the disarm.86- **Occupied is not an error.** A skipped PR means a live session owns87 it — report and move on; never force-spawn into someone's worktree.88- **The fixer bead is the handle.** `bro fleet agents status <bead>` shows89 the fixer, `bro fleet agents down <bead>` stops it (the fixer is a90 standalone task, not a molecule step — `bro fleet` doesn't list it).91 A dead fixer respawns on the same agentId — that is the contract.92- **Merge is the exit gate's call, not the driver's.** `bro review drive`93 never bypasses `bro review act merge` — a non-green PR is supervised, not94 forced.