SuperAPI AI Directory

drive

Coding & development

View repository

Updated 10-26 18:53

About this skill

/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.