@feigi/fleet-ctl 3.82.2 → 3.82.4

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

@@ -1,8 +1,9 @@
 # CI reading and staleness
 
 Why green not verdict, why absence is its own verdict, why conclusion not
-stable, why behind-count only honest signal. Assertions live in SKILL.md
-Phase 3 event loop + Merge bot sections; evidence here.
+stable, why behind-count only honest signal, why the tick runs on every wake
+and why the beat is shaped as it is. Assertions live in SKILL.md's wake table,
+**Nothing to do: arm the beat** and **Own the CI waits**; evidence here.
 
 ## Own the CI waits — members cannot hold across a run
 
@@ -13,6 +14,9 @@ latest runs, keyed `<run-id>:<attempt>:<conclusion>` so each terminal state
 fires once, emits behind-count with it: `success` on branch 8 behind not
 actionable, that distinction most of traffic.
 
+Members are turn-based and cannot hold across a ten-minute
+run — they rebase, push, stop.
+
 ## Run-binding: take the whole row from one read
 
 Take run id, head, conclusion from **one** `gh run list --json` row. Watcher
@@ -100,3 +104,33 @@ agent — measured twice, see **A member runs its test suite in the foreground**
 roughly two hours — and `run-merge-bot.md`'s CI gate states the general rule:
 "whatever wakes you is external and may never come". So hold the wait yourself,
 exactly the way that gate does:
+
+## Tick on every wake
+
+**Why every wake.** A merge cascade is a firehose of merges, CI greens and
+rebases that holds your attention on the merge side while the implementer side
+drains to 0 and stays there — 0 implementers emit no completion event, so a
+refill that waited for one would never fire. A tick on every wake you are
+already handling is what makes that drain visible. **Every wake is still an
+edge, so none covers a fully drained queue**: no members and no open PRs is no
+event at all, and the tick goes unrun. That state is the heartbeat's.
+
+## The beat's ceiling is a real bound
+
+The interval doubles while the fleet asks for nothing and stops at `--ceiling`,
+so a quiet night costs ~26 wakes instead of ~96. **The ceiling is a real bound,
+not a formality**: supply grows from OUTSIDE the fleet — a ticket you triage,
+one a reviewer filed `needs-triage` included — and that arrival emits no
+event either, so the ceiling is your worst-case latency for noticing it.
+Do not raise it past 30 minutes.
+
+## When you stop on purpose, say why
+
+The beat leaves a dated mark on every hold, so a run
+that dies abruptly (a crashed harness, a closed terminal, an OOM kill) is
+detected by its mark going stale. A run that stops KNOWINGLY can do better
+than being detected, and nothing else can write the reason afterwards:
+
+```bash
+~/.fleet/bin/fleet-run fleet-heartbeat.mjs --stop "budget exhausted"
+```

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

@@ -1,6 +1,6 @@
 # The CI watcher: why its block is shaped the way it is
 
-Evidence for the rules SKILL.md states beside Phase 3's watcher block, keyed by the rule each justifies.
+Evidence for the rules SKILL.md states beside its watcher block, under **Own the CI waits**, keyed by the rule each justifies.
 
 ## The pass is budgeted at 4 core REST units per listed PR
 
@@ -97,3 +97,42 @@ fixed interval stalls the fleet longer than the outage itself would have. A
 retry-and-wait loop is what turns a 60s outage into a stalled member. Report it,
 keep the local work moving (git, tests and mutation runs are all unaffected),
 re-probe.
+
+## A probe that cannot read is a transition event, not silence
+
+The natural
+watcher shape — `st=$(ci-state.mjs --pr "$pr" 2>/dev/null) || continue` — fails
+closed correctly and then throws the failure away, so a rate-limited probe emits
+NOTHING and "no event" becomes indistinguishable from "not green yet". Every
+open PR stalls unlabelled while the run reads as merely quiet; observed live
+twice.
+
+## It has to latch
+
+An unlatched line at a 120s poll gets the Monitor
+auto-stopped for volume during even a two-minute outage, reintroducing the same
+blindness by another route.
+
+## Guard every probe, not just the ones with a verdict field
+
+The block makes
+several API calls, and `gh pr list` is the one that looks like
+plumbing rather than a probe. A non-quota failure there (secondary/abuse limit,
+5xx, network blip, expired token) does not lower `.resources.core.remaining`, so
+the budget gate clears, and an unguarded `for pr in $(gh pr list …)` then
+iterates zero times over the empty substitution: no error, no latch, no DEGRADED
+line — total silence per tick, which is exactly what this section exists to
+remove.
+
+## A readable list can still be a short one
+
+`gh pr list` stops at its
+`--limit` — 30 when the flag is absent — with exit 0 and no warning, so a list
+that fills its limit reads exactly like one that happens to be that long, and
+every open PR past it goes unwatched without a line.
+
+## Judge `ci-state` on its payload, never its exit code
+
+`not-green` is an
+ordinary, frequent state that exits non-zero, so a watcher treating any non-zero
+exit as an outage misfires constantly on PRs that are merely in progress.

package/skills/run-team/references/correction-tickets.md

@@ -61,3 +61,9 @@ benign-looking answer. Measured once: `grep -c 'settled by:\s+x'` answers
 an absence counts only after the same command, with the same flags, finds a
 line known to match: a command that cannot find a match settles nothing, and
 under `Verified:` its zero reads as a checked absence.
+
+## The settling command for "which files read X" is never a literal-path grep
+
+The path is assembled in more than one spelling here, one of them behind
+a local `read` helper, so a grep for the path string answers with the files that
+merely *name* it — comments included — and misses the files that build it.

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

@@ -1,6 +1,6 @@
 # The finisher: why its gate and duties are shaped the way they are
 
-Evidence for the finisher rules SKILL.md states in **Reviewers**, keyed by the rule each justifies.
+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.
 
 ## An unanswered question from the member is an outbox item
 
@@ -107,3 +107,15 @@ to the fleet's worktree home, so a tree under `<scratch>` is a `kept` entry
 it reports and never collects. No claim built the tree you added, so it has
 `./agent-test` only if the repository tracks one — run that or `<testCmd>`
 in it, per `references/isolation.md`, **A reused worktree may lack the runner**.
+
+## Take the label off before you approve any push
+
+The label is a
+verdict on the tree the finisher read, and a GitHub label does not follow the
+branch — on one PR it survived a push and came to sit on a commit nobody had
+audited. The token is how the tick tells your
+removal from a finisher that never labelled — a tick run between a removal and
+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.

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

@@ -1,10 +1,10 @@
 # Member lifecycle: naming, fresh context, recovery
 
-Why member name load-bearing, why every member single-use, how a member's job outcome (`completed`/`failed`/`cancelled`) and peer liveness (`running`/`idle`/`parked`) decide its recovery. Assertions these justify live in SKILL.md's "Rules that fail silently", Phase 3, Reviewers, Failure handling sections; evidence here.
+Why member name load-bearing, why every member single-use, how a member's job outcome (`completed`/`failed`/`cancelled`) and peer liveness (`running`/`idle`/`parked`) decide its recovery. Assertions these justify live in SKILL.md's "Rules that fail silently", wake table, Reading a review result, Failure handling sections; evidence here.
 
 ## Every member is named
 
-The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch and result are recorded on the PR's row with `ledger.mjs review <pr#>`), `finisher-pr-<pr#>` (Phase 3's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
+The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch and result are recorded on the PR's row with `ledger.mjs review <pr#>`), `finisher-pr-<pr#>` (the finisher gate's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
 
 ## The coordination contract
 

package/skills/run-team/references/merge-bot.md

@@ -1,6 +1,6 @@
 # Landing a change on main
 
-Evidence for the rule SKILL.md states in **Fix the tooling mid-run**, keyed by the rule it justifies.
+Evidence for the rules SKILL.md states in **Fix the tooling mid-run** and in the `ready-to-merge` wake, keyed by the rule each justifies.
 
 ## A mid-run tooling fix lands through a PR
 
@@ -12,3 +12,8 @@ end of a 7-PR run. A mid-run tooling fix goes through a PR like every other
 change, and that PR faces every required check any other PR faces — the set
 `.github/rulesets/main.json` declares — so it carries a release label too.
 Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
+
+## You own the merge watcher, not the bot
+
+A dying member takes a watcher down with it
+and the queue stops silently.

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

@@ -72,7 +72,7 @@ walks the run from "could not look" to "certified clean" in one step, so
 `--record` itself refuses over a baseline it cannot read, over one a newer
 plugin wrote, and on any git read that fails. The exceptions are an
 older-version baseline and a baseline whose commit is missing from the
-repository; Phase 3's tick lines say how each is cleared.
+repository; the tick's rows say how each is cleared.
 `main-checkout.mjs --check` prints the same answer
 without a tick.
 On `MAIN-CHECKOUT-DIRTY` the maintainer may instead ignore a stray path that is untracked and new since the baseline: an entry in `.git/info/exclude` or in the global excludes file hides it from the check, and the hold clears on the next tick with no re-record. Ignoring never clears a tracked or staged file's change, which `git status` reports whatever the excludes say, nor a pattern that also matches a path the baseline holds, which then reads as changed. Ignoring is the maintainer's decision, never the controller's: the controller never writes an exclude or a `.gitignore` entry. Keep the pattern narrow, because an ignored path is invisible to this check, so a later member write that matches it is never seen.
@@ -273,15 +273,15 @@ Before the rotation, `phase0.mjs` puts the held-aside receipt (`phase0.previous.
 `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch>
 --after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
 so a run that merges nothing still reclaims the previous run's leftovers
-(**Reclaim scratch after each merge pass** says what it removes).
+(`reclaim-scratch.mjs`'s header says what it removes).
 `--after-rotate` goes on this call always and on no other: rotate leaves
 no ledger behind when it carried nothing, and the flag reads that absence
 as "no live token" — rotate's own verdict — where without it the script
 refuses. A ledger rotate did write is read as usual. Record nothing on the
 ledger and act on nothing in its receipt.
 
-Without `--after-rotate` — the per-pass sweep **Reclaim scratch after each
-merge pass** runs — no ledger refuses the call (exit 2, nothing removed):
+Without `--after-rotate` — the per-pass sweep `tick --apply` runs after each
+merge pass — no ledger refuses the call (exit 2, nothing removed):
 mid-run there is always one, so its absence is a fault to look at, never
 permission. A `gh` that cannot answer keeps every PR- and ticket-keyed entry.
 It prints one JSON receipt — `removed`, `kept` and `failed`, each entry with
@@ -342,8 +342,8 @@ invalid — a command that no longer runs, or an Install step that changed
 the tree — is the one mid-run trigger: dispatch `derive-recipe` again
 exactly as above, then retry what refused. The Install step's refusals
 fire after the claim has labelled the ticket and created its worktree, so
-release that claim with `release-ticket.sh` first (**Release the claims
-that never became PRs**). A red suite never triggers it: a failing test is
+release that claim with `release-ticket.sh` first (SKILL.md's Failure handling
+row for a claim abandoned mid-run). A red suite never triggers it: a failing test is
 a finding, not a stale Recipe. **Stall:** `RECIPE NOT PROVEN` from any
 derivation, or a second invalid-cache refusal after this run's one
 re-derivation, halts the run — no Pull, no claim, no review dispatch — and

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

@@ -232,7 +232,7 @@ terminating in exactly one dispatch or an empty shortlist:
    `tier=<CELL>` exactly when `DRAW` is not `-`; then phase 2 at once: claim
    what you are about to dispatch; dispatch what you have just claimed. Router
    exit 2 → no row and no dispatch: release the claim (`release-ticket.sh`, SKILL.md's
-   **Release the claims that never became PRs**) and emit an event, a probe that could not look — a table the router
+   Failure handling row for a claim abandoned mid-run) and emit an event, a probe that could not look — a table the router
    refuses refuses every Pull.
 
 **The Pull table** — every verdict a Pull can reach, and the one thing each
@@ -259,7 +259,7 @@ dispatch.
 ## Relabels and exclusions
 
 **A Pull never re-admits a ticket already relabelled.** The shortlist file can
-be older than a relabel — this run's own Pulls, or a demotion in phase 3 — so
+be older than a relabel — this run's own Pulls, or a bail's relabel under **Relabel causes** — so
 read the ticket's labels in step 3's full read (`--json
 title,body,comments,labels`) and drop it when `ready-for-agent` is gone. A Pull
 that trusted a list built before the relabel landed would hand a ticket the
@@ -324,8 +324,8 @@ its re-derive-once rule.
 
 **Materialize the isolation envelope as a file, not a briefing.** The claim
 writes the runner, `agent-test`, into the fresh worktree it creates: an exec of
-the Recipe's Test entrypoint, through the suite-slot wrapper (see SKILL.md's **The
-suite slot bound**), that exports one port triple derived from `<N>`
+the Recipe's Test entrypoint, through the suite-slot wrapper (see `suite-slot.mjs`'s
+header), that exports one port triple derived from `<N>`
 (so collisions stay impossible), kept out of `git status` through the
 repository's exclude file. A repository that tracks its own `agent-test` keeps
 it byte-identical, with whatever isolation that repository built, and takes the

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

@@ -1,6 +1,6 @@
 # Reaping merged branches and worktrees
 
-Why reap runs after each merge pass, why `commit-commands:clean_gone` disqualified, why hand-rolled reap shaped this way (implemented by `reap.sh`), and why a claim that never became a PR needs a different script (`release-ticket.sh`). Assertions these justify live in SKILL.md's "Reap after each merge pass" and "Release the claims that never became PRs" sections; evidence here.
+Why reap runs after each merge pass, why `commit-commands:clean_gone` disqualified, why hand-rolled reap shaped this way (implemented by `reap.sh`), and why a claim that never became a PR needs a different script (`release-ticket.sh`). Assertions these justify live in SKILL.md's **Merge-bot pass reports done** wake and its Failure handling row for a claim abandoned mid-run; evidence here.
 
 ## Reap after each merge pass, not once at the end
 

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

@@ -1,6 +1,6 @@
 # Reviewers: the evidence behind the review-side rules
 
-Evidence for rules SKILL.md states in Phase 2 and **Reviewers**, keyed by the rule each justifies.
+Evidence for rules SKILL.md states in Phase 2 and **Reading a review result**, keyed by the rule each justifies.
 
 ## A sizing verdict is a measurement only if it post-dates the run that produced it
 
@@ -96,3 +96,38 @@ with `--detach`, and there `git branch --show-current` prints nothing and exits
 --branch "$(git branch --show-current)"` is handed an empty branch and exits 2
 before pushing anything. A brief rendered without it would leave the push no
 destination at all, which is why the renderer requires it.
+
+## A review runs off your turn and relays nothing
+
+**`selectDimensions` sizes the fan-out to the diff and the verify budget
+follows severity.** It cuts one immutable
+snapshot, verifies every critical/important finding adversarially,
+re-dispatches each crashed specialist and each crashed refuter pair once before
+it assembles the result, and has `agent()` return **into the script**, so no
+report can go undelivered and you relay nothing — the delivery failure that
+cost one fleet five reports on one PR and four on another. None of it runs on
+your turn: a review takes 20-40 minutes, and a controller that held its turn
+for each one, one at a time, was what left implementer slots empty.
+
+## `testEnvironment` says what the shared test run is evidence about
+
+The snapshot is `git archive`d and then
+`git init`ed with one commit, and the block that cuts it compares that commit's
+tree hash against the reviewed commit's: verified, a suite run in the
+snapshot collects and runs what a checkout does, and a red is a fact about the
+tree. UNVERIFIED, it is not — tests that ask git what ships decline or fail for
+the environment, and this field carries which line of the cut failed.
+
+## `dimensionsUnrun` names a gap; an empty dimension does not
+
+The rule this replaces — treat any dimension with nothing in
+`survived`/`refuted`/`unverified` as unrun — was the workaround for having no
+such field, and it over-refuses in the direction that costs work: a dimension
+that ran clean has nothing in those three either.
+
+## A failed review is a failure event, not a clean review
+
+The review throws on missing `args.pr`/`args.worktree` and on a snapshot agent
+that returned no tree, and a failure surfaces mid-loop, where "react, never
+block" makes it easy to log and carry on — leaving a PR that *reads* as
+reviewed and is not.

package/skills/run-team/references/shell-traps.md

@@ -6,9 +6,9 @@ Monitor and Bash commands run under **zsh**, and the shell in SKILL.md is
 prescriptive — copied verbatim into a watcher or into the merge bot's agent
 body. So every trap here is a zsh-vs-bash difference that ships as a
 green-looking gate: correct in the shell you tested in, silently wrong in the
-one it runs in. Phase 3's monitor paragraph points here instead of restating
-any of it. The merge bot's agent body is the one place this block is copied
-whole (see **Merge bot**); the other deliberate copy is named at the end.
+one it runs in. **Own the CI waits**'s monitor paragraph points here instead of
+restating any of it. The merge bot's agent body is the one place this block is
+copied whole (see **The merge bot**); the other deliberate copy is named at the end.
 
 **zsh word-splits an unquoted command substitution's result; it does NOT split an unquoted parameter expansion.**
 
@@ -26,12 +26,12 @@ $prs
 EOF
 ```
 
-The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase 3's block uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can.
+The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what the watcher block under **Own the CI waits** uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can.
 
 **`</dev/null` every command inside a `while read` loop.**
 
 **A probe that could not look emits an event; it never `continue`s.** Stated in
-full at *A probe that cannot read is a transition event, not silence* in Phase 3,
+full at *A probe that cannot read is a transition event, not silence* under **Own the CI waits**,
 and it binds every watcher in SKILL.md rather than that one block: the third
 value beside pass and fail is what turns a broken loop into a loud failure
 instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]

package/skills/run-team/references/tick-rows.md

@@ -21,14 +21,14 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
   filter kept out of `supply`, read off the shortlist's `dropped`. Never
   actionable. Log them as specs awaiting to-tickets (phase 0), not as no work.
 - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
-  a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**Reviewers**). Printed
+  a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**The fix-applier**). Printed
   ahead of reviews on purpose: finishing what is started beats starting more.
 - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
-  (**Reviewers**).
-- `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
+  (**The reviewer**).
+- `DISPATCH merge-bot` — the next `merge-bot-<n>` (**The merge bot**).
 - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled`, yet the open
   list shows PR M without `ready-to-merge`, and no `label-off=` (**Run ledger**)
-  accounts for the removal. Apply the finisher gate (**Reviewers**: the
+  accounts for the removal. Apply the finisher gate (**The finisher gate**: the
   `check` job green on the current head), then dispatch the next-suffix
   finisher at that head, one letter past the highest the PR has used: render
   its brief with `dispatch-prompt.mjs render finisher --kind repair --member