@feigi/fleet-ctl 3.153.0 → 3.153.2

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.
@@ -90,7 +90,7 @@ It cannot ask the user anything and cannot wait on CI — rebasing, watching che
90
90
  - **Say read-only.** No `fleet-review-*` definition's frontmatter restricts tool access — a `.agent.md` prompt saying "report only" is instruction, not enforcement — so an agent hand-dispatched here, named or general-purpose, has write tools it must not use: one committed and pushed during a report-only dispatch. No commits, no pushes, no worktree edits.
91
91
  - **Cut TWO trees, not one — a shared snapshot is not enough.** Mutation probing is a *write*, so a mutating specialist and read-only specialists cannot share a copy: the readers then observe the mutant exactly as if it were real code. Give them `snap-ro`, pristine and **never written**, and one private copy **per mutating specialist**. Keep every one out of the worktree. What one shared snapshot did is in run-team's `references/reviewers.md` (**What a shared snapshot did to its readers**). Reverting a probe does not help — it leaves a window where every concurrent reader sees a lie, and serializing does not close it because readers are concurrent with the *mutator*.
92
92
  - **Do not trust the obvious contamination check.** `diff -rq` and `md5` against the mutating tree both returned *clean* — because the probe had been reverted between the two reads. A clean diff against a live tree is not evidence in either direction; only `snap-ro` and the object store settle it.
93
- - **`git archive` carries tracked files only.** No installed dependencies, no gitignored runner or config. Provision in the same step — run the Install step in the copy (read it off the worktree or main checkout, `derive-testcmd.sh <worktree or main checkout> install`; pointed at the copy it refuses, since a copy holds no Recipe cache), from the copy's root, before anyone measures in it — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement. Never `cp -R` an installed tree, and never symlink or clone its ignored paths into a copy: an install can record absolute paths back into the tree it ran in, so the copy runs that tree's source and a mutation made in the copy never runs.
93
+ - **`git archive` carries tracked files only.** No installed dependencies, no gitignored runner or config. Provision in the same step — run the Install step in the copy (read it off the worktree or main checkout, `derive-testcmd.sh <worktree or main checkout> install --at origin/main`; pointed at the copy it refuses, since a copy holds no Recipe cache), from the copy's root, before anyone measures in it — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement. Never `cp -R` an installed tree, and never symlink or clone its ignored paths into a copy: an install can record absolute paths back into the tree it ran in, so the copy runs that tree's source and a mutation made in the copy never runs.
94
94
  - **Initialize the copy before anyone measures in it — a bare `git archive` tree cannot validly run every suite.** It is not a git repository, so anything that asks git about the checkout breaks: `derive_workspace_id` shells out to `git rev-parse`, falls back to the directory basename and the hook tests fail on the *name* — naming the dir after the repo makes those pass **by coincidence, not correctness** — while every sweep that asks git what ships declines instead of running, which is the silent half. `git init && git add -A -f && git commit` in the extracted copy is what makes a count mean what it looks like; the review's snapshot agent does exactly that, verifies it by comparing the new commit's tree hash against the reviewed commit's, and then runs the Install step in it, and a hand-cut tree needs the same before you read a count off it. **Every agent you send to work in its own copy of the snapshot makes that copy the same way:** copy the tracked files only (`git -C <snapshot> archive HEAD | tar -x -C <copy>`, or a `git clone` of the snapshot repository), `git init`, `git add -A -f` and commit, then run the Install step in the copy before measuring anything in it — never `cp -R` the snapshot. Suites that need the real worktree for some *other* reason — the stack below — still do.
95
95
  - **Give specialists a stack-free test command, not the worktree's runner, and their own scratch dir** — `<scratch>/pr<N>/fleet-review-<key>/`, resolved to an absolute path that you write into that specialist's prompt; a specialist never derives its own. Specialists inherit no environment, and one falling back to the default config runs a `globalSetup` that brings the shared compose stack up and tears it down, recreating the DB mid-run for every sibling. **The snapshot does not cover this** — the compose project name comes from the environment, not the working directory, so three agents on three copies still collide. But `./agent-test` does not fix it either: it exports **one** `TEST_COMPOSE_PROJECT`/port triple per *worktree* (`ab-<issue>`), so N concurrent specialists sharing it tear down each other's postgres mid-run. So tell specialists the repo's test command directly — the Test entrypoint, read off the Recipe cache the way step 3 reads it (`derive-testcmd.sh <worktree or main checkout> test` prints it; the snapshot carries no `.fleet/` cache, so pointing it at the snapshot refuses) — when it brings up no shared stack, and the repo's own stack-free config when it does; never name a config the repo does not have, which sends every specialist into a missing-file error that reads as a broken tree rather than a bad instruction. Keep `./agent-test` for your own verification. **Hand that command with its reading rule: `tests 0` is a failed run, not a pass.** A command is not self-checking: a path glob or filter that matches nothing can exit 0 having run nothing. Measured with `node --test` over a glob matching no file: bash passes the pattern through literally, node globs it itself and finds no files, and you get `ℹ tests 0` / exit 0 — and `# tests 0` to a pipe on older node, so a rule that greps only for `ℹ` finds nothing in a CI log and cannot tell a zero-test run from a full one. Do not count on the shell to catch it: zsh errors (`no matches found`, exit 1) and bash does not, so the guard has to be the reading rule. **And zero is not the only no-work count.** **0 passes with no failures** is everything skipped, and a count **materially below the full suite** is a partial copy of the tree — which is the *documented* behavior, since the prompt tells specialists to run their probe work inside their own copy of the snapshot and nothing anchors an expected count for them. `review-core.mjs` classifies the first itself, in `suiteVerdictOf`; the second it structurally cannot, because that function is kept pure and so never learns how many tests the tree has. Handing the rule over with the command is the only guard the partial-copy case has. Carry the rule, not the command: wherever a repo has a stack, N concurrent specialists sharing one runner collide, and the escape is whatever that repo's stack-free config is.
96
96
  - **Completion is not delivery — but you can reach a specialist, so never wait idle.** A specialist you dispatched reports when it settles; if a report is missing, `hub send` it by name and ask for the report. Judge delivery by whether a report came out. **Do not settle a dimension you hold no report for**: ask the specialist, then the controller by name; only when neither answers, rule and name that dimension **unrun** — a killed specialist never reports, so waiting on one is unbounded. Never ship "dispatched, never delivered" as settled; a ruling citing a report you do not hold gets verified from source, never applied on trust.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.153.0",
3
+ "version": "3.153.2",
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": {
@@ -14,8 +14,8 @@
14
14
  #
15
15
  # The ONE reader of the cache — reused, not reimplemented, by claim-ticket.sh
16
16
  # (the Install step it runs and the Test entrypoint it bakes into the runner)
17
- # and by review-core.mjs's snapshot agent (the Test entrypoint handed to the
18
- # specialists). Two independent readers is what drifts.
17
+ # and by review-core.mjs's snapshot agent (the Install step it runs in the
18
+ # snapshot). Two independent readers is what drifts.
19
19
  #
20
20
  # THE CACHE is `<workspace>/.fleet/recipe.json`, where <workspace> is the
21
21
  # directory git-env.mjs's resolveWorkspace() names for the repository: the
@@ -114,7 +114,7 @@ export LC_ALL=C
114
114
  # `$repo` — and the cache it then reads is another repository's Recipe,
115
115
  # reported as this one's. Both consumers act on that string: claim-ticket.sh
116
116
  # runs it in a fresh worktree and bakes it into the runner, and review-core.mjs's
117
- # snapshot agent hands it to every specialist.
117
+ # snapshot agent runs it in the snapshot.
118
118
  #
119
119
  # GIT_WORK_TREE is unset alongside it: the vacuous-suite probe's `check-ignore`
120
120
  # reads the ignore rules of whatever work tree git is pointed at, so an ambient
@@ -416,9 +416,9 @@ fi
416
416
  # `;`, `&`, or a newline lets a real shell read the caller's "$@" as an
417
417
  # unrelated top-level command instead of args reaching the Test entrypoint, and
418
418
  # one containing a `#`-led word swallows everything after it, "$@" included, as
419
- # a comment. review-core.mjs's snapshot agent appends no arguments but embeds
420
- # the string in `{ cd <dir> && <cmd>; }`, where the same endings and `#` word
421
- # break the wrapper as a syntax error — measured on both. A trailing
419
+ # a comment. review-core.mjs's shared test run hands the string to
420
+ # suite-slot.mjs single-quoted and appends no arguments, so neither hazard
421
+ # reaches it there. A trailing
422
422
  # newline is checked here too: the frame above lets a value keep one
423
423
  # where an unframed `$(…)` capture always dropped it silently, so a value
424
424
  # that used to read as `true;` now reads as `true;\n` and would otherwise
@@ -2108,14 +2108,26 @@ function checkReaders(where) {
2108
2108
  die(`${where}: could not look — gh pr view ${pr} --json ${fields} answered ${e.message}; nothing written`);
2109
2109
  }
2110
2110
  };
2111
- // The title of issue `n`, as `gh issue view <n> --json title` answers it.
2112
- const issueTitle = (n) => {
2113
- const what = `gh issue view ${n} --json title`;
2114
- const { r, v } = lookJson(what, ["issue", "view", String(n), "--json", "title"]);
2111
+ // `labels` as the list of the label names it holds, or null when it is
2112
+ // anything but a list of named labels.
2113
+ const namedLabels = (labels) => {
2114
+ if (!Array.isArray(labels) || !labels.every((l) => l !== null && typeof l === "object" && typeof l.name === "string")) return null;
2115
+ return labels.map((l) => l.name);
2116
+ };
2117
+ // Issue `n`'s title and label names, as `gh issue view <n> --json
2118
+ // title,labels` answers them. An answer without a string title, or without a
2119
+ // list of named labels, could not look.
2120
+ const issueRead = (n) => {
2121
+ const what = `gh issue view ${n} --json title,labels`;
2122
+ const { r, v } = lookJson(what, ["issue", "view", String(n), "--json", "title,labels"]);
2115
2123
  if (v === null || typeof v !== "object" || typeof v.title !== "string") {
2116
2124
  die(`${where}: could not look — ${what} printed no title: ${cause(r.stdout)}; nothing written`);
2117
2125
  }
2118
- return v.title;
2126
+ const labels = namedLabels(v.labels);
2127
+ if (labels === null) {
2128
+ die(`${where}: could not look — ${what} printed no list of named labels: ${cause(r.stdout)}; nothing written`);
2129
+ }
2130
+ return { title: v.title, labels };
2119
2131
  };
2120
2132
  // The label names gh answers `args` with, `list` taking the label list off
2121
2133
  // the parsed answer. A read that fails, or answers anything but a list of
@@ -2124,38 +2136,58 @@ function checkReaders(where) {
2124
2136
  const what = `gh ${args.join(" ")}`;
2125
2137
  const lead = `could not read ${whose} labels`;
2126
2138
  const { r, v } = lookJson(what, args, lead);
2127
- const labels = list(v);
2128
- if (!Array.isArray(labels) || !labels.every((l) => l !== null && typeof l === "object" && typeof l.name === "string")) {
2139
+ const labels = namedLabels(list(v));
2140
+ if (labels === null) {
2129
2141
  die(`${where}: ${lead} — ${what} printed no list of named labels: ${cause(r.stdout)}; nothing written`);
2130
2142
  }
2131
- return labels.map((l) => l.name);
2143
+ return labels;
2132
2144
  };
2133
2145
  // PR `pr`'s label names, and the names of the labels its repository defines.
2134
2146
  const prLabels = (pr) => labelNames(`PR #${pr}'s`, ["pr", "view", String(pr), "--json", "labels"], (v) => v?.labels);
2135
2147
  const repoLabels = () => labelNames("the repository's", LABEL_LIST_ARGS, (v) => v);
2136
- return { repoDir, look, verifyShaOf, prView, prViewClosing, issueTitle, prLabels, repoLabels };
2148
+ // Issue `n`'s label names, as `gh issue view <n> --json labels` answers them.
2149
+ const issueLabels = (n) => labelNames(`issue #${n}'s`, ["issue", "view", String(n), "--json", "labels"], (v) => v?.labels);
2150
+ // Of `numbers`, a PR's closing references in its own repository, those not
2151
+ // in `own` — the PR's own tickets — whose issue carries the in-progress Label
2152
+ // role's string: tickets another claim holds. `labelsOf(n)` is issue n's
2153
+ // label names. The map is read only when a reference is not the PR's own, so
2154
+ // a single-ticket PR needs none; one that cannot be read is exit 2.
2155
+ const claimedElsewhere = (numbers, own, labelsOf) => {
2156
+ const others = numbers.filter((n) => !own.includes(n));
2157
+ if (others.length === 0) return [];
2158
+ const inProgress = roleLabel(repoDir(), "in-progress", where);
2159
+ return others.filter((n) => labelsOf(n).includes(inProgress));
2160
+ };
2161
+ return { repoDir, look, verifyShaOf, prView, prViewClosing, issueRead, prLabels, repoLabels, issueLabels, claimedElsewhere };
2137
2162
  }
2138
2163
 
2139
2164
  // The finisher gate's closing-reference checks for the PR `member` finishes,
2140
2165
  // read off the PR's closingIssuesReferences in its own repository — a
2141
2166
  // reference into another repository closes no issue here, whatever its
2142
- // number — and the titles of the issues they name; its second argument is
2143
- // rulingOf()'s answer, which let the PR through. Check 1, when a settled
2144
- // implementer's token names the PR: each ticket it names is closed by the
2145
- // body when the PR's ruling is closed_own_ticket=yes, and is not when the
2146
- // ruling is no. Check 2, for every PR: no reference may be the
2147
- // suggestion-band record of this PR's review — an issue whose title, trimmed,
2148
- // is recordTitle(), as dispositions-check.mjs finds the record. Returns
2149
- // `{refs, failures}`: the issue numbers the PR closes, its own
2150
- // suggestion-band record aside — that one is a failure here, not a ticket —
2151
- // and one line per failure. A read the checks need dies, naming the read,
2152
- // and writes nothing.
2167
+ // number — its head branch, and the titles and labels of the issues they
2168
+ // name; its second argument is rulingOf()'s answer, which let the PR through.
2169
+ // Check 1, when a settled implementer's token names the PR: each ticket it
2170
+ // names is closed by the body when the PR's ruling is closed_own_ticket=yes,
2171
+ // and is not when the ruling is no. Check 2, for every PR: no reference may
2172
+ // be the suggestion-band record of this PR's review — an issue whose title,
2173
+ // trimmed, is recordTitle(), as dispositions-check.mjs finds the record.
2174
+ // Check 3, for every PR, Ticketless ones included: no reference besides the
2175
+ // PR's own tickets may be a ticket another claim holds, its issue carrying
2176
+ // the Label map's in-progress string (claimedElsewhere()). The PR's own
2177
+ // tickets are the ones its settled tokens name and, when its head is a claim
2178
+ // branch (stranded.mjs's CLAIM_BRANCH), that claim's ticket — a PR a run
2179
+ // inherited carries no token, and its own claim holds its ticket until it
2180
+ // merges. Returns `{refs, failures}`: the issue numbers the PR closes, its
2181
+ // own suggestion-band record aside — that one is a failure here, not a
2182
+ // ticket — and one line per failure. A read the checks need dies, naming the
2183
+ // read, and writes nothing.
2153
2184
  async function closingRefusals(member, { tickets, ruling, tsv }) {
2154
2185
  const pr = member.number;
2155
2186
  const where = `dispatch ${member.name}`;
2156
2187
  const { recordTitle } = await import("./dispositions-check.mjs");
2157
- const { prViewClosing, issueTitle } = checkReaders(where);
2158
- const refs = prViewClosing(pr, "closingIssuesReferences,url").numbers;
2188
+ const { CLAIM_BRANCH } = await import("./stranded.mjs");
2189
+ const { prViewClosing, issueRead, claimedElsewhere } = checkReaders(where);
2190
+ const { view, numbers: refs } = prViewClosing(pr, "closingIssuesReferences,url,headRefName");
2159
2191
  const failures = [];
2160
2192
  if (tickets.length > 0) {
2161
2193
  const verdict = ruling.closed_own_ticket;
@@ -2172,10 +2204,21 @@ async function closingRefusals(member, { tickets, ruling, tsv }) {
2172
2204
  }
2173
2205
  }
2174
2206
  const own = recordTitle(pr);
2175
- const closed = [];
2207
+ // The label names of each issue the PR closes, its own record aside.
2208
+ const labels = new Map();
2176
2209
  for (const n of refs) {
2177
- if (issueTitle(n).trim() === own) failures.push(`PR #${pr} closes #${n}, its own suggestion-band record — rephrase the mention as "Refs #${n}" or "issue #${n}"`);
2178
- else closed.push(n);
2210
+ const issue = issueRead(n);
2211
+ if (issue.title.trim() === own) {
2212
+ failures.push(`PR #${pr} closes #${n}, its own suggestion-band record — rephrase the mention as "Refs #${n}" or "issue #${n}"`);
2213
+ } else {
2214
+ labels.set(n, issue.labels);
2215
+ }
2216
+ }
2217
+ const closed = [...labels.keys()];
2218
+ const claim = CLAIM_BRANCH.exec(view.headRefName);
2219
+ const ownTickets = claim === null ? tickets : [...tickets, Number(claim[1])];
2220
+ for (const n of claimedElsewhere(closed, ownTickets, (m) => labels.get(m))) {
2221
+ failures.push(`PR #${pr} closes #${n}, which another claim holds — rephrase it as "Refs #${n}"`);
2179
2222
  }
2180
2223
  return { refs: closed, failures };
2181
2224
  }
@@ -2220,16 +2263,23 @@ function labelRefusal(member, tickets, refs) {
2220
2263
  }
2221
2264
 
2222
2265
  // The tracker's string for the `ready-to-merge` Label role, off the Label map
2223
- // of the repository `dir` belongs to (label-map.mjs). Only the paths that
2224
- // compare or list that label read it — `dispatch merge-bot`'s queueSnapshot(),
2225
- // `dispatch finisher-pr-M`'s labelRefusal() and settle --from-report's
2226
- // finisher and merge-bot checks — so every other verb runs with no map at all.
2227
- // A map that cannot be read, or no repository to find one in, is exit 2 under
2228
- // `where`, carrying the reader's message (an absent or invalid map's names
2229
- // `label-map.mjs ensure`); nothing written.
2266
+ // of the repository `dir` belongs to: roleLabel()'s answer for that role. Only
2267
+ // the paths that compare or list that label read it — `dispatch merge-bot`'s
2268
+ // queueSnapshot(), `dispatch finisher-pr-M`'s labelRefusal() and settle
2269
+ // --from-report's finisher and merge-bot checks — so every other verb runs
2270
+ // with no map at all.
2230
2271
  function readyLabel(dir, where) {
2272
+ return roleLabel(dir, "ready-to-merge", where);
2273
+ }
2274
+
2275
+ // The tracker's string for the Label role `role`, off the Label map of the
2276
+ // repository `dir` belongs to (label-map.mjs). A map that cannot be read, or no
2277
+ // repository to find one in, is exit 2 under `where`, carrying the reader's
2278
+ // message (an absent or invalid map's names `label-map.mjs ensure`); nothing
2279
+ // written.
2280
+ function roleLabel(dir, role, where) {
2231
2281
  try {
2232
- return readLabelMap({ cwd: dir })["ready-to-merge"];
2282
+ return readLabelMap({ cwd: dir })[role];
2233
2283
  } catch (e) {
2234
2284
  if (!(e instanceof LabelMapUnreadable) && !(e instanceof FleetDirUnresolvable)) throw e;
2235
2285
  die(`${where}: ${e.message}; nothing written`);
@@ -2707,8 +2757,10 @@ function recordFiled(id, subject) {
2707
2757
  //
2708
2758
  // impl-N=PR#M verify-sha.sh <branch> <head> exits 0; PR M
2709
2759
  // reads OPEN and its closingIssuesReferences in its
2710
- // own repository name N; its head branch is
2711
- // implementer/N-impl-N;
2760
+ // own repository name N; no other closing
2761
+ // reference there is a ticket another claim holds,
2762
+ // its issue carrying in-progress; its head branch
2763
+ // is implementer/N-impl-N;
2712
2764
  // the Check-step record (below) holds for <head>
2713
2765
  // impl-N=bailed bailCause is not null; the receipt names it.
2714
2766
  // report-schema.mjs already refuses a bail that
@@ -2739,7 +2791,9 @@ function recordFiled(id, subject) {
2739
2791
  // by readyLabel() only when one of the two checks runs: on a finisher's
2740
2792
  // `labelled`, and on a merge bot's report that leaves a PR queued at dispatch
2741
2793
  // without a verdict. Outside settle, `dispatch finisher-pr-M` reads it too,
2742
- // to refuse a finisher onto a labelled PR (labelRefusal()).
2794
+ // to refuse a finisher onto a labelled PR (labelRefusal()). `in-progress` in
2795
+ // the `impl-N=PR#M` row is the Label map's string for that role, read by
2796
+ // roleLabel() only when the PR closes a ticket besides N.
2743
2797
  //
2744
2798
  // THE CHECK-STEP RECORD, for `impl-N=PR#M` and `fix-pr-M=applied:<head>`:
2745
2799
  // recipe-check.mjs writes `<reports>/<member>.check.json` on the member's
@@ -2835,7 +2889,7 @@ async function runSettleFromReport() {
2835
2889
  if (report.member !== member) invalid(`$.member: ${JSON.stringify(report.member)} is not ${member}`);
2836
2890
 
2837
2891
  // The gh and git reads this check makes, shared with the finisher gate.
2838
- const { repoDir, look, verifyShaOf, prView, prViewClosing } = checkReaders(where);
2892
+ const { repoDir, look, verifyShaOf, prView, prViewClosing, issueLabels, claimedElsewhere } = checkReaders(where);
2839
2893
  // origin's head of `branch`, or null when origin has no such branch.
2840
2894
  const remoteHead = (branch) => {
2841
2895
  const ref = `refs/heads/${branch}`;
@@ -2893,6 +2947,15 @@ async function runSettleFromReport() {
2893
2947
  const { view: pr, numbers } = prViewClosing(report.pr, "state,closingIssuesReferences,url,headRefName");
2894
2948
  check(`PR #${report.pr} reads OPEN`, pr.state === "OPEN");
2895
2949
  check(`PR #${report.pr} closes #${live.number}`, numbers.includes(live.number));
2950
+ // The claim's own ticket is the token's: a replacement impl-N-x holds
2951
+ // the same claim as impl-N, so it is never refused for #N. A PR that is
2952
+ // not OPEN, or does not close #N, has failed already, so no other
2953
+ // reference's issue is read: a read that could not look would turn
2954
+ // that exit 3 into exit 2.
2955
+ if (pr.state === "OPEN" && numbers.includes(live.number)) {
2956
+ const held = claimedElsewhere(numbers, [live.number], issueLabels);
2957
+ check(`PR #${report.pr} closes no ticket another claim holds (in-progress: ${held.length === 0 ? "none" : held.map((n) => `#${n}`).join(", ")})`, held.length === 0);
2958
+ }
2896
2959
  // The claim's branch comes from the ticket: the Pull claims with member
2897
2960
  // impl-N, so its branch is implementer/N-impl-N, and close-out releases
2898
2961
  // impl-N. Never from the settling member's name or its report: a
@@ -1,7 +1,7 @@
1
1
  // review-core.mjs — the review body for PR review.
2
2
  //
3
3
  // This file holds every host-independent declaration PR review needs: the
4
- // JSON schemas, `usableDiff`, `usableMessages`, `messagesNote`, `refuterMessagesNote`, `readRules`, `resolveTestCmd`,
4
+ // JSON schemas, `usableDiff`, `usableMessages`, `messagesNote`, `refuterMessagesNote`, `readRules`,
5
5
  // `decodeArgs`, `selectDimensions`, `resolveDimensions`, `snapshotMissing`,
6
6
  // `installReason`/`installFinding`, `suiteVerdictOf`/`unrunCrashed`,
7
7
  // `sharedRunNote`, `copyRule`,
@@ -134,8 +134,6 @@ export const SNAPSHOT_SCHEMA = {
134
134
  messagesPath: { type: "string" },
135
135
  refHead: { type: "string" },
136
136
  prHead: { type: "string" },
137
- testCmd: { type: "string" },
138
- testCmdError: { type: "string" },
139
137
  // The Recipe's `uncovered` as derive-testcmd.sh printed it: the merge-gating
140
138
  // CI steps neither the Test entrypoint nor the Check step runs, one line of JSON, `[]` for none.
141
139
  // `uncoveredError` carries the reader's refusal instead when it could not
@@ -410,23 +408,6 @@ re-billed as cache-read each time. Measured over one run, 88 unpiped whole-file
410
408
  reads carried 434 KB.`;
411
409
  }
412
410
 
413
- // The step a missing Test entrypoint is derived by, named in the refusal so the
414
- // caller — a controller or a reviewer — knows what to run rather than what went
415
- // wrong. derive-testcmd.sh's refusals about the cache name the same
416
- // step; its exit-3 refusals name an environment fault instead, which the caller
417
- // fixes rather than deriving. This one covers the case where the snapshot agent
418
- // reported no reason at all.
419
- const DERIVATION_STEP =
420
- "run the Recipe derivation step (run-team phase 0, before the first claim) to derive, prove and write the Recipe cache";
421
-
422
- export function resolveTestCmd(explicit, snap) {
423
- if (explicit) return explicit;
424
- if (snap && snap.testCmd) return snap.testCmd;
425
- throw new Error(
426
- `review-pr: no test command for this repository — ${(snap && snap.testCmdError) || `the snapshot agent read no Recipe cache; ${DERIVATION_STEP}`}. Pass args.testCmd to override.`,
427
- );
428
- }
429
-
430
411
  // The review's one run goes through the suite-slot wrapper, by the Resolver,
431
412
  // so it counts against the host-wide bound on concurrent full runs. The
432
413
  // command is one word to the wrapper — it hands the string to `sh -c` itself —
@@ -1104,6 +1085,15 @@ async function reviewRun(host, args, run) {
1104
1085
  // into it: an absent `pr` is owed "required", not a complaint about digits.
1105
1086
  if (!isDigits(pr)) throw new Error(`review-pr: args.pr must be a PR number, got ${JSON.stringify(pr)}`);
1106
1087
 
1088
+ // Nothing in the review derives a test command: every caller reads the Test
1089
+ // entrypoint off the Recipe cache and passes it. Refused here, beside the
1090
+ // other argument refusals, so a review that could never run its suite costs
1091
+ // no snapshot.
1092
+ const testCmd = A.testCmd;
1093
+ if (typeof testCmd !== "string" || testCmd.trim() === "") {
1094
+ throw new Error(`review-pr: args.testCmd is required — the Test entrypoint the shared run executes, got ${JSON.stringify(testCmd)}`);
1095
+ }
1096
+
1107
1097
  // Resolved only now: the default spawns git, so a missing or malformed `pr`
1108
1098
  // is refused on its own terms before anything is resolved or spawned.
1109
1099
  const scratch = A.scratch === undefined ? standaloneScratchRoot() : A.scratch;
@@ -1154,7 +1144,7 @@ async function reviewRun(host, args, run) {
1154
1144
  ( cd "$SNAP" && git init -q && git add -A -f && git -c user.name=fleet -c user.email=fleet@invalid commit -q --no-verify -m "review snapshot of $SHA" ) || echo SNAPSHOT_INIT_FAILED
1155
1145
  SNAPTREE=$(git -C "$SNAP" rev-parse 'HEAD^{tree}' 2>/dev/null); SRCTREE=$(git -C ${worktree} rev-parse 'HEAD^{tree}')
1156
1146
  { [ -d "$SNAP/.git" ] && [ -n "$SNAPTREE" ] && [ "$SNAPTREE" = "$SRCTREE" ]; } && echo SNAPSHOT_TREE_MATCH || echo SNAPSHOT_TREE_MISMATCH="snapshot $SNAPTREE vs commit $SRCTREE"
1157
- INSTALL=$(~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} install) && echo SNAPSHOT_INSTALL_STEP="$INSTALL" || { INSTALL=; echo SNAPSHOT_INSTALL_UNREAD; }
1147
+ INSTALL=$(~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} install --at origin/main) && echo SNAPSHOT_INSTALL_STEP="$INSTALL" || { INSTALL=; echo SNAPSHOT_INSTALL_UNREAD; }
1158
1148
  [ -z "$INSTALL" ] || { ( cd "$SNAP" && env -u CI sh -c "$INSTALL" ) >"$RUN/install.log" 2>&1; echo SNAPSHOT_INSTALL_EXIT=$?; }
1159
1149
  if [ -d "$SNAP/.git" ] && git -C "$SNAP" status --porcelain --untracked-files=all >"$RUN/status.txt"; then head -n 20 "$RUN/status.txt" | sed 's/^/SNAPSHOT_UNTRACKED=/'; echo SNAPSHOT_UNTRACKED_COUNT=$(wc -l <"$RUN/status.txt" | tr -d ' '); else echo SNAPSHOT_STATUS_FAILED; fi
1160
1150
 
@@ -1273,17 +1263,7 @@ a match nor a mismatch. Do not judge whether the diff is usable, and do not
1273
1263
  withhold one field because another failed: report what you got and let the
1274
1264
  caller decide.
1275
1265
 
1276
- Then read this repository's Test entrypoint out of its Recipe cache:
1277
-
1278
- ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} test
1279
-
1280
- Report \`testCmd\` = its stdout ONLY if it exited 0. If it exited non-zero,
1281
- report \`testCmdError\` = its stderr and omit \`testCmd\`. Never derive or
1282
- guess a command yourself: a refusal about the cache names the step that
1283
- derives it; an exit-3 refusal names an environment fault, and the caller fixes
1284
- that instead of deriving.
1285
-
1286
- Then read, out of the same cache, the merge-gating CI steps that neither the
1266
+ Then read, out of the Recipe cache, the merge-gating CI steps that neither the
1287
1267
  Test entrypoint nor the Check step runs:
1288
1268
 
1289
1269
  ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} uncovered
@@ -1334,8 +1314,7 @@ replaces uncovered.`,
1334
1314
  log(`snapshot ${snap.head} at ${snap.path} — head ref ${snap.refHead || "(absent): head check SKIPPED"} — PR head ${snap.prHead ?? "(absent)"}`);
1335
1315
  log(environmentNote(snap));
1336
1316
 
1337
- const testCmd = resolveTestCmd(A.testCmd, snap);
1338
- log(`testCmd ${A.testCmd ? "(caller override)" : "(derived)"} ${testCmd}`);
1317
+ log(`testCmd ${testCmd}`);
1339
1318
  // An Install step that failed or never ran leaves a snapshot that cannot
1340
1319
  // measure the tree: the shared run is skipped, the suite verdict is not
1341
1320
  // usable through `testRunReason`, and a non-zero exit is filed as a finding.
@@ -182,6 +182,8 @@ above is the correct one.
182
182
 
183
183
  `Closes #N` closes issue on merge — as does any closing keyword (`close`, `fixes`, `resolved`, …) sitting directly before an issue reference, wherever it appears in the body. Write one `Closes #M` per issue you mean to close, so `Closes #A, closes #B` closes both; give every other issue mention a word in front of it — `closed issue #M`, or the issue named without the `#`. A keyword before a list links only the first reference in that list, never the rest: `Closes #A, #B` closes only issue A.
184
184
 
185
+ Close no ticket another claim holds — its issue carries the in-progress label — even when the ticket asks for one PR with it; write `Refs #M`. A ticket closed by another claim's PR strands that claim: neither release nor reap removes it.
186
+
185
187
  Repo gating on release label → exactly one of `patch`/`minor`/`major`; `validate-release-label` fails without it.
186
188
 
187
189
  **Never fold `--label` into the create.** A `gh pr create` that outruns the caller's tool timeout is backgrounded with the PR already open and its flags unapplied, and a timeout carries no exit status for anything to react to — so the label goes missing and every later gate reads the PR as correctly opened. Written as its own command it has its own exit status and fails loudly; `gh pr edit` with no PR argument resolves the current branch's PR, so it lands even when the create's own output was lost to the timeout. Failed → run it again before reporting the PR.
@@ -561,8 +561,8 @@ Dispatch a finisher only when every test here passes at once — the review retu
561
561
  **This bullet and the one above are a pair, and on a clean PR this one carries the
562
562
  whole route to a finisher**: a `no-op` report satisfies the gate above by
563
563
  itself, so nothing further is owed and no further event is coming.
564
- - **The PR's closing references match its ruling and exclude its own suggestion-band record** → `ledger.mjs dispatch` refuses the finisher otherwise, naming the PR and the ticket: repair the body with `gh pr edit <M> --body-file <file>`, then dispatch again.
565
- - **The PR carries exactly one release label, or its repo defines none** → `ledger.mjs dispatch` refuses the finisher otherwise, except a Ticketless PR with none, which `finisher-label.mjs` labels `patch`. Fix them, then dispatch again. In full: references/finisher.md.
564
+ - **The PR's closing references match its ruling and exclude its own suggestion-band record and every ticket another claim holds** → `ledger.mjs dispatch` refuses the finisher otherwise, naming the PR and ticket: `gh pr edit <M>` fixes the body; dispatch again.
565
+ - **The PR carries exactly one release label, or its repo defines none** → `ledger.mjs dispatch` refuses the finisher otherwise, except a Ticketless PR with none, which `finisher-label.mjs` labels `patch`. Fix them; dispatch again. In full: references/finisher.md.
566
566
  - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → the CI edge never
567
567
  fires: dispatch the finisher off the reviewer's final verdict the moment it
568
568
  lands, never while you still owe it a reply. Its gate is then the
@@ -14,9 +14,12 @@ literal outcome
14
14
  Implement ticket <N>. You are ALREADY in worktree `<abs-path>`, whose PR branch is
15
15
  `<branch>`: commit on it and open your PR from it, even when the ticket below names
16
16
  another branch; the settle refuses a PR from any other branch. If the ticket names
17
- one, say in the PR body that you used `<branch>`. Your scratch directory is
18
- `<scratch>/impl-<N>/`; outside the worktree, write nowhere else but your report file
19
- below.
17
+ one, say in the PR body that you used `<branch>`. Label names in this file are roles;
18
+ the Label map gives the string to type; a member never derives the map. Close no ticket
19
+ another claim holds — one whose issue carries the in-progress label — even when the
20
+ ticket below asks for one PR with it: write `Refs #M` instead; the settle refuses a PR
21
+ that closes one. Your scratch directory is `<scratch>/impl-<N>/`; outside the worktree,
22
+ write nowhere else but your report file below.
20
23
 
21
24
  The ticket, pasted verbatim from the controller's own read — its title, the
22
25
  `## Agent Brief` comment or the issue body, whichever carries the brief, and its
@@ -119,7 +119,7 @@ and will act on it. Relay everything — reversals too — then dispatch.
119
119
  append` command to run. Any row for the PR passes, so a replacement finisher
120
120
  is never held once the first passed; a PR no such token names is not gated.
121
121
  No flag skips it: a PR `append` refuses is fixed on the ledger, as at close-out.
122
- - **The PR's closing references match its ruling and exclude its own suggestion-band record** → `ledger.mjs dispatch` reads the PR's `closingIssuesReferences` from `gh pr view <M>` before it dispatches any finisher, counting only those in the PR's own repository: a reference into another repository closes none of this repository's tickets, whatever its number. When the ruled row says `closed_own_ticket=yes`, each ticket a settled `impl-<N>=PR#<M>` token names must be closed by the body (`Closes #<N>`); when it says `no`, none may be, and no reference may be the PR's own suggestion-band record. A blank verdict is refused until it is set. A refusal names the PR and the ticket. The controller repairs the body itself with `gh pr edit <M> --body-file <file>`, then dispatches the finisher again. A `gh` read that fails refuses the dispatch and writes nothing.
122
+ - **The PR's closing references match its ruling and exclude its own suggestion-band record and every ticket another claim holds** → `ledger.mjs dispatch` reads the PR's `closingIssuesReferences` from `gh pr view <M>` before it dispatches any finisher, counting only those in the PR's own repository: a reference into another repository closes none of this repository's tickets, whatever its number. When the ruled row says `closed_own_ticket=yes`, each ticket a settled `impl-<N>=PR#<M>` token names must be closed by the body (`Closes #<N>`); when it says `no`, none may be, and no reference may be the PR's own suggestion-band record. A blank verdict is refused until it is set. Whatever the ruling, and for a Ticketless PR too, no reference besides those tickets may be one another claim holds — one whose issue carries the in-progress label, as the Label map spells it; the same `gh issue view` read of each reference answers it. A refusal names the PR and the ticket, and for a ticket another claim holds says to write `Refs #<M>`. The controller repairs the body itself with `gh pr edit <M> --body-file <file>`, then dispatches the finisher again. A `gh` read that fails refuses the dispatch and writes nothing.
123
123
  - **The PR carries exactly one release label** → `ledger.mjs dispatch` reads the PR's labels from `gh pr view <M>` before it dispatches any finisher, and refuses unless exactly one of `patch`, `minor` and `major` is among them — the count `finisher-label.mjs` makes before it labels. A repository whose label list defines none of the three is not gated. A Ticketless PR with none is not refused: `finisher-label.mjs` adds `patch` to it before its count. Any other PR with none is refused naming the tickets it closes, and any PR with several naming the labels found — the bump, or which label stays, is not picked for the controller. The controller adds or removes the label itself, then dispatches the finisher again. A `gh` read that fails or answers malformed refuses the dispatch, saying the labels could not be read, and writes nothing.
124
124
  - **The PR carries no `ready-to-merge`** → the same `gh pr view <M>` read of the PR's labels answers it, and `ledger.mjs dispatch` refuses any finisher while the label is on, writing nothing and naming `fleet-event.mjs label-off <M>`. A finisher runs on an unlabelled PR: the label a merge bot's `head-moved-after-label` refusal left comes off with its report's settle, and the command takes off any other. A repair finisher's PR lacks the label by definition, so it passes.
125
125
 
@@ -484,7 +484,7 @@ code in the claim tree.
484
484
  **Derive the Recipe — the Recipe derivation step — before the fold-in below
485
485
  and before the first claim.** Every claim runs this repository's Install
486
486
  step and bakes its Test entrypoint into the member's runner, and every
487
- review reads the Test entrypoint, all out of the **Recipe cache**
487
+ review runs the Install step, all out of the **Recipe cache**
488
488
  (`.fleet/recipe.json` beside the common git dir); no script infers either
489
489
  command. Check it first: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh .
490
490
  install --at origin/main`, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check
@@ -522,7 +522,7 @@ stall, below.
522
522
  **Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/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.
523
523
 
524
524
  **Mid-run, a cache that stops running is re-derived once, then the run
525
- stalls.** A claim or a review that refuses because the Recipe cache is
525
+ stalls.** A claim that refuses because the Recipe cache is
526
526
  invalid — a command that no longer runs, or an Install step that changed
527
527
  the tree — is a mid-run trigger: dispatch `derive-recipe` again
528
528
  exactly as above, then retry what refused. So is the `NEED derive-recipe`
@@ -131,7 +131,7 @@ that ran clean has nothing in those three either.
131
131
 
132
132
  ## A failed review is a failure event, not a clean review
133
133
 
134
- The review throws on missing `args.pr`/`args.worktree` and on a snapshot agent
134
+ The review throws on missing `args.pr`/`args.worktree`/`args.testCmd` and on a snapshot agent
135
135
  that returned no tree, and a failure surfaces mid-loop, where "react, never
136
136
  block" makes it easy to log and carry on — leaving a PR that *reads* as
137
137
  reviewed and is not.