@feigi/fleet-ctl 3.82.19 → 3.82.21

package/skills/run-team/references/ci-and-staleness.md

@@ -134,3 +134,50 @@ than being detected, and nothing else can write the reason afterwards:
 ```bash
 ~/.fleet/bin/fleet-run fleet-heartbeat.mjs --stop "budget exhausted"
 ```
+
+Skipping it is not fatal — the next reader still reports the stop, it just
+reports that the beat stopped *without a recorded reason*, which is all it can
+honestly say about a death that named nothing.
+
+## Nothing to do: why the beat, and what its lines mean
+
+- **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
+  (SKILL.md's **Nothing to do: arm the beat**). A turn that ends on a drained
+  queue is the stall itself: nothing external will wake you, and the
+  level-check you are one command away from never runs. Listed on its own
+  because it is the only wake with no trigger — every other row of SKILL.md's
+  wake list arrives; this one is the absence of one.
+
+- `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
+  command blocks for a whole interval (omp backgrounds one at 60s, which is
+  why the CI gate holds its wait in one `eval` cell polling `gh run view`).
+  Issue it again. That is still one blocking call per turn, never an idle turn.
+
+**The beat does not stop on idleness.** An empty shortlist and an empty supply are
+not a reason to end the run; they are the state a newly triaged ticket arrives
+into. The run ends when you drain it, when the budget goes, or when this
+context does — not because there was briefly nothing to do.
+Zeroes on the cockpit are not yet proof the pipeline is idle.
+
+## Rule: record, tick, act, beat
+
+**Rule: record, tick, act, beat.** Every wake — a member report, a review
+notification, a label, a CI run reaching a terminal state, a `CONFLICT` line, a
+heartbeat, the maintainer's drain — is one `fleet-event.mjs` call, which makes
+the wake's writes and ends in one `fleet-tick.mjs` invocation, and you do what
+it prints. There are no hand-run
+refill or dispatch edges left. Record first, because the tick reads the run off
+`.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
+one it cannot see, and it names the same dispatch again. Every record goes
+through `ledger.mjs` (references/ledger.md), which `fleet-event.mjs` drives — never a
+hand edit. What each kind writes is in the header comment of `fleet-event.mjs`.
+
+## The merge bot does not wait for the finisher's report
+
+The `ready-to-merge` Monitor catches hand-added labels as well as a finisher's
+own. The bot does not wait for that finisher's report: its rebase is
+server-side, `gh pr update-branch --rebase`, so nothing on the finisher's
+worktree has to happen first. **You own the watcher, not the bot.** Arm one
+yourself, `persistent: true`, seeded before the loop so handled PRs do not
+re-fire. **One rebase per PR, at merge time.** Any behind-count you hand a bot
+is expired on arrival; say so.

package/skills/run-team/references/ci-watcher.md

@@ -1,6 +1,141 @@
-# The CI watcher: why its block is shaped the way it is
+# The CI watcher: its block, and why it is shaped the way it is
 
-Evidence for the rules SKILL.md states beside its watcher block, under **Own the CI waits**, keyed by the rule each justifies.
+SKILL.md's **Own the CI waits** arms the persistent Monitor from the block
+below, verbatim. The rules beside the block follow it; the evidence for each
+rule is under the heading naming it.
+
+## The block
+
+**A probe that cannot read is a transition event, not silence.** So check the REST budget *before* polling — `gh api rate_limit` is itself
+unmetered (`gh api rate_limit --jq '.resources.core.remaining'`, re-confirmed
+2026-09-08) — and give an unreadable `ci-state` payload the same treatment one
+level down. The shape is **one outer tick loop with an inner pass over the open
+PRs**, because the two causes live at different levels — the budget is one
+account, the payload is one PR:
+
+```sh
+budget_out= hidden_out= list_out= cap_out= blind= # seed the latches: set -u reads each below before tick 1 ever assigns one
+pr_cap=200                                   # the open-PR read's --limit; gh stops there with exit 0 and no warning
+while :; do                                   # one tick
+  rl=$(gh api rate_limit --jq '.resources.core.remaining' 2>/dev/null || echo ERR)
+  case "$rl" in ''|*[!0-9]*) rl=ERR;; esac    # a non-numeric read is an outage, not a budget
+  if [ "$rl" = ERR ] || [ "$rl" -lt 200 ]; then
+    if [ -z "$budget_out" ]; then             # ONE global latch: a quota outage hits every PR
+      echo "WATCHER DEGRADED: core REST budget=$rl — CI polling paused, silence is NOT green"
+      budget_out=1
+    fi
+  else                                        # every RECOVERED waits for the pass gates below
+    prs=$(gh pr list --state open --limit "$pr_cap" --json number --jq '.[].number' 2>/dev/null) || prs=ERR
+    if [ "$prs" = ERR ]; then
+      if [ -z "$list_out" ]; then             # global latch: this cause is account-level too
+        echo "WATCHER DEGRADED: cannot list open PRs — CI polling paused, silence is NOT green"
+        list_out=1
+      fi
+    else                                      # a list or cap RECOVERED waits for the pass gates too
+      count=$(printf '%s\n' "$prs" | grep -c .) || : # grep -c exits 1 on zero matches; set -e must not take it
+      if [ "$count" -ge "$pr_cap" ] && [ -z "$cap_out" ]; then # global latch: a full page may have been cut there
+        echo "WATCHER DEGRADED: open-PR list hit its --limit $pr_cap — PRs past it are NOT watched, silence on them is NOT green"
+        cap_out=1
+      fi
+      # gh pr list is GraphQL, so $rl still holds. The pass is budgeted at 4 core
+      # REST units per listed PR on top of the 200 floor.
+      # A shortfall here, or at the Actions-bucket gate below, pauses this tick's pass.
+      if [ "$rl" -lt $((200 + 4 * count)) ]; then
+        if [ -z "$budget_out" ]; then
+          echo "WATCHER DEGRADED: core REST budget=$rl < $((200 + 4 * count)) needed for $count PRs — CI polling paused, silence is NOT green"
+          budget_out=1
+        fi
+      else
+        # The workflow and run lookups bill a second core bucket that
+        # `rate_limit` does not report. Its count is only in the response
+        # headers of a lookup that bills it: one 1-unit read per tick, 4 units
+        # per listed PR on the same 200 floor. Recovery for every global latch
+        # waits until this gate clears too, so no line says polling resumed
+        # while this one still pauses it.
+        hrl=$(gh api -i 'repos/{owner}/{repo}/actions/workflows?per_page=1' 2>/dev/null | awk 'tolower($1)=="x-ratelimit-remaining:" {sub(/\r$/, "", $2); print $2; exit}')
+        case "$hrl" in ''|*[!0-9]*) hrl=ERR;; esac # a missing header is an outage, not a budget
+        if [ "$hrl" = ERR ] || [ "$hrl" -lt $((200 + 4 * count)) ]; then
+          if [ -z "$hidden_out" ]; then
+            need=; [ "$hrl" = ERR ] || need=" < $((200 + 4 * count)) needed for $count PRs" # an unreadable header has no amount to compare
+            echo "WATCHER DEGRADED: unreported Actions core REST bucket=$hrl$need — CI polling paused, silence is NOT green"
+            hidden_out=1
+          fi
+        else
+          if [ -n "$list_out" ]; then
+            echo "WATCHER RECOVERED: open-PR list readable again — CI polling resumed"
+            list_out=
+          fi
+          if [ -n "$cap_out" ] && [ "$count" -lt "$pr_cap" ]; then
+            echo "WATCHER RECOVERED: open-PR list under its --limit $pr_cap — every open PR watched again"
+            cap_out=
+          fi
+          if [ -n "$budget_out" ]; then
+            echo "WATCHER RECOVERED: core budget=$rl — CI polling resumed"
+            budget_out=
+          fi
+          if [ -n "$hidden_out" ]; then
+            echo "WATCHER RECOVERED: unreported Actions core REST bucket=$hrl — CI polling resumed"
+            hidden_out=
+          fi
+          for pr in $(printf '%s\n' "$prs"); do # inline $(...): `for pr in $prs` is ONE iteration under zsh
+            st=$(~/.fleet/bin/fleet-run ci-state.mjs --pr "$pr" 2>/dev/null) || : # not-green exits non-zero; the payload is the verdict
+            if ! printf '%s' "$st" | jq -e '.verdict and .verdict != "rate-limited"' >/dev/null 2>&1; then
+              case " $blind " in *" $pr "*) ;; *) # latch keyed BY PR: this cause is per-PR
+                echo "WATCHER DEGRADED: no usable ci-state reading for #$pr — silence is NOT green"
+                blind="$blind $pr" ;;
+              esac
+              continue                        # inner continue — still reaches the tick sleep
+            fi
+            case " $blind " in *" $pr "*)
+              echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
+              keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
+            esac
+            : # your normal handling of $st for this PR; a run at a terminal state is the CI wake: fleet-event.mjs ci "$pr"
+          done
+        fi
+      fi
+    fi
+  fi
+  sleep 120                                   # the block's only pacing, once per tick
+done
+```
+
+**It has to latch** — one line entering the degraded state, one leaving it,
+never one per tick. **Latch each cause at the level its cause lives
+at**: the budget, the unreported Actions bucket, the open-PR list and that
+list's cap are one global flag each — all account-level — but the payload latch is keyed by PR, and a
+shared scalar for those is an unlatched line wearing a latch's clothes — one
+persistently blind PR alongside one healthy PR re-clears the flag on every tick,
+emitting a DEGRADED and a false RECOVERED pair forever. The recovery line is
+what says the watch is alive again, so emit it on the first good pass even when
+nothing about the CI state changed; without it a reader cannot tell a recovered
+watcher from a dead one.
+
+**Guard every probe, not just the ones with a verdict field.** Capture its status (`prs=$(…) || prs=ERR`), latch it globally, and fall
+through to the same tail sleep. **Then iterate with the inline `$(printf '%s\n'
+"$prs")` form, never a bare `for pr in $prs`** — the assigned-variable trap in
+**Shell traps**, in references/shell-traps.md, which carries the mechanism and its
+measurements. It
+applies to **every** loop in this block, the `blind`-latch removal included:
+under a bare `for b in $blind` a recovered PR never leaves the list and the block
+emits a fresh RECOVERED every tick thereafter — the per-tick volume the latch
+exists to prevent, wearing a latch's clothes again.
+
+**A readable list can still be a short one.** Pass an explicit `--limit`
+(`pr_cap`: one variable for the flag and the check, so the two cannot drift)
+and treat a full page as its own degraded cause — the "no silent caps" rule
+`candidates.mjs`'s `refuseIfCapped()` and `fleet-tick.mjs`'s `PR_LIMIT` already
+enforce. It latches globally like the list failure but does not pause polling:
+the PRs it did return are real, so the pass still watches them, and the
+DEGRADED line names the rest as unwatched until a pass comes back under the cap.
+
+**Judge `ci-state` on its payload, never its exit code** — the same rule as
+`merge-gate.mjs` applies on the merge path, applied to the watcher. Empty
+or unparseable output is the degraded case; parseable JSON reading
+`verdict: "not-green"` is normal. An exhausted quota may also name itself,
+`verdict: "rate-limited"` on stdout — likewise degraded, and likewise not a
+reading, which is why the gate above tests the verdict rather than mere
+parseability: that payload is perfectly good JSON.
 
 ## The pass is budgeted at 4 core REST units per listed PR
 
@@ -28,7 +163,7 @@ as a CI reading. Require the field, then compare it.
 inside the per-PR pass multiplies by the number of open PRs (8 open PRs → 960s
 of pause per tick, against the 24s outage reset measured below), and a degraded
 branch that `continue`s the *outer* loop skips the tail sleep and busy-spins
-probe pairs during exactly the outage it is reporting. Every degraded branch of SKILL.md's watcher block falls through to the same single sleep instead.
+probe pairs during exactly the outage it is reporting. Every degraded branch of this file's watcher block falls through to the same single sleep instead.
 
 ## The budget is gated at the floor and again at the pass
 

package/skills/run-team/references/close-out.md

@@ -2,6 +2,36 @@
 
 `closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the commit of the metrics files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
 
+- **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
+  first (below). The marker is on disk, so the tick
+  holds the implementer row at `HOLD (draining)` from then on — for a
+  replacement controller too — and keeps the review, fix-applier and merge rows
+  firing until the open PRs merge. The drain starts the end of the run; it does
+  not end it. **End of run**, in this order:
+  1. `~/.fleet/bin/fleet-run fleet-event.mjs drain --reason "<reason>"` — runs
+     `closeout.mjs begin --reason "<reason>"` (references/reaping.md), then the tick. A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
+     refusal is the finding, so run `worktree-audit.sh` and decide by hand.
+     `begin` selects a claim with no PR and a live or `bailed` implementer token
+     on every run, so a claim you keep leaves `begin` at exit 4 on every run:
+     release the rest by hand and run `begin` again.
+  2. Act on the review, fix-applier and merge rows until the tick prints
+     `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
+     once the run is draining with no open PR and no live implementer.
+  3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
+     the run's member facts, checks the tier-outcomes rows, refreshes the
+     metrics, commits the three metrics files and opens their PR, sets the
+     phase-0 receipt aside as `.fleet/phase0.previous.json`, then records
+     `fleet-heartbeat.mjs --stop` last, because every reader takes a recorded
+     stop as the end of the run. A `NEED tier-outcomes append <pr>` is a PR
+     the ledger marks reviewed with no verdict row: append it with the verdict
+     you rule (**Guard: accumulate per PR**) and run `finish` again. A reviewed
+     PR that closes no issue, a `Refs`-only step for instance, takes no row: the
+     check names it in a `note` line and never asks for one. A step it fails is
+     explained in references/close-out.md. Exit 0 is the run closed.
+  Drain only when a documented trigger fired, and name the trigger in `--reason`.
+  **Undrain** only when the maintainer asks, never a drain that budget or
+  context exhaustion caused (references/close-out.md).
+
 ## Scrape the member facts and check the tier rows
 
 **Then record the run's member facts — do not author them.** Scrape EVERY session
@@ -55,7 +85,10 @@ and none could be compared, so nothing from that run was checked: append the
 run's member rows if they are missing, or blank each named row's `tier` and say
 why in `note`.
 Each WARNING names a PR this run's ledger marks `reviewed=` that has no row yet
-— append it before committing if it is an implementer PR.
+— append it before committing if it is an implementer PR. A reviewed PR that
+closes no issue is named in a `note` line instead: it takes no row. A line
+saying the PR's closing references could not be read comes before that PR's
+WARNING and says why.
 
 ## Drain the pending ticket-features rows and refresh the cost guard
 

package/skills/run-team/references/failure-handling.md

@@ -33,3 +33,46 @@ while one poll spent on a member that had in fact stopped costs only the poll.
 The refuter's own observation rule in the fix-applier body stops a
 member from creating that state; this one stops you from misreading whoever
 reaches it anyway, and neither replaces the other.
+
+## Audit every worktree before dispatching replacements
+
+Audit every worktree before dispatching replacements with
+`~/.fleet/bin/fleet-run worktree-audit.sh` — it reports each worktree's
+ahead-count and uncommitted files, the committed-vs-uncommitted distinction that
+decides whether a replacement redoes or destroys work.
+
+## A failed review, and verifying a reported SHA
+
+**A throw, an empty return, or a notification whose status is not `completed`
+is a failure event, not a clean review.** **Retry once
+under the next runner letter, then stop:** the `review-pr-<pr#>` runner
+already retried once inside its cell and reports `failed` with both errors, so
+the retry is a second runner under the next letter the PR's rows do not carry
+yet — `review-pr-<pr#>-b` after a first runner — recorded as
+`review=member:<that name>`. A second failure is reported, and the PR stays at
+review-due. A
+runner member that is killed rather than failed follows **Failure
+handling** (fresh name, inherited state stated).
+
+**Verify every reported SHA.** `~/.fleet/bin/fleet-run verify-sha.sh
+<branch> <sha>` before enqueueing — a member can commit in a nested worktree,
+leaving the SHA on a stray branch while its report reads normally. Exit codes as
+`inflight.sh`: `# 0 reachable, 1 not reachable, 2 unanswerable`. Not reachable
+(exit 1) → flag, do not enqueue, do not return the ticket to the shortlist until the
+maintainer rules. **Exit 2 is not a verdict** — the question could not be
+answered, and every cause of it reaches you as one shape: no JSON on stdout at
+all, the cause on stderr alone. Read that stderr, fix what it names and re-run;
+escalate if it repeats. Never read exit 2 as `not reachable`, and never record it
+as a stray commit — the flag and the maintainer's ruling above are what exit 1
+earns, and spending them on a probe that never answered costs a member its
+ticket over a failure a re-run would have cleared.
+## Never force a rebase to start
+
+**Never force a rebase to start.** No `git clean`, `git checkout .`,
+`git reset --hard`, `git stash`. Uncommitted changes may exist nowhere else.
+Non-empty `git status --porcelain -unormal` → stop and report — the explicit
+mode, never bare `--porcelain`, or `status.showUntrackedFiles = no` reads an
+empty answer here and licenses the rebase over work this check exists to
+protect. Stashing empties it either way, so that check and
+`no-undo-audit.sh` both go quiet on work nothing else holds.
+

package/skills/run-team/references/finisher.md

@@ -2,6 +2,139 @@
 
 Evidence for the finisher rules the finisher's agent body, `agents/fleet-finisher.agent.md`, and SKILL.md's **The finisher gate** state, keyed by the rule each justifies.
 
+## The fix-applier pushes and exits; the finisher is dispatched fresh
+
+**The fix-applier pushes and exits — it does not hold the CI wait.** You own the
+persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
+rebuilds a 100k-token context for nothing the Monitor lacks. The body
+carries the report-last rule and the brief says to push, write the report and exit; you do not have to restate either. When the
+diff-validating `check` job is green **and no
+heavy job is in `failure`** (the heavy diff-validating suites — not the
+`rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
+fine — **solely** off that count, which is a condition to establish rather than
+infer, see the five-condition note in the fix-applier body) — or
+`ci-state.mjs` reads `verdict: "no-ci"`, its bullet in **The finisher gate's
+tests, in full** — **and once the PR's review
+has returned and its fix-applier, if one was dispatched, has sent its report,
+which the CI-completes edge in that section states in full** — dispatch a
+**finisher** — a fresh small agent, not the fix-applier resumed. Render its brief
+with `dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<pr#> …`
+(`--kind repair` once an earlier finisher reported `labelled` without the label landing), record it with
+`ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call, then **dispatch
+it with the `agent` that command printed and omit `model` on the call** — the
+tier lives in that definition's frontmatter, `agents/fleet-finisher.agent.md`,
+as the `@smol:low` route, which resolves through the operator's `modelRoles`.
+Its four duties are a checklist — audit the
+worktree, confirm every deferral has a tracker home and re-run the acceptance
+mutation, apply one release label, report — and the
+merge gate downstream still catches whatever it gets wrong. **Never dispatch
+one while you still owe the fix-applier a ruling**: the pinned SHA is only as good
+as the guarantee nothing else is inbound. **The test is your OUTBOX, not the
+member's last message** — anything you have decided that it has not received,
+including a ruling you have since **withdrawn or reversed**. **That is the test
+of THIS condition only**: an empty outbox says nothing is inbound from you, and
+nothing about whether the member considers itself finished, which is what the
+report condition above is for. A withdrawal you
+recorded only in the ledger is undelivered: the member still holds the original
+and will act on it. Relay everything — reversals too — then dispatch.
+
+## The finisher gate's tests, in full
+
+- **Monitor: CI run completes** → `fleet-event.mjs ci <pr>`, which binds the run
+  (`ci-state.mjs --pr <N>`) and **records it as
+  `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
+  ticket's ledger row, which outlives your context. The key is what the sibling
+  bullet below turns on: it tells an edge already spent from one that never
+  fired. The whole key, never the conclusion alone: **a
+  conclusion is not stable** (references/ci-and-staleness.md), because a rerun rewrites the run in
+  place. The diff-validating `check` job green with no heavy job (the
+  diff-validating suites, not the `rebase-check` currency gate) in `failure`
+  → a finisher CANDIDATE (gated by *The fix-applier pushes and exits; the
+  finisher is dispatched fresh*), a `check`
+  **failure** that is not solely staleness → the **red-check fixer** (SKILL.md's
+  **Then dispatch a red-check fixer**), behind the same review-returned and
+  fix-applier-reported gate as a finisher. A `check`-green board whose heavy jobs are merely
+  `skipped` (behind-count staleness, the normal case after a merge) still labels — do NOT
+  gate on `ci-state --quiet` exit 0, which a behind PR never reaches. **This
+  edge fires for every CI run the PR produces, and the implementer's own
+  firing comes first for every PR** — `ci.yml` triggers on `pull_request`, so
+  opening the PR at the end of `next-ticket` step 7 starts a run within seconds,
+  while the review returns 20-40 minutes later. That first firing is
+  the ordinary case for every PR, not a rarity, and no review has run at all
+  when it arrives. **Green is therefore not the gate: dispatch a finisher only
+  once the PR's review has returned AND its fix-applier, if one was dispatched,
+  has sent its report — pushed is not reported**, and a push before that report
+  is mid-work on a SHA the member may still move, which its own prompt tells it
+  not to hand over. A push is therefore not an exit, and a report that has not
+  arrived is asked for by name rather than read as one. Neither shape is caught
+  by an empty outbox: on the implementer's firing there is no fix-applier to owe
+  anything to, so the outbox is *vacuously* empty, and on a fix-applier's
+  mid-work push nothing has been sent since the dispatch, so it is *genuinely*
+  empty. **The outbox is the last test, not the only one, and it stands wherever
+  a fix-applier exists** — that is exactly where a ruling you still owe it is
+  outstanding, so never dispatch off it while you do. Empty your outbox to it
+  first — including any ruling you have withdrawn or reversed — then dispatch
+  (*The fix-applier pushes and exits; the finisher is dispatched fresh*); a final report is not proof it stopped. A PR that needs nothing fixed
+  reaches a finisher through the **fix-applier reports `no-op`** bullet below,
+  never by waiting for a second CI event this head will never produce. The
+  same goes for a red one: a red that fired before the review never fires
+  again, so the **fix-applier reports `no-op`** and **review result lands**
+  bullets are also the only routes to the red-check fixer there.
+  Then run the tick. These edges dispatch it, each the finisher's own: **Monitor: CI run completes** binding a red on a head whose review has returned and whose fix-applier, if any, has reported; **A fix-applier reports `no-op`**, or a SHA you have already bound, when that head's bound conclusion is red; and **A review result lands** with no finding and nothing to file, when that head's bound conclusion is red.
+- **A fix-applier reports `no-op`, or a SHA you have already bound** → dispatch
+  the finisher **now**, against the existing head — when that head's bound
+  conclusion is red, the red-check fixer instead (SKILL.md's **Then dispatch a
+  red-check fixer**), never a finisher and never a wait. No push means no new run, and
+  the Monitor above is edge-keyed on `<run-id>:<attempt>:<conclusion>` — that
+  head's terminal state already fired once and will never fire again, so waiting
+  for the CI event waits forever. This stays a common outcome on a clean PR:
+  `suggestion` is the band a clean diff produces, and every out-of-scope or
+  refuted one is filed as an issue rather than committed. An edge-only label path
+  therefore strands exactly the PRs with nothing wrong with them. **Reconcile, do
+  not wait for an event** governs here too, not only the implementer row. **This
+  bullet and the one above are a pair, and on a clean PR this one carries the
+  whole route to a finisher**: a `no-op` report satisfies the gate above by
+  itself — the review has returned, because a fix-applier exists only after it
+  did, and the member has reported — so nothing further is owed and no further
+  event is coming. Edit either bullet without the other and what strands is exactly the PR that needed no fixes. Edit one of these bullets without the others and what strands is exactly the red-only PR.
+- **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → no workflow run will ever
+  complete for this repo, so the CI-run-completion edge above never fires and
+  waiting for it stalls the whole PR — the same silent-stall shape reported
+  before this verdict existed. Dispatch the finisher off the reviewer's final
+  verdict instead, the moment it lands — and, same as above, never while you still
+  owe it a ruling — or hold anything else it has not received, a ruling you have
+  withdrawn or reversed included. The finisher's gate is then the
+  `--declare-no-ci` declaration, not a `check` job: with it, label off the
+  reviewer's verified suite run; **without it, do not label** — report that this
+  repo has no CI configured and no declaration, and stop. Absence never reads as
+  pass. See `review-and-fix.md` step 6.
+
+Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
+reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
+per-job state (`ci-state.mjs` without `--quiet`, or its `jobs`), since `--quiet`
+drops `jobs`, `missing` and `dropped`. Normal path, not only kill-recovery.
+
+**`ci-state.mjs` reads `verdict: "no-ci"`** — no `check` job exists in this repo
+to gate on, and that is not a third way to skip the wait. **The
+`--declare-no-ci` declaration is caller-side, and reading it back out of the
+payload verifies nothing**: the flag is echoed into `reasons` and flips the exit
+code, so re-running with it and finding it there confirms only that you passed
+it. Passing it yourself is not a second opinion. Check the two facts it stands
+for instead:
+
+1. `ci-state.mjs` **without** the flag still reads `verdict: "no-ci"`. A repo
+   whose CI is merely misconfigured — workflow files present under other names,
+   or `.github/workflows/` not a directory — exits 2 there rather than reading no-ci,
+   so this is the check that separates real absence from misconfiguration, the
+   case that must never ship silently.
+2. The reviewer's own final verdict reports a green `testCmd` run on the SHA it
+   pushed. `review-and-fix.md` step 3 requires it to, and that run is the only
+   gate this repo actually has.
+
+Both → add the label, and say it rests on the reviewer's suite run, not on CI.
+Either missing → halt here, same as a dirty worktree: report `no CI configured,
+no verified suite run on record` and add no label.
+
 ## An unanswered question from the member is an outbox item
 
 **An unanswered question from the member is an outbox item, and it blocks
@@ -119,3 +252,55 @@ its token re-dispatches a finisher into your take-off window. The label goes
 before the approval because removing the artifact the merge bot gates on is
 the reliable stop, where messaging the bot races it, and a label has been
 observed holding until after an abort message arrived.
+
+## A final report is not proof the member stopped
+
+**A final report is not proof the member stopped.** Observed twice: a ruling
+relayed after dispatch produced a new commit mid-audit, and a fix-applier that
+reported "nothing outstanding" resumed on a ledger-only withdrawal and was
+cycling mutants through the worktree when the finisher audited it. Both finishers
+correctly halted. Note what that costs to detect: two reads of the same worktree
+a minute apart showed *different* mutants, so a member's report and any single
+`git status` are each valid only at their instant.
+
+## The standing CI facts are in the fix-applier body
+
+**The standing CI facts are in the fix-applier body, not in per-event messages** —
+otherwise you send "your red is staleness, do not rebase" once per member per
+merge. `review-and-fix.md` states them; the body says they apply.
+
+## A halt's cause comes from one script
+
+A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
+and the causes `finisher-audit.mjs` names are the ones seen so far, not a
+closed list; the finisher's agent body gives it the cause from one script
+instead of asking anyone.
+
+## Why a `past-pin` halt needs the tick
+
+`past-pin` needs the tick because the dead-review path cannot reach it: once a
+review has **returned**, its `reviewed=` token holds the PR out of `review-due=`,
+and settling that review `=failed` re-queues nothing — that path covers only a
+review that died before returning. A head that moved past `reviewed=` with no
+such halt — a fix-applier's push — stays not due: duty 2 verifies what it
+applied. **A rebase never gets a `reviewed=`:** the earlier review still
+counts, because dispositions verdicts are tied to its head. Never write a
+`reviewed=` you did not read off a review result file.
+
+## Resolving a finisher that died
+
+**Resolving a finisher that died.** A finisher settled `failed` or `killed` left
+its PR without `ready-to-merge`, and nothing else notices: the PR is out of the
+merge queue, and the tick dispatches no finisher for it. The cockpit flags a
+REVIEW-column open PR without the label, whose latest finisher attempt settled
+so, `finisher:failed` or `finisher:killed` at severity 4 — one token per
+outcome, neither the implementer's bare `killed` flag nor `unlabelled`. You
+resolve it by hand: investigate why the finisher died, or dispatch the
+next-suffix finisher after the finisher gate: render its brief with
+`dispatch-prompt.mjs render finisher --kind fresh --member finisher-pr-<M>-<x>
+…` (`--kind repair` once an earlier finisher reported `labelled` without the
+label landing), then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`. The flag
+clears when a later attempt settles — `labelled`
+(then `unlabelled` takes over while the label is still off), `halted:<cause>`,
+or a live `-b` — or when the PR carries `ready-to-merge`, merges or closes.
+You never add the label yourself, and the tick does not retry.

package/skills/run-team/references/instruments.md

@@ -42,3 +42,23 @@ refusal on that is noise.
 You just changed the instrument set under your own check, and this is the
 only edit that legitimately does; skip it and the next gate refuses on your own
 fix, which teaches you to ignore the refusal.
+
+## Landing a mid-run tooling fix from the main checkout
+
+**Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
+--pin`. Then the ledger line, save the
+rationale, one line to the maintainer. **Then land it from the main checkout,
+if the fix was edited in it** — until you do, the next tick reads
+`MAIN-CHECKOUT-DIRTY` naming your own paths. Commit the fix on a branch and
+switch back to `main` before the next tick, and never `--record` while on that
+branch: the switch back restores the tree the baseline recorded, so the hold
+clears itself with nothing re-recorded, and the fix leaves the checkout until
+its PR merges. A `HEAD …` entry is none of your paths and clears the same way.
+Re-baseline only a fix you leave edited in the checkout: run
+`~/.fleet/bin/fleet-run main-checkout.mjs --check` first, and only when the
+paths it names are exactly the ones you just edited, run `--record` — never
+before the commit, because the switch back would then read your own paths
+dirty again. Any other path on that line is a stray write — leave the hold for
+the maintainer, because `--record` would certify it with yours. Live members
+hold the old text — re-brief only if it changes what they do *now*.
+

package/skills/run-team/references/isolation.md

@@ -310,3 +310,13 @@ by the member rather than by the controller's guesswork.
 It owns the object-store rule, the two-tree split, snapshot provisioning, and
 which suites a snapshot cannot validly run. Your only duty is to *not*
 contradict it.
+
+## Every brief carries the absolute scratch path
+
+`<scratch>` in this file is the path it prints, resolved before you send anything: every
+brief that carries one carries the absolute path you passed it — an
+implementer's `<scratch>/impl-<N>/`, the recipe deriver's
+`<scratch>/derive-recipe/`, a fix-applier's, a finisher's and a merge bot's
+`<scratch>/pr<N>/…`, and a review runner's `scratch` argument, which is the
+root itself. A member whose prompt names no path asks you by name and never
+makes one up.

package/skills/run-team/references/ledger.md

@@ -101,3 +101,7 @@ The ledger half reports its own readability as its own field, `ledger.ok`, the p
 **The suite slots wedge the same ways, and clear the same way.**
 
 `~/.fleet/suite-slots/<i>.lock` is built on the ledger's lock primitive, so an empty or unparseable `<i>.lock` and a leftover `<i>.lock.reap` are permanent, a zombie holder is transient, and a dead holder is taken over. A wait that expired with exit 75 names each wedged file — remove it by hand once no suite run is running, the way the Writer policy section above removes `<file>.lock`.
+
+## Adding a token
+
+Token additions go through `ledger.mjs token`. `ledger.mjs token <key> <token>…` adds a token and keeps every token already on the row. Re-typing the row with `row` replaces the whole line, so it drops the tokens you do not restate.

package/skills/run-team/references/member-lifecycle.md

@@ -176,3 +176,21 @@ Dispatching the next member on top of an unchecked or mismatched dispatch multip
 ## Ledger reads and their buffer
 
 `board.mjs` reads `ledger.mjs read` with an explicit `maxBuffer`, so a payload past node's default is carried rather than killed mid-flight and reported as an unreachable tool — which is how the blind cockpit came back at HTTP 200 even after the pipe cut was gone.
+
+## A carried implementer after `/resume` holds the whole tick
+
+**After `/resume`, a carried implementer can hold the whole tick.** It holds when the check given this run's `session` finds no `<member>.jsonl` and exits 2, writing nothing. `HOLD (tier unchecked impl-<N>)` then stops the whole tick, not only that member's ticket. It clears once the member settles: one settled `killed` or `released` gets `tier-unverifiable=` from the same check, and one settled any other way ran, so pass the directory that dispatched it, as above. Until it settles, follow the carried token's reconciliation in references/phase-0.md, the "Resume the claims a dead run left without a PR" section, under its `prior: ancestor` branch: `proc://` reads `running` → wait; dead → the Member-killed row.
+
+A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick probes that issue and drops it, since there is nothing left to replace.
+
+## The test command every gate runs
+
+**The test command every gate runs.** Pass the same command to the review, to the fix-applier, and to the finisher — whose duty-2 mutation gate runs it too — so every gate runs one command. The fix-applier and the finisher run what you hand them, so hand them the wrapped string as `<testCmd>` — `~/.fleet/bin/fleet-run suite-slot.mjs '<command>'`, each `'` inside the command written `'\''` — and it is still one command for every gate. The review wraps its own one run, so its args carry the bare command; a wrapped string handed to it anyway is harmless, the inner wrapper being the nested case. Omit it from the review args and the review (`review-core.mjs`, in a runner) reads the same cache itself, refusing outright when there is none; the fix-applier has no such fallback, so substituting `<testCmd>` with nothing leaves it no gate at all. See `references/isolation.md` (the stack-free test command).
+
+## Dispatching the members a wake names, in full
+
+- **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path and `reviewed=` token.
+A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
+- **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
+- **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement.
+- **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness: a `rebase-check` red, or heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the five-condition note in `agents/fleet-fix-applier.agent.md` establishes that). Name `fix-pr-<M>`, or the next free suffix; render with `dispatch-prompt.mjs render fix-applier --kind red-check --member <name> …`, record with `ledger.mjs dispatch <pr#> <name>` before the call, and dispatch with the printed `agent` in the PR's existing worktree. While a review or a review fix-applier on the PR is live or still owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included — the red-check fixer does not fire: their push starts a new run, and a fixer racing them would work on a SHA that is still moving. The common case, the implementer's own first CI firing turning red before any review exists, still dispatches the review against that head as normal. The tick prints no `DISPATCH` for it, so you reconcile it yourself, and it always goes after the review, never before. It is told outright not to watch, poll or wait for CI: your persistent Monitor owns the next run on the pushed head, and the finisher gate — review returned AND fix-applier report sent — applies to this member the same way. Settle it `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red turns out not to be this member's to fix — a flake that passes on rerun, or staleness — with nothing pushed; `no-op` counts as landed, so it never stands for "could not fix". Settle it `failed` when it cannot reach green, which the **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot reach green" covers. Its three dispatch edges are under **The finisher gate**; their rationale is in `references/member-lifecycle.md` (The red-check fixer's three edges).

package/skills/run-team/references/phase-0.md

@@ -12,6 +12,14 @@ child's stderr. `--session <dir>` overrides the variable.
 Exit 3 is a step that failed: its line carries the refusal, so fix the cause
 and run it again.
 
+`phase0.mjs` runs the start sequence in
+its fixed order — branch, fast-forward, pin, baseline, preflight, ruleset,
+tier-roles, metrics, cockpit, rotate, reclaim, recipe, fold-in, stranded,
+shortlist — prints one `phase0: <step>: <status>` line per step with the
+`NEED` lines last, and records each step in `.fleet/phase0.json`, which the
+tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
+until the receipt is whole.
+
 ## Fast-forward the checkout
 
 **Fast-forward the checkout before you trust these rules — you are reading
@@ -441,3 +449,45 @@ else. Exit 2 is a list that did not answer — a `gh` or `git`
 failure, a list at its cap, a worktree whose presence cannot be told, or,
 after `ancestor`, a ledger that cannot be read — and is never nothing
 stranded.
+
+## Build the Shortlist
+
+1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
+   `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
+   — no ticket body is read here, because a Pull reads one ticket in full at
+   the moment it admits it:
+
+   - **Candidate scan** — `candidates.mjs --require-label ready-for-agent
+     --with-dropped`, oldest-first, never re-ranked. Its row count is
+     `scanned`, the supply; the rows its to-spec filter removed are
+     `dropped`, counted nowhere.
+   - **Dependency scan**, `next-ticket` step 2, on each row's `d` array. Open
+     blocker → drop.
+   - **Live Exclusions** — a ticket whose ledger row reads `excluded ·
+     behind-pr:#M` or `excluded · behind-issue:#M` stays out while its premise
+     holds (references/pull.md, **Exclusion**).
+   - **In-flight check** — `inflight.sh <N>` per survivor. Exit 1 is taken, and
+     any other non-zero exit is a check that could not answer, which is never
+     free. Both drop the ticket, logged by number.
+
+   It writes the survivors, in order, to `.fleet/shortlist.json` —
+   `{scanned, shortlist: [{n, t}], dropped: [{n, reason}]}` — resolved against the git common dir by
+   `fleet-dir.mjs`, the one locator `ledger.mjs` resolves `.fleet/ledger.md`
+   with too, so you, the tick and a member in its own worktree all name one
+   file. **Exit 0 is the file written,
+   an empty shortlist included** — the empty queue is an answer. **Exit 2 is a
+   refusal**: the scan, the ledger read or the write did not answer, and the
+   previous file stands untouched, because an empty file written then would
+   read as "no work". Never read 2 as empty.
+
+   Every probe fails CLOSED: an unreadable blocker counts as open, an
+   unreadable premise leaves its exclusion standing, an unanswered in-flight
+   check counts as taken. A ticket dropped wrongly waits one refresh; a ticket
+   admitted wrongly costs a Pull's full read at best and two members on one
+   ticket at worst.
+
+   **`--require-label ready-for-agent` mandatory, no fallback** — the script
+   fixes it, and you never run `candidates.mjs --allow-fallback` by hand to
+   widen the list: `ready-for-human` needs a human to brainstorm first and you
+   have no channel to one mid-flight.
+