@feigi/fleet-ctl 3.76.8 → 3.76.9

package/agents/fleet-fix-applier.agent.md

@@ -333,7 +333,8 @@ whose `ledger.mjs filed` failed twice, which the controller's settle records —
 send the one line your brief gives, `<your name>: <outcome> <path>`, and exit.
 **Deferring everything is a normal
 outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
-index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and your
+index, `~/.fleet/bin/fleet-run push-sync.mjs --branch <branch>` prints git's
+`Everything up-to-date`, and your
 report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
 explicitly — silence there is indistinguishable from a member that died. Never
 manufacture a commit to make CI fire.

package/commands/review-and-fix.md

@@ -12,7 +12,7 @@ argument-hint: [pr-number]
    See **Specialists** — those constraints are not optional.
 2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first, and check it in either scope. Out of the PR's ticket scope → defer and file, but **the claim bar runs first:** a suggestion whose claim is about shape — step 5's worth-a-claim bar, recorded `claimKind: shape` — gets no refuter and goes to the closed `PR #<pr> review: the suggestion band, checked` record, and every other out-of-scope suggestion gets the same refuter an in-scope one does, dispatched the same way, before it is filed. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. **Out of scope the refuter decides only where the suggestion is filed — it defers either way, never applied.** Refuted → the closed `PR #<pr> review: the suggestion band, checked` record, never an open issue. Survived, or its refuter crashed or abstained → its own open issue labelled `needs-triage`, citing the verdict, or the run that crashed, in the body. There is no cap on these refuters; your final verdict (step 4) says how many you dispatched against out-of-scope suggestions. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed or abstained always defers, whatever its severity** — and which it is, you read off the finding's **`refutersDispatched`** and **`refutersInconclusive`**, never off severity and never off an empty vote list: `refutersDispatched` above zero with nothing decided means every refuter dispatched against it died or abstained, and `refutersInconclusive` counts the ones that abstained. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **An abstention is not a crash** — a refuter that abstained ran and could not decide: defer and file the finding, citing the inconclusive runs each abstaining refuter named in its `reason`, and never describe its refuters as crashed. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
    **Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to a human instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher, and nothing retries it; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the closed suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
-3. **Run `testCmd` before you commit**, from the worktree, copied verbatim — not a runner you picked. `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you one, it is the repo's own test command**, the Test entrypoint in the repo's Recipe cache (`derive-testcmd.sh <repo> test` prints it). Read it off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no usable Recipe cache (`derive-testcmd.sh` refuses), run the Recipe derivation step first — dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it proves both commands in a throwaway worktree and writes the cache only on proof, and its `RECIPE NOT PROVEN` is a stop, reported with its reason. Never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `git push origin HEAD:<branch>`, the explicit refspec: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`) and any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`) — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Measured twice in one run — one body kept asserting a calibration its own fix had just deleted as false, another kept claiming a hunk the fix had removed as "this diff owns it" — both caught by a finisher's reading rather than by any rule, and both would otherwise have merged intact. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify`.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
+3. **Run `testCmd` before you commit**, from the worktree, copied verbatim — not a runner you picked. `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you one, it is the repo's own test command**, the Test entrypoint in the repo's Recipe cache (`derive-testcmd.sh <repo> test` prints it). Read it off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no usable Recipe cache (`derive-testcmd.sh` refuses), run the Recipe derivation step first — dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it proves both commands in a throwaway worktree and writes the cache only on proof, and its `RECIPE NOT PROVEN` is a stop, reported with its reason. Never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `~/.fleet/bin/fleet-run push-sync.mjs --branch <branch>`, which pushes the explicit refspec `HEAD:refs/heads/<branch>` and then moves the worktree holding `<branch>` to the pushed SHA, or names why it did not and exits 3 with the push landed: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`), any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`), and a refspec push alone leaves the claim worktree's `refs/heads/<branch>` at its old tip — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Measured twice in one run — one body kept asserting a calibration its own fix had just deleted as false, another kept claiming a hunk the fix had removed as "this diff owns it" — both caught by a finisher's reading rather than by any rule, and both would otherwise have merged intact. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify`.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
 4. **Under the fleet, do not hold this wait.** The controller owns a persistent CI Monitor and dispatches a finisher once your report has arrived and CI is green — so push, then report to the controller a **final verdict** (every specialist you dispatched + its outcome + your apply/defer adjudication + how many refuters you dispatched against out-of-scope suggestions + the pushed SHA) and stop. A specialist that has not reported to you is not a verdict line — `hub send` it by name for its report, then ask the controller, before ruling; see **Specialists**. The controller keys "review complete" on that verdict, **never on you merely going idle** — a slow specialist can still be running when your turn ends, and finishing off idle-alone ships a premature label (observed: a PR labelled while its contract-test specialist was still running and about to surface a vacuous pin). A turn-based reviewer re-reading `gh pr checks` each idle cycle rebuilds its whole context for nothing the Monitor lacks. **Standalone (no controller): watch** the run until the diff-validating jobs are green (bind via `ci-state.mjs` below); fix a **genuine** failure and repeat from 3. **Staleness is not a failure:** a `rebase-check` red or heavy jobs `skipped` **solely from a non-zero behind-count** never clears by waiting and must not be rebased away here — see **`skipped` is not `passed`** and **Do NOT rebase to label** below for what it looks like and why. Stop watching and go to 6. A turn-based reviewer that "waits for green" on a behind PR stalls forever and ends its turn without labelling. **`ci-state.mjs` returns `verdict: "no-ci"`** → there is no run to watch, so don't: go straight to 6 and let that step's `--declare-no-ci` branch decide.
 5. File each deferred finding: `gh issue create --label needs-triage` with the finding, `file:line`, why deferred, `Deferred from PR #<pr> review`, and **the finding's `dimension` in the issue body** — the review returns it on every finding, and a backlog that does not carry it cannot be attributed to the specialist that generated it. **The body also carries the evidence triage needs: the refuter's verdict — the `verdictPath` reason, or the review's votes — and the candidate remedy.** **Every issue you create is labelled `needs-triage`; only triage sets `ready-for-agent`** — and the label is never omitted; an unlabelled issue is invisible to both `candidates.mjs --require-label` and the cockpit's pool query, reachable only by a human. **A confirmed defect does not settle its remedy**, so confirming one earns it no other label: a confirmed defect with the remedy still open files `needs-triage`, and so does a finding you are unsure is broken at all. **A finding a refuter CHECKED and did not survive is neither** — it is not a confirmed defect, and you are not unsure whether anything is broken: you measured that nothing is. Refutations go as **one issue per review, titled `PR #<pr> review: the suggestion band, checked`, labelled `wontfix`, and CLOSED** — a run that files them open instead has to be corrected afterwards, as one was on 2026-08-27. Left open they read as queued agent work and rot into filing artifacts; a measured triage pass found a quarter of its `needs-triage` backlog was refuted records, bulk-closable by title shape. Closed is still a durable home — `check` reads the tracker at `--state all`, so a future run re-deriving the finding lands on the evidence rather than re-litigating it. Split the band only where an entry is **not** a refutation: a residual the refuter surfaced, or an out-of-scope finding its refuter let survive or never decided, is real deferred work — and real deferred work earns its own open issue only past a second bar. **Worth a claim: a finding whose own claim is that correct code could be shaped better — style, naming, layout, redundancy, a micro-simplification — never gets its own open issue.** **Neither does a gap in a prose guard — a test holding prose to its wording — unless something acts on the guarded text: an agent follows it as an instruction (a skill, a command, an agent definition, a script's header or usage text, `AGENTS.md`), or a program other than its own guard reads it.** Whether anything does is your judgement, as `claimKind` is, and a gap below this bar is recorded `claimKind: shape`. A gap in a guard's own code — a slow pattern, a dead branch, an unchecked spawn result — takes the stakes of the prose it guards, and a helper several guards share takes the highest of theirs. A missed wording already in the tree is no guard gap — that prose is wrong — and neither is an input already in the tree that trips a guard's code; each files on its own merits. Once the prose is corrected, the observed wording may join the guard's literal ban, never a reader built to catch wordings nobody has written. A below-bar finding's only open question is "is this worth doing?", which answers itself under the repriced triage bar: measured 2026-08-15→31, 133 issues were triage-closed `wontfix` in sixteen days, 121 of them review deferrals, mostly this shape. Append it to the same closed record issue under a `Below the claim bar` heading — `file:line`, dimension, the claim, and a re-open trigger per entry. Closed is a durable home for these too: `check` reads `--state all`, so a run re-deriving the finding lands on the record instead of re-filing — and a later review returning the same finding as `survived`, or a maintainer hitting it, is the promotion signal: file it open then, citing the record. **An in-scope rediscovery step 2 applied is that same promotion signal, and it files nothing** — so the record carries no mark unless you write one: run `check` over each finding step 2 applied as well, and where its tracker rows put one on a `Below the claim bar` entry, comment on that record issue, opening `Promoted — applied, not filed`, and name the entry, that its refuter let it through, and the commit carrying the fix. That comment is the promotion mark this path leaves, and it is **not** a cross-reference — measured on this tracker, a comment mints `cross-referenced` on the issue its own text *names*, never on the issue it sits under (a comment citing a second issue landed on that issue's timeline and nowhere else), so the fixed opening is what carries the signal instead. **The bar reads the finding's claim, never its review band** — a finding that alleges wrong behavior, whatever band it sat in, `unverified`-with-crashed-refuters included, is above this bar and files open, `needs-triage`, which is why a band cannot carry this decision. Do **not** reach for phase 0's **decided?** test here. That is a *consumption* gate, and whether a filed issue is decided enough to reach it is triage's call, never the filer's. **The cost of this rule is watched:** open `needs-triage` issues citing `Deferred from PR` above 40 on 3 consecutive run dates send the filing rule back to the maintainer — batch triage, a fleet triage role, or a different bar. **Dedupe through `~/.fleet/bin/fleet-run ledger.mjs check "<subject>"`, never a bare `gh issue list --search`** — the duplicate class that guard exists to catch was filed from *here*: the ledger row for the finding rediscovered five times in one measured run carries a reviewer's own source tag, `(review-pr-108)`. `check` reads this run's filed list *and* the tracker at `--state all`, so a closed duplicate still counts. Exit **1** is already filed in this run; exit **3** is a clean ledger with matching tracker rows that score against the subject — read the ones it prints and comment on the existing follow-up rather than filing a second issue. **Exit 0 is not automatically "safe to file"**: it covers `clean`, `soft-hit` and `unverified` alike, and an unreachable `gh` degrades to a ledger-only answer that says `TRACKER NOT CHECKED`, so read the stdout `verdict` to tell a tracker that was searched and clean from one nobody read — under `unverified`, search it yourself before filing — or, for the applied-promotion comment above, before treating a tracker nobody could read as a reason to skip it. **`soft-hit` is the answer that costs most to misread**: it means related rows were found and none of them was established as a duplicate — a near-miss above the floor, or tracker rows the scorer rates 0.00 — so read the rows it printed and decide, and never treat that exit 0 as permission. Exit **2** is a usage error, meaning nothing was checked at all: fix the invocation and re-run, never read it as a duplicate. Full exit-code and `verdict` semantics live in `$(~/.fleet/bin/fleet-run --root)/skills/run-team/references/ledger.md`, which `SKILL.md`'s **Run ledger** section points at — read them there rather than restating them here. **The guard dedupes, it never drops:** a duplicate becomes a comment on the issue that already covers it, never a dropped finding. **Record every issue you create, at once:** immediately after each `gh issue create`, run `~/.fleet/bin/fleet-run ledger.mjs filed <N> "<subject>"` — `<N>` the number `gh issue create` printed, and **the same subject string you passed to `check`**, so the next `check` for that finding meets it in the filed list instead of scoring a rewording. Without it the guard's ledger half never holds a row, and its exit **1** can never fire. If `filed` fails, retry it once; if it fails again, leave the issue alone — it exists and is correct — and report it as `unrecorded: #N <subject>`, so the controller runs `filed` for it. Report `filed: #N <subject>` for every issue you created — under the fleet, in your report to the controller. **The one window the guard cannot see:** `check` → `gh issue create` → `filed` is three commands, and the ledger's lock covers each alone, so two filers can both read `clean` in the seconds before either records. That gap is accepted, never a reason to skip `filed`. Post the numbers as one PR comment.
    **A duplicate that should hold an open deferral is a comment, never a relabel.** Where the guard lands a finding whose home is an open issue on an existing one that is open, cite the refuters' verdict — or the review's votes — in the comment you leave there, and change no label. Never relabel `ready-for-agent` down to `needs-triage`: a `ready-for-agent` issue already holds a `needs-triage` finding, because triage already promoted it, and a later run's crashed refuters are no reason to send it back. A closed one cannot hold it: file a new open issue citing it, as the promotion rule above does for the closed record.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.76.8",
+  "version": "3.76.9",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/push-sync.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// Push `HEAD` to `refs/heads/<branch>` on origin, then move the worktree that
+// holds `refs/heads/<branch>` to the pushed SHA.
+//
+//   push-sync.mjs --branch <branch> [--force-with-lease]
+//
+// WHY. A member in a `--detach` worktree can only push by refspec, and a
+// refspec push moves origin's ref alone: the claim worktree claim-ticket.sh
+// made (`worktree add --no-track -b`) still has `refs/heads/<branch>` at the
+// old tip, and everything that later reads that local ref reads a head the PR
+// no longer has. `git branch -f` refuses a branch a worktree has checked out,
+// and `git update-ref` would move the ref while leaving that worktree's index
+// and files at the old tip, so this uses neither: it runs
+// `git -C <claim worktree> reset --keep <pushed>`, which moves the ref, the
+// index and the working tree together, and covers a fast-forward and a
+// rebased (non-fast-forward) push alike.
+//
+// BEFORE THE PUSH it reads origin's head of the branch (`ls-remote`) and the
+// local `refs/heads/<branch>`. A failed or timed-out `ls-remote` does not stop
+// the push — it only leaves the ref guard's "equals origin's pre-push head"
+// alternative below unmet; the ancestor alternative can still hold.
+//
+// THE PUSH is `git push [--force-with-lease] origin HEAD:refs/heads/<branch>`,
+// git's own output passed through on stderr. A failed push — a denied lease
+// included — exits with the push's own status, is never retried with
+// `--force`, and nothing is synced.
+//
+// THE SYNC, after a push that landed. The holder is found by parsing
+// `git worktree list --porcelain -z` record by record (NUL-delimited, so a
+// path holding a newline cannot split a record). The move happens only when
+// both guards hold:
+//   - the holder is clean: `git status --porcelain` prints nothing, untracked
+//     files included;
+//   - the local ref read before the push equals origin's head read before the
+//     push, or is an ancestor of the pushed SHA. A rebase's force-push
+//     replaces exactly the tip origin had, so under this guard no commit that
+//     was only local is dropped.
+// A guard that fails moves nothing: the refusal names each failed condition
+// and says the push itself landed. An ancestry check git cannot answer —
+// `merge-base --is-ancestor` exiting other than 0 or 1, or not running —
+// refuses as `ancestry-check-failed` with git's own error, never as a
+// divergence. The clean-tree check is the only protection against a member
+// working in the holder at the same moment.
+// A holder already at the pushed SHA — the attached claim worktree running
+// this itself — has nothing to move and is not checked.
+//
+// OUTPUT, on stdout, in this order: one `push:` line, then the `sync:`
+// outcome — one line, or on a refusal one line per failed condition — then
+// one `read-back:` line comparing `refs/heads/<branch>` with the pushed
+// SHA. A failed push prints the `push:` line alone.
+//
+// Exit 0: pushed, and the holder is at the pushed SHA — or no worktree holds
+//         the branch (`sync: no worktree holds <branch>`), where the push
+//         result stands.
+// Exit 2: bad usage, HEAD names no commit, or git could not run or read HEAD.
+//         Nothing was pushed.
+// Exit 3: pushed, NOT synced — a guard refused, a git call in the sync failed,
+//         or the read-back differs. Origin has the pushed SHA.
+// Any other non-zero: the push failed, with git's own exit status.
+
+import { spawnSync } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { defineFlags, makeDie, writeAll } from "./arg.mjs";
+import { gitEnv } from "./git-env.mjs";
+import { isCLI } from "./is-cli.mjs";
+
+const NAME = "push-sync";
+const die = makeDie(NAME);
+const EXIT_NOT_SYNCED = 3;
+// `ls-remote` moves refs, no objects, so it gets a short bound.
+const LS_REMOTE_TIMEOUT_MS = 30_000;
+const USAGE = "usage: push-sync.mjs --branch <branch> [--force-with-lease]";
+
+const say = (line) => writeAll(1, `${line}\n`);
+
+function git(args, { timeout, stdio } = {}) {
+  return spawnSync("git", args, {
+    env: gitEnv(),
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    timeout,
+    stdio,
+  });
+}
+
+const ok = (r) => !r.error && r.status === 0;
+const why = (r) => r.error?.message ?? (r.signal ? `killed by ${r.signal}` : (r.stderr ?? "").trim() || `exit ${r.status}`);
+
+/** The commit `ref` names, or null when it names none. */
+function commitOf(ref) {
+  const r = git(["rev-parse", "-q", "--verify", `${ref}^{commit}`]);
+  return ok(r) ? r.stdout.trim() : null;
+}
+
+/**
+ * Origin's head of `branch`: `{ok: true, sha}` (`sha` null when origin has no
+ * such branch) or `{ok: false, why}`. An exact field match, never ls-remote's
+ * pattern, which matches any ref ENDING in it on a `/` boundary.
+ */
+function remoteHead(branch) {
+  const ref = `refs/heads/${branch}`;
+  const r = git(["ls-remote", "origin", ref], { timeout: LS_REMOTE_TIMEOUT_MS });
+  if (!ok(r)) return { ok: false, why: why(r) };
+  for (const line of r.stdout.split("\n")) {
+    const [sha, name] = line.split("\t");
+    if (name === ref) return { ok: true, sha };
+  }
+  return { ok: true, sha: null };
+}
+
+/**
+ * The path of the worktree whose record in `listing` — the output of
+ * `git worktree list --porcelain -z` — carries `branch refs/heads/<branch>`,
+ * or null. Records end with an empty field; a record's first field is its
+ * `worktree <path>`.
+ */
+export function claimHolder(listing, branch) {
+  const want = `branch refs/heads/${branch}`;
+  let path = null;
+  for (const field of listing.split("\0")) {
+    if (field === "") path = null;
+    else if (path === null && field.startsWith("worktree ")) path = field.slice("worktree ".length);
+    else if (field === want && path !== null) return path;
+  }
+  return null;
+}
+
+/** The push's exit status as a shell would report it. */
+function pushStatus(r) {
+  if (r.status !== null) return r.status;
+  const n = r.signal ? osConstants.signals[r.signal] : undefined;
+  return n ? 128 + n : 1;
+}
+
+function readBack(branch, pushed) {
+  const now = commitOf(`refs/heads/${branch}`);
+  if (now === null) {
+    say(`read-back: refs/heads/${branch} is absent; the pushed SHA is ${pushed}`);
+    return false;
+  }
+  const same = now === pushed;
+  say(`read-back: refs/heads/${branch} is ${now} — ${same ? "equals" : "differs from"} the pushed ${pushed}`);
+  return same;
+}
+
+function refuse(branch, pushed, reasons) {
+  for (const [name, text] of reasons) {
+    say(`sync: refused (${name}): ${text}; nothing moved — the push itself landed`);
+  }
+  readBack(branch, pushed);
+  process.exit(EXIT_NOT_SYNCED);
+}
+
+function main() {
+  const flags = defineFlags(die, { flags: { branch: "value", "force-with-lease": "bool" } });
+  flags.sweep();
+  flags.stray();
+  const branch = flags.arg("branch");
+  if (branch === null) die(`--branch is required\n${USAGE}`);
+  const lease = flags.has("force-with-lease");
+  const format = git(["check-ref-format", `refs/heads/${branch}`]);
+  if (format.error || format.signal) die(`git could not run: ${why(format)}`);
+  if (format.status !== 0) die(`'${branch}' is not a valid branch name`);
+
+  // `rev-parse -q --verify` says nothing when HEAD is unborn; anything it does
+  // say is git failing to read the repository at all.
+  const head = git(["rev-parse", "-q", "--verify", "HEAD^{commit}"]);
+  if (!ok(head)) {
+    die(head.error || head.signal || head.stderr.trim() !== "" ? `cannot read HEAD: ${why(head)}` : "HEAD names no commit — nothing to push");
+  }
+  const pushed = head.stdout.trim();
+  const remoteBefore = remoteHead(branch);
+  const localBefore = commitOf(`refs/heads/${branch}`);
+
+  const pushArgs = ["push", ...(lease ? ["--force-with-lease"] : []), "origin", `HEAD:refs/heads/${branch}`];
+  writeAll(2, `$ git ${pushArgs.join(" ")}\n`);
+  const push = git(pushArgs, { stdio: ["ignore", 2, 2] });
+  if (push.error) die(`git push could not run: ${push.error.message}`);
+  if (push.status !== 0) {
+    const status = pushStatus(push);
+    say(`push: failed (exit ${status}); nothing synced, nothing retried`);
+    process.exit(status);
+  }
+  say(`push: landed ${pushed} on origin refs/heads/${branch}`);
+
+  const list = git(["worktree", "list", "--porcelain", "-z"]);
+  if (!ok(list)) refuse(branch, pushed, [["worktree-list-failed", `git worktree list failed: ${why(list)}`]]);
+  const holder = claimHolder(list.stdout, branch);
+  if (holder === null) {
+    say(`sync: no worktree holds ${branch}`);
+    readBack(branch, pushed);
+    process.exit(0);
+  }
+  if (localBefore === pushed) {
+    say(`sync: ${holder} already at ${pushed}`);
+    process.exit(readBack(branch, pushed) ? 0 : EXIT_NOT_SYNCED);
+  }
+
+  const reasons = [];
+  const st = git(["-C", holder, "status", "--porcelain"]);
+  if (!ok(st)) reasons.push(["status-unreadable", `git -C ${holder} status failed: ${why(st)}`]);
+  else if (st.stdout !== "") reasons.push(["claim-worktree-dirty", `${holder} has uncommitted or untracked changes`]);
+
+  const local = localBefore ?? "(absent)";
+  const equalsRemote = remoteBefore.ok && remoteBefore.sha !== null && remoteBefore.sha === localBefore;
+  if (!equalsRemote) {
+    const remote = !remoteBefore.ok ? `unread: ${remoteBefore.why}` : remoteBefore.sha ?? "absent";
+    // `--is-ancestor` answers 0 (an ancestor) or 1 (not one); anything else is
+    // git failing to answer, which is no evidence of a divergence.
+    const ancestry = localBefore === null ? null : git(["merge-base", "--is-ancestor", localBefore, pushed]);
+    if (ancestry !== null && !ok(ancestry) && (ancestry.error || ancestry.status !== 1)) {
+      reasons.push([
+        "ancestry-check-failed",
+        `refs/heads/${branch} at ${local} does not equal origin's pre-push head (${remote}), and git merge-base --is-ancestor ${local} ${pushed} failed: ${why(ancestry)}`,
+      ]);
+    } else if (ancestry === null || !ok(ancestry)) {
+      reasons.push([
+        "claim-ref-diverged",
+        `refs/heads/${branch} at ${local} neither equals origin's pre-push head (${remote}) nor is an ancestor of the pushed ${pushed}`,
+      ]);
+    }
+  }
+  if (reasons.length > 0) refuse(branch, pushed, reasons);
+
+  const reset = git(["-C", holder, "reset", "-q", "--keep", pushed]);
+  if (!ok(reset)) refuse(branch, pushed, [["reset-failed", `git -C ${holder} reset --keep ${pushed} failed: ${why(reset)}`]]);
+  say(`sync: moved ${holder} from ${local} to ${pushed}`);
+  process.exit(readBack(branch, pushed) ? 0 : EXIT_NOT_SYNCED);
+}
+
+if (isCLI(import.meta.url)) main();

package/skills/next-ticket/SKILL.md

@@ -105,9 +105,15 @@ and a member sent into one is on `## HEAD (no branch)`, where the push above exi
 the cause, so no `-u`/force combination reaches it: the unqualified `HEAD`
 destination is, and plain `git push origin HEAD` fails the same way while a bare
 `git push` exits 128 (`fatal: You are not currently on a branch`). Name the branch
-instead — `git push --force-with-lease origin HEAD:<branch>` (measured 2026-09-18,
-git 2.50.1: exit 0). A worktree `claim-ticket.sh` claimed is on its branch, where
-the push above is the correct one.
+instead, through the helper — `~/.fleet/bin/fleet-run push-sync.mjs --branch <branch> --force-with-lease`.
+A refspec push alone moves origin's ref and leaves the claim worktree's
+`refs/heads/<branch>` at its old tip; the helper pushes `HEAD:refs/heads/<branch>`,
+then moves the worktree holding `<branch>` to the pushed SHA with `reset --keep`,
+only when that worktree is clean and its branch was origin's head or an ancestor
+of the push. Exit 3 is pushed but not synced, its refusal named; exit 2 refused
+before pushing anything; any other non-zero is the push's own failure, nothing
+synced. A worktree `claim-ticket.sh` claimed is on its branch, where the push
+above is the correct one.
 
 `--force-with-lease` matters only on a re-push: step 7 rebases immediately before pushing, so re-entering step 7 after an earlier push needs the force to land the rebased commits. On a re-push the force is load-bearing: stop and report the denial, never retry with a plain `--force`; a denial on a branch that has never been pushed is safe to route around with a plain `git push -u origin HEAD` instead.
 

package/skills/run-team/briefs/fix-applier.md

@@ -66,11 +66,11 @@ claim, never your patch.
 Bring `<branch>` current with `origin/main`, resolving every conflict by the
 **No-undo audit** in `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md`.
 Run `<testCmd>` from the worktree before you push, then push with
-`git push origin HEAD:<branch>`. Report the new head, or that no conflict was
+`~/.fleet/bin/fleet-run push-sync.mjs --branch <branch>`. Report the new head, or that no conflict was
 left.
 ## kind: red-check
 Read the failing job's log and fix the cause. Run `<testCmd>` from the
-worktree before you push, then push with `git push origin HEAD:<branch>`.
+worktree before you push, then push with `~/.fleet/bin/fleet-run push-sync.mjs --branch <branch>`.
 Report the new head and **stop**: do not watch, poll or wait for CI — the
 controller owns the next run on the pushed head. A red that is not yours to
 fix — a flake that passes on rerun, or staleness — gets nothing pushed: report

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

@@ -92,7 +92,7 @@ reads gates and never injects a fault.
 the worktree from. Pass it as `--branch`, because
 the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
 with `--detach`, and there `git branch --show-current` prints nothing and exits 0
-(measured 2026-09-18, git 2.50.1), so `git push origin
-"HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
-'HEAD:'`. A brief rendered without it would leave the push no destination at
-all, which is why the renderer requires it.
+(measured 2026-09-18, git 2.50.1), so `~/.fleet/bin/fleet-run push-sync.mjs
+--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.