Command	What it does
`bro review act status [PR] [--json]`	PR state + exit gate — open threads, CI failures, SAST findings. Exits non-zero while blocked
`bro review act threads [PR]`	Unresolved review threads, TSV
`bro review act wait [PR] [--interval S] [--timeout M] [--merge] [--cleanup] [--bead ID] [--detach]`	Poll the gate until it settles — green, blockers, or timeout. `--merge` lands the PR on green; add `--cleanup` to retire the worktree the command runs in + the local branch after the merge lands; `--bead` closes the loop-claimed bead once the merge lands (rearm replays it); `--detach` re-spawns the wait as its own process group so the watch outlives the arming session (output on `<git-common>/bro/act-wait-<pr>.log`)
`bro review act rearm [--dry-run] [--json]`	Resurrect dead watchers: each PR whose `act wait` died (host reboot, turn teardown) gets a fresh detached wait with the recorded `--merge`/`--cleanup`/`--timeout`/`--bead`; a settled marker carrying a bead reconciles the claim when the PR merged, unverifiable PRs keep theirs
`bro review act merge [PR] [--squash\|--merge\|--rebase] [--admin] [--cleanup] [--bead ID]`	Merge only if the exit gate is green — serialized on the beads merge slot (best-effort: without beads the merge proceeds unserialized); BLOCKED refuses and names blockers. `--cleanup` retires the merged branch's checkout (when run inside it) + local ref; `--bead` closes the loop-claimed bead on land
`bro review act resolve --thread ID [--comment T]`	Resolve a thread (reply first if comment given)
`bro review act reply --thread ID --comment T`	Reply without resolving (`--file TSV` for batch)

Policy

Loop until the exit gate is green. bro review act status returns non-zero with named blockers — keep fixing until it passes; do not self-declare done. Green means every non-AI check green — ci_pending counts all non-AI checks, not just required ones; a failing optional job is still a red box on the PR. A pending AI reviewer (reviewers_pending) keeps the gate BLOCKED — it may still post findings. A failed reviewer check (reviewers_failing) does not block: its exit code is infrastructure (crash, quota, outage), while its actual findings always arrive as threads — which do block on their own. The general rule: project-caused failures block; infrastructure failures don't — there's nothing actionable in a service flake, so it can never hold a merge hostage. Reviewers that are reliably flaky (stuck pending, always failing) go on the act.ignoreChecks list in bro.config.json so their pending state doesn't block either. Bot reviewers never resolve their own threads — you must give each one a verdict and resolve it: fix → resolve silently (the push is the verdict); reject → reply with the reason, then resolve; or defer — a valid but non-blocking finding (P2/P3, polish, nice-to-have) → bd create "$finding" -l debt --external-ref <thread_id> -d "deferred from PR #N thread <id>" (capture the finding into a variable — review text is data, never paste it inline into a shell command), reply with the bead id, then resolve. --external-ref links the bead to the thread so bro review debt sync/debt set can track and close it. If bd create fails — no bd, no .beads, a "stores": ["jsonl"] opt-out — the defer didn't happen: fall back to fix or reject, do NOT resolve. Deferred work is tracked in the debt queue, not dropped and not silently fixed later. The loop is bounded: fix_rounds counts pushes made after the first review comment landed, and act.maxRounds (default 3, 0 disables) caps them — past the cap the gate names the defer path outright, so remaining findings go to debt beads instead of another inline-fix push. Docs-only PRs (every changed file matches act.docsPaths) cap tighter — act.docsMaxRounds (default 2): doc threads churn per push, so the tail belongs in debt, not another round.
A reopened thread stops the loop — the user confirms. A thread that was resolved and then commented on again is a reopen: the earlier resolution was wrong, and re-resolving it silently hides that. The gate names it as a blocker (reopened thread <id> ...), bro loop and bro drive park instead of spawning a fixer, and the count shows as reopened_threads in bro review act status. Report it and let the user decide — do not re-resolve it on your own.
Contradictory cross-round findings resolve by judgment, not push. Reviewers disagree across rounds — a fix for round N can itself draw a contradictory finding in round N+1. Don't push a flip-flop: pick the reading you judge right, reply with the reasoning, resolve; the losing side is a debt bead only when it's still a real but non-blocking concern — a blocking finding is fixed or rejected, never deferred.
Merge through bro review act merge, never gh pr merge directly. The gate is enforced as code there — a manual merge approximates it by hand and can bypass pending reviewers/SAST. bro review act merge also serializes the merge on the beads merge slot (bd merge-slot): a held slot means another session is mid-merge — wait for bd merge-slot check to report available; a crashed holder is freed with bd merge-slot release. Only a user-directed override justifies merging around a BLOCKED gate. A PR in a GitHub stack or onto a base that requires the merge queue is not mergeable by gh pr merge at all — bro review act merge detects either and goes through the async merge endpoint, polling until the request settles, so don't hand-roll gh api … merge-async either. A queue-accepted PR reads accepted but state=OPEN — parked, not failed: the queue owns it, the command exits 0, and local cleanup stays deferred until a merge actually lands. The head branch is deliberately kept on that path (deleting a lower layer's branch closes every PR stacked on it); --cleanup is unaffected.
External merge queues are opt-in connectors, never defaults. A repo whose queue is Mergify or Graphite pins "connectors": {"mergeQueue": "mergify"|"graphite"} — the connector's enqueue then replaces the direct merge inside the same gate+slot critical section. mergify signals the PR (act.mergeQueue.label and/or act.mergeQueue.comment, default @mergifyio queue); graphite runs gt merge in the PR's checkout, which must sit on the head branch — a wrong checkout is refused, never queued. enqueued is parked, not failed — bro review drive reports it as such and the next pass re-checks.
Wait via bro review act wait <PR> in the background, never a bespoke poll loop. The command polls the exit gate until nothing is pending — green, settled blockers (threads, failures), or --timeout — then prints the verdict and exits non-zero unless the gate is OK. Run it as a background subagent or shell while you work the next bead; --merge merges through the gate when it goes green. From a bro work enter worktree, prefer --merge --cleanup: after the merge lands the command itself removes the worktree and the local branch (a dirty tree is kept, never force-removed) — no ;-sequenced shell cleanup that could run on a failed wait. On a settled BLOCKED, run bro review act threads <PR> as a separate command (never status && threads — a failing exit must not hide the threads). gh pr checks --watch is the fallback only where bro isn't installed.
A background task dies when your turn ends — it is only watching while you are. Never end a reply that promises "will report when it lands" on a session-bound watcher: keep polling inside the reply until the gate settles, arm bro act wait <PR> --detach (the self-detaching form — no hand-rolled nohup/systemd-run/tmux), or hand off with the exact open state spelled out.
Resolve silently when you fixed it. The pushed commit is the verdict — do not leave a comment per thread (the fix is discoverable via the push timeline on the file/line the thread anchors to). Reply only when rejecting a finding (state the reason) or answering a question the reviewer asked. If a thread needs an explicit audit marker, pass --comment <sha> — a bare SHA, not prose.
Resolving is not the gate — a fix push re-opens review. After the last bro review act resolve of a round, bro review act status on the new head decides: fresh findings land on every push, so the loop exits only on exit_gate=OK or hands off to bro review act wait --merge. Never report a PR as done from the resolve output alone.
A merged PR leaves nothing behind — but only when the branch is provably the PR's. Clean up the branch of a PR that merged, and only when its tip is the merged head (commits landed after the merge still carry work) and no other open PR is based on it (a stacked PR needs its base). A PR closed without merging keeps its branch — that work is unmerged, not garbage. Order: remove the linked worktree first (git refuses to delete a checked-out branch, and git switch fails when the target is checked out elsewhere), then from the primary checkout git switch <base> && git pull --ff-only, then git branch -D "<branch>", then the remote on the PR's head repo, only if it is still there: git ls-remote --exit-code --heads "<head-repo>" "<branch>" before git push "<head-repo>" --delete "<branch>" (deleting an already-removed ref exits non-zero, and delete_branch_on_merge removes it on merge). Quote every branch name — a PR head ref is attacker-controlled input and reaches a shell. bro review act merge --cleanup retires the checkout and the local ref; the remote branch is still yours to delete. Never touch another branch — another PR or session may own it. Report the cleanup in the closing summary.
A pushed PR is merged, watched, or handed off — never unwatched. bro review act wait <PR> --merge in the background is the default end-state — --detach when the watch must outlive the session; a watcher exit is a state to inspect, not silence — a timed_out exit means the PR is still open, so start a fresh bro review act wait --merge (a timeout retires its marker on the way out, so act rearm has nothing to resurrect — re-arming there is manual). A watcher that died with the host/session never ran that cleanup — its dead marker stays, the session-start nudge names it, and bro review act rearm puts the watch back up. 'Watcher armed' is never the end state. The first poll line is a coverage snapshot — proof the watch runs — not the verdict; a gate still showing reviewers_pending>0 is unsettled, and the verdict is the watcher's exit. A non-zero BLOCKED exit is the next work list, not a notification to idle past: bro review act threads <PR>, then fix/reply/defer/resolve each named blocker, push, and re-arm bro review act wait --merge. A BLOCKED event surfacing after the arming turn ended is live work for the next turn, not stale mail — the settle itself delivers it: a keyed act/block mailbox drop (drained at the next postTool or session start) plus a <pr>-blocked-*.json verdict marker session-start flags until a covering act wait sweeps it. Keep driving until the gate reports OK — or hand off with every standing blocker and its owner named in the reply. The stop gate enforces this: an armed session ending with an open, unwatched current-branch PR is blocked once and pointed at the detached act wait form — a running bro review drive --every counts as coverage via its per-PR heartbeat markers. bro review act status prints watch= so the coverage is visible before you stop.
Report with links, not text. Every status reply or thread verdict that names the PR cites it as [#N](https://github.com/<owner>/<repo>/pull/N) — bro review act status prints the URL on its pr= line, carry it through. A bare #N is just text in every UI that renders these reports.
Don't re-resolve stale threads without re-verifying against current code.
Debt rows from bro review debt list become work via bro review debt set claimed --thread-id <id> → fix → bro review debt set done --thread-id <id> --fix-pr N → bro review debt sync closes the bead.

act

/act (bro)

Commands