@feigi/fleet-ctl 3.127.9 → 3.128.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -20,7 +20,7 @@ Label names in this file are roles; the Label map gives the string to type; a me
20
20
  **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 suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
21
21
  **Give every entry whose finding stands a Charge:** `charge` — `false-claim`, `unmet`, `both` or `none` — and, with `none` only, a `chargeReason`: `defect-outside-acceptance` (a defect outside the ticket's acceptance criteria, which no text the implementer wrote claims is otherwise), `not-the-implementers-text` (the false text predates the PR, or comes from the ticket) or `claim-about-untouched-code` (a claim about code the change does not touch). A `survived` finding not deferred `false-rationale` stands, and so does every `refuted` one you reverse; an `unverified` one never does. Charge the work as submitted — a finding you apply is charged as if it were still there — by the definitions of `closed_own_ticket` and `minted_false_claim` in the header of `docs/metrics/tier-outcomes.tsv`, against the ticket as its implementer was dispatched with it; an entry scoped `out` is charged `none`. The check requires a Charge on every standing entry of the record answering the PR's first review — the first that counted no survived and no unverified finding, or else the first a fix-applier answered — and a record answering a later review, or one checked with no ledger, needs none. Wherever a `charge` or `chargeReason` appears it is judged: an unknown value, `none` with no `chargeReason`, a `chargeReason` with any other `charge` or with none, and an out-of-scope entry charged anything but `none` are each a mismatch.
22
22
  3. **Run `checkCmd` and `testCmd` before you commit**, from the worktree, each copied verbatim — not a runner you picked. `checkCmd` is the Recipe's Check step and `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you them, they are the repo's own Check step and Test entrypoint**, read off the repo's Recipe cache (`derive-testcmd.sh <repo> check` prints the first, `derive-testcmd.sh <repo> test` the second). Read them 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 all three 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. Seen twice in one run, and caught only by a finisher's reading. `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` on a commit you push, or on the push itself.** 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 on what reaches the branch — 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.
23
- **Under the fleet, run the two through `recipe-check.mjs`, not one by one:** from the worktree, after `git add` and before the commit, `~/.fleet/bin/fleet-run recipe-check.mjs --member <your name> --testCmd "<testCmd>" --reports <scratch>/reports` — `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as, and `<testCmd>` the whole command you were handed, one quoted argument. It runs the Recipe's Check step, which is `checkCmd`, then `<testCmd>` exactly as handed, against the staged tree, and records both results beside your report. The record is keyed to the tree, so run it again after any content change or rebase — a message-only amend keeps it valid — and the controller refuses an `applied` report whose head's tree has no green record. After the commit, and before you push or report, compare `git rev-parse 'HEAD^{tree}'` with the `tree` field of your record, `<scratch>/reports/<your name>.check.json`. A commit hook that rewrote and re-staged files after the record was written makes the two differ. When they do, list the paths it changed, `git diff --name-only "$(jq -r .tree <scratch>/reports/<your name>.check.json)" HEAD`. If the PR changes every listed path anyway, run `recipe-check.mjs` again with the same arguments: right after the commit the index holds the committed tree, so the re-run runs both commands on that tree and records it, leaving the head's sha as it is. A listed path the PR does not otherwise change is a stale base the hook staged rather than left unstaged, and a re-run would record it green: `git fetch origin && git rebase origin/main`, take the commit back with `git reset --soft HEAD^`, put each such path alone back with `git restore --source=HEAD --staged --worktree -- <that path>`, run `recipe-check.mjs`, then `git commit -C ORIG_HEAD` and compare again. A hook that stages such a path again on the rebased base → push nothing and report that cause. Equal trees need no re-run. A non-zero exit is red, save two that are no test result: exit 75 — no slot was free and nothing ran — so run it again, and exit 143, 130 or 129 — a SIGTERM, SIGINT or SIGHUP stopped it and nothing was recorded — so run it again with `timeout: 0` on the call. **Standalone, with no report to settle against,** run `checkCmd` and `testCmd` yourself, each copied verbatim.
23
+ **Under the fleet, run the two through `recipe-check.mjs`, not one by one:** from the worktree, after `git add` and before the commit, `~/.fleet/bin/fleet-run recipe-check.mjs --member <your name> --testCmd "<testCmd>" --reports <scratch>/reports` — `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as, and `<testCmd>` the whole command you were handed, one quoted argument. It runs the Recipe's Check step, which is `checkCmd`, then `<testCmd>` exactly as handed, against the staged tree, and records both results beside your report. The record is keyed to the tree, so run it again after any content change or rebase — a message-only amend keeps it valid — and the controller refuses an `applied` report whose head's tree has no green record. After the commit, and before you push or report, compare `git rev-parse 'HEAD^{tree}'` with the `tree` field of your record, `<scratch>/reports/<your name>.check.json`. A commit hook that rewrote and re-staged files after the record was written makes the two differ. When they do, list the paths it changed, `git diff --name-only "$(jq -r .tree <scratch>/reports/<your name>.check.json)" HEAD`. If the PR changes every listed path anyway, run `recipe-check.mjs` again with the same arguments: right after the commit the index holds the committed tree, so the re-run runs both commands on that tree and records it, leaving the head's sha as it is. A listed path the PR does not otherwise change is a stale base the hook staged rather than left unstaged, and a re-run would record it green: `git fetch origin && git rebase origin/main`, take the commit back with `git reset --soft HEAD^`, put each such path alone back with `git restore --source=HEAD --staged --worktree -- <that path>`, run `recipe-check.mjs`, then `git commit -C ORIG_HEAD` and compare again. A hook that stages such a path again on the rebased base → push nothing and report that cause. Equal trees need no re-run. Exit 1 is red; exit 2 and 4 are refusals that record nothing: your brief says how each ends; exit 75 (no slot free) and exit 143, 130 or 129 (a SIGTERM, SIGINT or SIGHUP, nothing recorded) are no test result: run it again, with `timeout: 0` on the call for a signal. **Standalone, with no report to settle against,** run `checkCmd` and `testCmd` yourself, each copied verbatim.
24
24
  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. 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.
25
25
  5. File each deferred finding: `gh issue create --label "<needs-triage string>"` 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 string>`, and CLOSED** — left open they read as queued agent work. 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. 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, 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*. `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 wake 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.
26
26
  **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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.127.9",
3
+ "version": "3.128.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -50,7 +50,7 @@
50
50
  // opens with no sha, is a NEED and N is left untouched, claim and all.
51
51
  // The PR a `covered` detail names is never written to.
52
52
  // A `PR#M` outcome also sets the claim branch's upstream when it has none: `reap.sh` keeps a branch with no upstream, and only an upstream's `[gone]` state makes it reapable. It writes `branch.<b>.remote` and `branch.<b>.merge` only while the merge key is unset, and prints `NEED upstream <b> — <why>` when a write fails.
53
- // A `blocked` outcome takes no action beyond the settle: no label, comment, release or upstream, so the ticket keeps `in-progress`.
53
+ // A `blocked` outcome takes no action on the ticket beyond the settle: no label, comment, release or upstream, so the ticket keeps `in-progress`. It runs the Recipe read, below.
54
54
  // fix-report <fix-pr-M[-x]>
55
55
  // `settle --from-report`, which records the filings and rulings the
56
56
  // report carries. Settled `applied:`/`no-op`, on a PR whose rows carry
@@ -61,6 +61,8 @@
61
61
  // token on the PR's rows yet: `dispositions-check.mjs --member <member>
62
62
  // --scratch <scratch>`, its stdout printed. That script writes its own
63
63
  // verdict token; its exit 1 is a verdict, its exit 2 a NEED.
64
+ // A `failed` outcome takes no dispositions check and runs the Recipe read, below.
65
+ // The Recipe read, after an `impl-report` settled `blocked` or a `fix-report` settled `failed`, whatever the member's cause: `derive-testcmd.sh . install`, `. check` and `. test --at origin/main` from the main checkout, the three reads phase0.mjs's `recipe` step makes (recipe-read.mjs is the one reader of both). All three exit 0: nothing printed, the cache is valid. One refused (exit 1): the refused reads, then `NEED derive-recipe`, which is phase 0's mid-run trigger; a refusal naming `--at` is no cache fault, and the controller fetches and reads again. Exit 3 or any other failure of a read: a `NEED recipe-read …` line carrying the environment fault, since the cache's state is unknown and deriving would not help. A cause local to the member's worktree reads valid from the main checkout and prints nothing. No other outcome runs the reads.
64
66
  // finisher-report <finisher-pr-M[-x]>
65
67
  // `settle --from-report`. Settled `halted:<cause>`: `gh pr comment <M>`
66
68
  // with the report's cause and evidence. A repair finisher (a retry
@@ -204,6 +206,7 @@ import { BRIEFS, REVIEW, REVIEWED, REVIEWER, dispositionsToken, memberTokens, ne
204
206
  import { NO_TRANSCRIPT_AFTER_DEFAULT, PARKS, controllerState, foldLedger, parkedToken } from "./fleet-tick.mjs";
205
207
  import { phase0Gate, readRunReceipt, tickCaps } from "./phase0-receipt.mjs";
206
208
  import { defaultScratch, readReportIn, reportsDir } from "./report-files.mjs";
209
+ import { readRecipe } from "./recipe-read.mjs";
207
210
  import { readState, statePath } from "./fleet-state.mjs";
208
211
 
209
212
  const NAME = "fleet-event";
@@ -568,16 +571,37 @@ function claimUpstream(ev, member) {
568
571
  ev.note(`upstream ${b} set`);
569
572
  }
570
573
 
574
+ // The Recipe read of the two settle wakes that end a member on a refusal it
575
+ // may have met: the one phase 0 makes (recipe-read.mjs), from the main
576
+ // checkout. A cause local to the member's own worktree reads valid from here
577
+ // and prints nothing. A refused read is `NEED derive-recipe`, which is phase
578
+ // 0's mid-run trigger; a read that could not run, or outlived
579
+ // CHILD_TIMEOUT_MS, is a NEED carrying the environment fault, since the
580
+ // cache's state is unknown and deriving would not help.
581
+ function recipeWake(ev, member) {
582
+ const { state, output } = readRecipe(process.cwd(), { timeoutMs: CHILD_TIMEOUT_MS });
583
+ if (state === "refused") {
584
+ ev.print(output);
585
+ ev.need("derive-recipe");
586
+ ev.note(`Recipe read after ${member}: refused`);
587
+ } else if (state === "broken") {
588
+ ev.need(`recipe-read after ${member} — ${output.split("\n").filter((l) => l.trim() !== "").join(" — ")}`);
589
+ ev.note(`Recipe read after ${member}: could not run`);
590
+ }
591
+ }
592
+
571
593
  function implReport(ev, member) {
572
594
  const outcome = ev.settle(member);
573
595
  if (outcome === "bailed") bailed(ev, member);
574
596
  else if (outcome?.startsWith("PR#")) claimUpstream(ev, member);
597
+ else if (outcome === "blocked") recipeWake(ev, member);
575
598
  }
576
599
 
577
600
  function fixReport(ev, member) {
578
601
  const outcome = ev.settle(member);
579
602
  if (outcome === null) return;
580
603
  const pr = parseMember(member).number;
604
+ if (outcome === "failed") recipeWake(ev, member);
581
605
  if (outcome !== "no-op" && !outcome.startsWith("applied:")) {
582
606
  ev.note("no dispositions check: it answered nothing");
583
607
  return;
@@ -67,8 +67,10 @@
67
67
  // for the other keys under the scratch parent, which runs
68
68
  // whatever the first answered. What either receipt's failed[]
69
69
  // names is listed. Recorded; never fails the run.
70
- // recipe `derive-testcmd.sh . install` and `. test --at origin/main`.
71
- // Either exiting 1 is a cache with nothing valid in it: pending,
70
+ // recipe `derive-testcmd.sh . install`, `. check` and `. test --at
71
+ // origin/main` (recipe-read.mjs, which the settle wakes of
72
+ // fleet-event.mjs read the cache through as well). Any
73
+ // exiting 1 is a cache with nothing valid in it: pending,
72
74
  // `NEED derive-recipe`. Exit 3 (a tool the reader could not run)
73
75
  // fails the step — deriving would not help.
74
76
  // fold-in every Owned PR (owned-pr.mjs: open, not a draft, authored by
@@ -170,6 +172,7 @@ import { GH_LOGIN_ARGS, isOwnedPr, loginOf, ownershipReadable } from "./owned-pr
170
172
  import { OBJECTIVES, RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
171
173
  import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
172
174
  import { IN_FLIGHT_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
175
+ import { readRecipe } from "./recipe-read.mjs";
173
176
 
174
177
  const NAME = "phase0";
175
178
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
@@ -365,16 +368,10 @@ function unreclaimed(what, r) {
365
368
  }
366
369
 
367
370
  function recipe({ cwd }) {
368
- const reads = [["install"], ["test", "--at", "origin/main"]].map((a) => ({ a, r: sh("derive-testcmd.sh", [".", ...a], { cwd }) }));
369
- const broken = reads.filter(({ r }) => r.status === 3 || (r.status !== 0 && r.status !== 1));
370
- if (broken.length > 0) {
371
- return failed(broken.map(({ a, r }) => withText(`derive-testcmd.sh . ${a.join(" ")} ${r.how} — the cache's state is unknown, and deriving would not help`, r)).join("\n"));
372
- }
373
- const refused = reads.filter(({ r }) => r.status === 1);
374
- if (refused.length > 0) {
375
- return { status: "pending", output: [...refused.map(({ a, r }) => withText(`derive-testcmd.sh . ${a.join(" ")} refused:`, r)), "NEED derive-recipe"].join("\n") };
376
- }
377
- return ok(`Recipe cache valid: ${reads.map(({ r }) => lines(r.stdout).at(-1) ?? "").join(" ; ")}`);
371
+ const { state, output } = readRecipe(cwd);
372
+ if (state === "broken") return failed(output);
373
+ if (state === "refused") return { status: "pending", output: `${output}\nNEED derive-recipe` };
374
+ return ok(output);
378
375
  }
379
376
 
380
377
  // The ledger's rows, read through `ledger.mjs read` so the ledger keeps one
@@ -22,7 +22,7 @@
22
22
  // Steps, in this order:
23
23
  //
24
24
  // 1 read the Check step and the Test entrypoint off the Recipe cache. A
25
- // worktree with no usable Recipe has no Check step to run: exit 2,
25
+ // worktree with no usable Recipe has no Check step to run: exit 4,
26
26
  // nothing run, nothing written. Settle reads the same cache from the
27
27
  // ledger's repository, where derive-testcmd.sh's probes of the Test
28
28
  // entrypoint can answer otherwise, so it skips its gate only where its
@@ -31,7 +31,8 @@
31
31
  // the working tree, so it must hold exactly that tree: an unstaged change
32
32
  // to a tracked file, or an untracked file no ignore rule covers, is a
33
33
  // refusal, exit 2 — a green record would otherwise name a tree that never
34
- // ran. Then the reports directory is created, before anything runs.
34
+ // ran. Then the reports directory is created, before anything runs; one
35
+ // that cannot be created is a refusal, exit 4.
35
36
  // 3 the Check step, `sh -c` from the worktree root. A Check step of
36
37
  // `true` is recorded as green without being run.
37
38
  // 4 the Test entrypoint, the same way — only when the Check step passed
@@ -59,7 +60,8 @@
59
60
  //
60
61
  // A record is written whenever a command ran and failed, so a red run
61
62
  // replaces an older record rather than leaving it standing; it records the
62
- // failure, and settle refuses on it. A run that is killed is the exception: a
63
+ // failure, and settle refuses on it. One that cannot be written is exit 4,
64
+ // though the commands already ran. A run that is killed is the exception: a
63
65
  // SIGTERM, SIGINT or SIGHUP this script itself receives during step 3 or 4 is
64
66
  // forwarded to the running command, no further command starts, and nothing
65
67
  // is written, so an older record stays where it is — settle compares the
@@ -78,9 +80,14 @@
78
80
  //
79
81
  // Exit status: 0 both commands passed and the record is written; 1 a command
80
82
  // failed — the record says which, and the script's stderr names it; 2 a
81
- // refusal that ran nothing and wrote nothing (usage, no usable Recipe, git
82
- // could not be read, a working tree that is not the staged tree, a reports
83
- // directory that could not be created); 75 the Test entrypoint printed exit
83
+ // refusal the member can clear, which ran nothing and wrote nothing (usage,
84
+ // including no `--reports` with a scratch root that cannot be resolved; git
85
+ // could not be read; a working tree that is not the staged tree); 4 a refusal
86
+ // the member cannot clear: no usable Recipe, derive-testcmd.sh did not
87
+ // answer, or a reports directory that could not be created, each before
88
+ // anything ran, so nothing was run or written — or a record that could not be
89
+ // written once the commands had run, so the run recorded nothing; 75
90
+ // the Test entrypoint printed exit
84
91
  // 75 — the suite wrapper found no slot and launched nothing, which is no test
85
92
  // result — so no record is written, and the same command is to be run again;
86
93
  // 143, 130 or 129 the script itself received a SIGTERM, a SIGINT or a
@@ -97,7 +104,7 @@ import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
97
104
  import { constants as osConstants } from "node:os";
98
105
  import { dirname, join } from "node:path";
99
106
  import { fileURLToPath } from "node:url";
100
- import { makeDie, defineFlags } from "./arg.mjs";
107
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
101
108
  import { FleetDirUnresolvable } from "./fleet-dir.mjs";
102
109
  import { gitEnv } from "./git-env.mjs";
103
110
  import { isCLI } from "./is-cli.mjs";
@@ -108,6 +115,8 @@ const NAME = "recipe-check";
108
115
  const USAGE = "usage: recipe-check.mjs --member <name> --testCmd <command> [--reports <dir>]";
109
116
  const DERIVE = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
110
117
  const GIT_TIMEOUT_MS = 30_000;
118
+ // The exit of a refusal the member cannot clear.
119
+ const UNCLEARABLE = 4;
111
120
  // What the suite wrapper exits with when it found no slot and launched nothing.
112
121
  const NO_SLOT = 75;
113
122
  // The signals this script forwards to the running command, and treats as a kill.
@@ -159,12 +168,24 @@ async function cli() {
159
168
  }
160
169
  }
161
170
 
171
+ // A refusal the member cannot clear — no usable Recipe, a Recipe reader that
172
+ // did not answer, a reports directory that cannot be created, a record that
173
+ // cannot be written — exits 4, where `die` exits 2 for the ones it can. Same
174
+ // message shape, same write.
175
+ const cannotClear = (msg) => {
176
+ try {
177
+ writeAll(2, `\n${NAME}: ${msg}\n`);
178
+ } catch {
179
+ // The message may be lost; the exit code may not.
180
+ }
181
+ process.exit(UNCLEARABLE);
182
+ };
162
183
  const env = gitEnv();
163
184
  // A reader that did not answer: the refusal names it, its exit status and
164
185
  // its own reason.
165
- const noAnswer = (what, r) => {
186
+ const noAnswer = (what, r, refuse = die) => {
166
187
  const why = (r.error?.message ?? r.stderr ?? "").trim();
167
- die(`${what} did not answer${r.status === null ? "" : ` (exit ${r.status})`}${why ? `: ${why}` : ""}; nothing run, nothing written`);
188
+ refuse(`${what} did not answer${r.status === null ? "" : ` (exit ${r.status})`}${why ? `: ${why}` : ""}; nothing run, nothing written`);
168
189
  };
169
190
  const gitOut = (what, args) => {
170
191
  const r = spawnSync("git", args, { encoding: "utf8", env, timeout: GIT_TIMEOUT_MS });
@@ -179,9 +200,9 @@ async function cli() {
179
200
  const r = spawnSync("sh", [DERIVE, top, name], { encoding: "utf8", env, timeout: GIT_TIMEOUT_MS });
180
201
  if (r.status === 0) return r.stdout.replace(/\n$/, "");
181
202
  if (r.status === 1) {
182
- die(`this worktree has no usable Recipe, so there is no Check step to run; settle reads the Recipe from the ledger's repository and gates the report wherever that read finds one; nothing run, nothing written — ${(r.stderr ?? "").trim()}`);
203
+ cannotClear(`this worktree has no usable Recipe, so there is no Check step to run; settle reads the Recipe from the ledger's repository and gates the report wherever that read finds one; nothing run, nothing written — ${(r.stderr ?? "").trim()}`);
183
204
  }
184
- noAnswer(`derive-testcmd.sh ${name}`, r);
205
+ noAnswer(`derive-testcmd.sh ${name}`, r, cannotClear);
185
206
  };
186
207
  const checkCmd = field("check");
187
208
  field("test");
@@ -199,7 +220,7 @@ async function cli() {
199
220
  try {
200
221
  mkdirSync(reports, { recursive: true });
201
222
  } catch (e) {
202
- die(`could not create ${reports}: ${e.code ?? e.message}; nothing run, nothing written`);
223
+ cannotClear(`could not create ${reports}: ${e.code ?? e.message}; nothing run, nothing written`);
203
224
  }
204
225
 
205
226
  // 3 and 4: the commands. A reader that closes this script's stdout or
@@ -264,7 +285,7 @@ async function cli() {
264
285
  renameSync(tmp, path);
265
286
  } catch (e) {
266
287
  rmSync(tmp, { force: true });
267
- die(`could not write ${path}: ${e.code ?? e.message}`);
288
+ cannotClear(`could not write ${path}: ${e.code ?? e.message}`);
268
289
  }
269
290
  run.decided = true;
270
291
 
@@ -0,0 +1,70 @@
1
+ // The controller's read of the Recipe cache, shared by phase0.mjs's `recipe`
2
+ // step and the settle wakes of fleet-event.mjs, so the two never read it
3
+ // differently.
4
+ //
5
+ // readRecipe(cwd, { timeoutMs }) -> { state, output }
6
+ //
7
+ // `derive-testcmd.sh . install`, `. check` and `. test --at origin/main`, each
8
+ // run from `cwd`, the main checkout — the one place the cache is read from —
9
+ // and all three always run, so every refused read is named. `timeoutMs`, when
10
+ // given, bounds each read; one that outlives it is killed and reads `broken`.
11
+ // `state` is:
12
+ //
13
+ // valid all three exited 0; `output` is `Recipe cache valid:` and each
14
+ // read's last line.
15
+ // refused one or more exited 1, a cache with nothing valid in it, or a
16
+ // command it names that does not resolve; `output` is one
17
+ // `derive-testcmd.sh . <args> refused:` line per read followed by
18
+ // the reader's own words. A refusal naming `--at` is no cache fault:
19
+ // the caller fetches and reads again.
20
+ // broken one or more exited 3 or failed any other way — a tool the reader
21
+ // could not run, a reader that was killed; the cache's state is
22
+ // unknown, and deriving would not help. `output` names each such
23
+ // read, its exit and the reader's own words. It outranks `refused`.
24
+ //
25
+ // Zero deps: node builtins and sibling scripts only.
26
+
27
+ import { spawnSync } from "node:child_process";
28
+ import { dirname, join } from "node:path";
29
+ import { fileURLToPath } from "node:url";
30
+ import { gitEnv } from "./git-env.mjs";
31
+
32
+ const DERIVE = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
33
+ const MAX_BUFFER = 64 * 1024 * 1024;
34
+
35
+ /** The reads, as arguments after the repository `.`. */
36
+ const RECIPE_READS = [["install"], ["check"], ["test", "--at", "origin/main"]];
37
+
38
+ const trimmed = (s) => String(s ?? "").trim();
39
+ const lines = (s) => trimmed(s).split("\n").filter((l) => l.trim() !== "");
40
+
41
+ function how(r) {
42
+ if (r.error) return r.error.code ?? r.error.message;
43
+ if (r.signal) return `killed by ${r.signal}`;
44
+ return `exit ${r.status}`;
45
+ }
46
+
47
+ // `head`, then the reader's stdout and stderr when it said anything.
48
+ function withText(head, stdout, stderr) {
49
+ const text = [trimmed(stdout), trimmed(stderr)].filter(Boolean).join("\n");
50
+ return text ? `${head}\n${text}` : head;
51
+ }
52
+
53
+ export function readRecipe(cwd, { timeoutMs } = {}) {
54
+ const reads = RECIPE_READS.map((a) => {
55
+ const r = spawnSync("sh", [DERIVE, ".", ...a], { cwd, encoding: "utf8", maxBuffer: MAX_BUFFER, env: gitEnv(), timeout: timeoutMs });
56
+ return { a, r, status: r.error ? null : r.status };
57
+ });
58
+ const broken = reads.filter(({ status }) => status !== 0 && status !== 1);
59
+ if (broken.length > 0) {
60
+ return {
61
+ state: "broken",
62
+ output: broken.map(({ a, r }) => withText(`derive-testcmd.sh . ${a.join(" ")} ${how(r)} — the cache's state is unknown, and deriving would not help`, r.stdout, r.stderr)).join("\n"),
63
+ };
64
+ }
65
+ const refused = reads.filter(({ status }) => status === 1);
66
+ if (refused.length > 0) {
67
+ return { state: "refused", output: refused.map(({ a, r }) => withText(`derive-testcmd.sh . ${a.join(" ")} refused:`, r.stdout, r.stderr)).join("\n") };
68
+ }
69
+ return { state: "valid", output: `Recipe cache valid: ${reads.map(({ r }) => lines(r.stdout).at(-1) ?? "").join(" ; ")}` };
70
+ }
@@ -806,9 +806,9 @@ Match the failure to its row in the table below and run that response; where the
806
806
  |---|---|
807
807
  | SHA not on expected branch | Flag, do not enqueue, report |
808
808
  | Implementer bails before implementing | Act by the report's `bailCause` as the **Relabel causes** table says, then refill (**What a wake owes beyond its call**) |
809
- | Implementer blocked or ambiguous *mid-implementation* | Free the slot. A `blocked` report settles on the **Implementer report** wake, no label moved; with no report, `ledger.mjs settle impl-<N> blocked`, its Ending still `hollow`. Leave `in-progress`, report — the ticket is not In flight and waits for a human; the row above is the pre-code bail |
809
+ | Implementer blocked or ambiguous *mid-implementation* | Free the slot. A `blocked` report settles on the **Implementer report** wake, no label moved; with no report, `ledger.mjs settle impl-<N> blocked`, its Ending still `hollow`. Leave `in-progress`, report — the ticket is not In flight and waits for a human; its `NEED derive-recipe` is phase 0's mid-run trigger |
810
810
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
811
- | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — a fix-applier or red-check fixer settles `failed` |
811
+ | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — the last two settle `failed`; a wake's `NEED derive-recipe` is phase 0's mid-run trigger |
812
812
  | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
813
813
  | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
814
814
  | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
@@ -148,6 +148,22 @@ result — no slot was free and nothing ran — so run it again. Exit 143, 130 o
148
148
  129 is no test result either — it received a SIGTERM, SIGINT or SIGHUP and
149
149
  recorded nothing — so run it again with `timeout: 0` on the call.
150
150
 
151
+ A refusal that recorded nothing is no red. Exit 2 is one you can clear — a
152
+ working tree that is not the staged tree, git that did not answer, a usage
153
+ error: do what its message says, then run `recipe-check.mjs` again, and if it
154
+ refuses again push nothing and end as for exit 4. Exit 4 is one you cannot
155
+ clear — no usable Recipe, a Recipe reader that did not answer, a reports
156
+ directory it cannot create or write to: never derive the Recipe, and never
157
+ rebase, re-run or edit to get around it, save one case. When the refusal names
158
+ a path your own staged change deletes, renames or changes the mode of
159
+ (`git diff --cached --summary`), undo that change unless the PR requires it,
160
+ and run `recipe-check.mjs` once more. Otherwise — the change is required, or
161
+ the re-run refuses again — push nothing and write a `failed` report, a report
162
+ and not the no-report ending: `head` the PR's head on origin, which you pushed
163
+ nothing past, `applied` and `deferred` empty, `dispositionsRecord` and
164
+ `testRun` null, the refusal verbatim in `confirmation`, and `filed` and
165
+ `unrecorded` as for any outcome.
166
+
151
167
  Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
152
168
  `fix-pr-` name you were dispatched as, in the shape
153
169
  `~/.fleet/bin/fleet-run report-schema.mjs print fix-pr` prints. A field with
@@ -48,6 +48,22 @@ head's tree has no green record, and exit 75 from it is no test result — run i
48
48
  again. So is exit 143, 130 or 129: it received a SIGTERM, SIGINT or SIGHUP and
49
49
  recorded nothing — run it again with `timeout: 0` on the call.
50
50
 
51
+ Exit 2 is a refusal you can clear: it ran nothing and wrote nothing, and its
52
+ message names the cause — a working tree that is not the staged tree, git that
53
+ did not answer, a usage error. Do what it says, then run `recipe-check.mjs`
54
+ again; refused again → push nothing and end as for exit 4. Exit 4 is a refusal
55
+ you cannot clear: no usable Recipe, a Recipe reader that did not answer, or a
56
+ reports directory it cannot create or write to. Never derive the Recipe, and
57
+ never rebase, re-run or edit to get around it. One exception: when the refusal
58
+ names a path your own staged change deletes, renames or changes the mode of
59
+ (`git diff --cached --summary`), undo that change unless the ticket requires
60
+ it, and run `recipe-check.mjs` once more. Otherwise — the change is required,
61
+ or the re-run refuses again — push nothing and end as `blocked`: write the
62
+ report with `outcome` `blocked`, `pr`, `head` and `bailCause` null,
63
+ `bailDetail` `recipe-check.mjs`'s stderr verbatim, and leave the worktree as
64
+ it stands. The ticket stays claimed, its label untouched, and waits for the
65
+ maintainer.
66
+
51
67
  Your report is a file, `<scratch>/reports/<your name>.json`, `<your name>` the
52
68
  `impl-<N>[-x]` you were dispatched as, in the shape
53
69
  `~/.fleet/bin/fleet-run report-schema.mjs print impl` prints. Write it before
@@ -418,12 +418,13 @@ step and bakes its Test entrypoint into the member's runner, and every
418
418
  review reads the Test entrypoint, all out of the **Recipe cache**
419
419
  (`.fleet/recipe.json` beside the common git dir); no script infers either
420
420
  command. Check it first: `~/.fleet/bin/fleet-run derive-testcmd.sh .
421
- install` and `~/.fleet/bin/fleet-run derive-testcmd.sh . test --at
422
- origin/main`. **Both exit
421
+ install`, `~/.fleet/bin/fleet-run derive-testcmd.sh . check` and
422
+ `~/.fleet/bin/fleet-run derive-testcmd.sh . test --at
423
+ origin/main`. **All three exit
423
424
  0 → the cache is present and valid: use it as it stands and derive
424
- nothing.** Either exits 1 (a refusal about the cache) → derive it; a refusal
425
+ nothing.** Any exits 1 (a refusal about the cache) → derive it; a refusal
425
426
  naming `--at` says `origin/main` does not resolve, which is no cache fault —
426
- fetch it and check again, since deriving would not help. Either
427
+ fetch it and check again, since deriving would not help. Any
427
428
  exits 3 → the reader could not run a tool it needs, so the cache's state is
428
429
  unknown: fix that environment fault and check again; deriving would not
429
430
  help. This step is yours: one derivation
@@ -444,9 +445,9 @@ a deliberate mutation of a tracked file, and the Test entrypoint must be shown t
444
445
  runner's own non-zero count, or a deliberate mutation of one test that
445
446
  turns the run red. Only a proof writes the cache, with `derivedAt` (the
446
447
  `origin/main` commit it ran against) and the proof itself. **`RECIPE
447
- PROVEN`** → re-run both reads above (`derive-testcmd.sh . install` and
448
- `derive-testcmd.sh . test --at origin/main`) and the Check step's read
449
- below; their output is the Recipe this run uses. **`RECIPE NOT PROVEN`** →
448
+ PROVEN`** → re-run the three reads above (`derive-testcmd.sh . install`,
449
+ `derive-testcmd.sh . check` and `derive-testcmd.sh . test --at origin/main`);
450
+ their output is the Recipe this run uses. **`RECIPE NOT PROVEN`** →
450
451
  stall, below.
451
452
 
452
453
  **Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.fleet/bin/fleet-run derive-testcmd.sh . check` prints it. Pass it to the fix-applier beside `testCmd`; the review does not run it. Neither member runs the two by hand: `recipe-check.mjs` runs the Check step it reads off that cache, then the `testCmd` it is handed, on the member's staged tree, and writes the record `ledger.mjs settle --from-report` requires of an implementer's and a fix-applier's report.
@@ -454,8 +455,16 @@ stall, below.
454
455
  **Mid-run, a cache that stops running is re-derived once, then the run
455
456
  stalls.** A claim or a review that refuses because the Recipe cache is
456
457
  invalid — a command that no longer runs, or an Install step that changed
457
- the tree — is the one mid-run trigger: dispatch `derive-recipe` again
458
- exactly as above, then retry what refused. The Install step's refusals
458
+ the tree — is a mid-run trigger: dispatch `derive-recipe` again
459
+ exactly as above, then retry what refused. So is the `NEED derive-recipe`
460
+ a settle wake prints, `fleet-event.mjs impl-report` for an implementer
461
+ settled `blocked` and `fix-report` for a fix-applier settled `failed`: it is
462
+ counted in the same once per run, a line printed while that derivation runs
463
+ is covered by it, and one printed after its `RECIPE PROVEN` is the second
464
+ refusal that stalls the run. What to retry for a wake's line: a fix-applier's
465
+ PR is fix-due again and the tick re-dispatches it; a blocked implementer's
466
+ ticket is reported to the maintainer and waits for their `replace #<N>`.
467
+ The count is yours to keep; the ledger holds no record of it. The Install step's refusals
459
468
  fire after the claim has labelled the ticket and created its worktree, so
460
469
  release that claim with `release-ticket.sh` first (SKILL.md's Failure handling
461
470
  row for a claim abandoned mid-run). A red suite never triggers it: a failing test is