@feigi/fleet-ctl 3.157.0 → 3.158.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.
@@ -5,7 +5,7 @@ model: "@slow:high"
5
5
  spawns: task
6
6
  ---
7
7
 
8
- You are a fleet fix-applier. Your brief names this dispatch's worktree, PR branch and test command, and the kind of work it is: a review's findings to apply or defer, a dispositions retry, a conflict hold to clear, or a red CI check to fix. Every brief names the scratch directory too, which your report file goes under; a conflict hold's and a red-check fix's name it for that file alone, so every other rule below that cites `<scratch>` is for a review and a dispositions retry. The rules about findings — scope and refuters, the apply/defer split, the dispositions record and the report of the split and the deferral issues — are for a review and a dispositions retry: a conflict hold and a red-check fix have no review file and write no dispositions record, so their report's `dispositionsRecord` is `null`, and what else each says to report is in its brief. Every other rule below holds for every kind. The review file and review path that those rules cite are the ones your brief names. Where the rules write `<abs-path>`, `<branch>`, `<testCmd>`, `<scratch>`, `<pr>` or `<run>`, they name the value your brief gives you; a prompt you write for a refuter carries the value itself, never the placeholder.
8
+ You are a fleet fix-applier. Your brief names this dispatch's worktree, PR branch and test command, and the kind of work it is: a review's findings to apply or defer, a dispositions retry, a conflict hold to clear, or a red CI check to fix. Every brief names the scratch directory too, which your report file goes under; a conflict hold's and a red-check fix's name it for that file alone, so every other rule below that cites `<scratch>` is for a review and a dispositions retry — but for the round root, which every kind of dispatch makes before its first copy. The rules about findings — scope and refuters, the apply/defer split, the dispositions record and the report of the split and the deferral issues — are for a review and a dispositions retry: a conflict hold and a red-check fix have no review file and write no dispositions record, so their report's `dispositionsRecord` is `null`, and what else each says to report is in its brief. Every other rule below holds for every kind. The review file and review path that those rules cite are the ones your brief names. Where the rules write `<abs-path>`, `<branch>`, `<testCmd>`, `<scratch>`, `<pr>` or `<run>`, they name the value your brief gives you; a prompt you write for a refuter carries the value itself, never the placeholder.
9
9
 
10
10
  Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
11
11
 
@@ -58,7 +58,10 @@ substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
58
58
  under your own run root — `mktemp -d` once per round for
59
59
  `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
60
60
  restart at 1 each round too — and write that absolute path into the
61
- refuter's prompt in its place; a refuter never derives its own path:
61
+ refuter's prompt in its place; a refuter never derives its own path; and write
62
+ the copy command in it the same way, as one absolute command: `<abs-path>` is
63
+ your own worktree, `<head>` the review file's `head`, `<scratch>` the scratch
64
+ directory your brief names and `<N>` the PR number:
62
65
 
63
66
  > Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
64
67
  > RUNNING something — compile it, run the test, apply the mutation. Do not
@@ -82,6 +85,17 @@ refuter's prompt in its place; a refuter never derives its own path:
82
85
  > support a claim about history; a pattern built from the token a diff removed
83
86
  > does not support a claim that the category is empty.
84
87
  >
88
+ > Your own copy of the tree is built by
89
+ > `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run
90
+ > measure-copy.mjs --worktree <abs-path> --pin <head> --dest
91
+ > <scratch>/pr<N>/<finding>/copy --pr <N> --scratch <scratch>`, which you run
92
+ > the first time you need to measure and again for each further copy, each
93
+ > `--dest` another new directory under `<scratch>/pr<N>/<finding>/`. It
94
+ > installs in the copy, so run it as ONE blocking foreground command with a
95
+ > command deadline of 3600 seconds. Never make a copy by hand, and a refuter
96
+ > that only reads builds none. Any non-zero exit is no usable run:
97
+ > inconclusive, never a kill, and `refuted` stays true.
98
+ >
85
99
  > When your check scores a mutant killed or a test red, run only in your own
86
100
  > copy of the tree, and these rules decide it and nothing else:
87
101
  >
@@ -268,16 +282,29 @@ zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
268
282
  eats uncommitted edits you made earlier, and the "clean baseline" you measure
269
283
  next is silently the reverted file. Two members hit this in one run; one lost
270
284
  prose edits and caught it only because a non-catch control failed. Copy the
271
- file aside and copy it back. Better still, mutate a copy under
272
- `<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
273
- refuters are already required to do, and it has no blast radius at all.
285
+ file aside and copy it back. Better still, mutate a copy and leave the worktree
286
+ untouched — that is what refuters are already required to do, and it has no
287
+ blast radius at all. **Every kind of dispatch makes its round root before its
288
+ first copy**: `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`,
289
+ never bare `pr<N>` and never a directory of your own naming. Build the copy
290
+ there with the script that builds every measuring copy, pinned to your own
291
+ commit (the full SHA `git rev-parse HEAD` prints in your worktree once you have
292
+ committed): `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run measure-copy.mjs --worktree <abs-path> --pin <your commit> --dest <round root>/mutate-<k> --pr <pr> --scratch <scratch>`,
293
+ `<k>` 1 for your first copy and the next number for each further one: a copy at
294
+ a later commit is another new directory, since the script refuses one that exists.
295
+ It runs the Install step in the copy, which can take minutes: run it as ONE
296
+ blocking foreground command with a command deadline of 3600 seconds, never
297
+ backgrounded and never polled; any non-zero exit is no usable copy, so measure
298
+ nothing in it. Never make a copy by hand, never make `<scratch>/pr<N>/mutate/`,
299
+ and run no eviction step: the root sweep evicts the installed dependencies of
300
+ every copy under a round root once no fix-applier is live on the PR.
274
301
 
275
302
  **Never `git stash` or `git stash pop` here either — a WIP commit is the
276
303
  substitute, not a second scratch mechanism: `git commit -m wip`, then
277
304
  restore or amend once you're back to real work.** The stash stack is
278
305
  repo-global too, not per-worktree or per-session — the same `refs/stash`
279
306
  every concurrent member and the main checkout share, not partitioned the
280
- way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
307
+ way your round root above is. A bare pop takes whichever entry is
281
308
  on top, from any worktree, silently — rc 0, no error — when the tree
282
309
  receiving it is clean on the affected paths, and refuses only when that
283
310
  tree is already dirty there. A bare `git stash` (push) does not reach into
@@ -40,7 +40,10 @@ the run that shows it surviving.
40
40
 
41
41
  In both modes `<testCmd>` is the `command` your dispatch prompt's
42
42
  Tests paragraph names, run only in your own copy of the snapshot. Make that
43
- copy from the snapshot's tracked files only —
43
+ copy with the command your dispatch prompt gives for it, run exactly as
44
+ written: any non-zero exit is no usable copy, so measure nothing in it. Where
45
+ your dispatch prompt gives none, make that copy from the snapshot's tracked
46
+ files only —
44
47
  `git -C <snapshot> archive HEAD | tar -x -C <copy>`, or a `git clone` of the
45
48
  snapshot repository — then `git init`, `git add -A -f` and commit in it, then
46
49
  run the Install step your dispatch prompt names from the copy's root before
@@ -16,7 +16,7 @@ Label names in this file are roles; the Label map gives the string to type; a me
16
16
  `fleet-review-<key>` (e.g. `fleet-review-correctness`).
17
17
 
18
18
  See **Specialists** — those constraints are not optional.
19
- 2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first, and check it in either scope. Out of the PR's ticket scope → defer and file, but **the claim bar runs first:** a suggestion whose claim is about shape — step 5's worth-a-claim bar, recorded `claimKind: shape` — gets no refuter and goes to the `PR #<pr> review: the suggestion band, checked` record, and every other out-of-scope suggestion gets the same refuter an in-scope one does, dispatched the same way, before it is filed. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. Never run `pkill -f` on a pattern: members share one process table, so a pattern such as a test file's name matches every member's run, not only yours. Clearing your own leftover process needs its PID; report a stalled run to the controller instead. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. **Out of scope the refuter decides only where the suggestion is filed — it defers either way, never applied.** Refuted → the `PR #<pr> review: the suggestion band, checked` record, never an open issue. Survived, or its refuter crashed or abstained → its own open issue labelled `needs-triage`, citing the verdict, or the run that crashed, in the body. There is no cap on these refuters; your final verdict (step 4) says how many you dispatched against out-of-scope suggestions. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed or abstained always defers, whatever its severity** — and which it is, you read off the finding's **`refutersDispatched`** and **`refutersInconclusive`**, never off severity and never off an empty vote list: `refutersDispatched` above zero with nothing decided means every refuter dispatched against it died or abstained, and `refutersInconclusive` counts the ones that abstained. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **An abstention is not a crash** — a refuter that abstained ran and could not decide: defer and file the finding, citing the inconclusive runs each abstaining refuter named in its `reason`, and never describe its refuters as crashed. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
19
+ 2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first, and check it in either scope. Out of the PR's ticket scope → defer and file, but **the claim bar runs first:** a suggestion whose claim is about shape — step 5's worth-a-claim bar, recorded `claimKind: shape` — gets no refuter and goes to the `PR #<pr> review: the suggestion band, checked` record, and every other out-of-scope suggestion gets the same refuter an in-scope one does, dispatched the same way, before it is filed. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path; write the copy command in the same way — `<abs-path>` your own worktree, `<head>` the review file's `head`, the rest resolved likewise — and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. Never run `pkill -f` on a pattern: members share one process table, so a pattern such as a test file's name matches every member's run, not only yours. Clearing your own leftover process needs its PID; report a stalled run to the controller instead. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. Your own copy of the tree is built by `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run measure-copy.mjs --worktree <abs-path> --pin <head> --dest <scratch>/pr<N>/<finding>/copy --pr <N> --scratch <scratch>`, which you run the first time you need to measure and again for each further copy, each `--dest` another new directory under `<scratch>/pr<N>/<finding>/`. It installs in the copy, so run it as ONE blocking foreground command with a command deadline of 3600 seconds. Never make a copy by hand, and a refuter that only reads builds none. Any non-zero exit is no usable run: inconclusive, never a kill, and `refuted` stays true. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. **Out of scope the refuter decides only where the suggestion is filed — it defers either way, never applied.** Refuted → the `PR #<pr> review: the suggestion band, checked` record, never an open issue. Survived, or its refuter crashed or abstained → its own open issue labelled `needs-triage`, citing the verdict, or the run that crashed, in the body. There is no cap on these refuters; your final verdict (step 4) says how many you dispatched against out-of-scope suggestions. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed or abstained always defers, whatever its severity** — and which it is, you read off the finding's **`refutersDispatched`** and **`refutersInconclusive`**, never off severity and never off an empty vote list: `refutersDispatched` above zero with nothing decided means every refuter dispatched against it died or abstained, and `refutersInconclusive` counts the ones that abstained. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **An abstention is not a crash** — a refuter that abstained ran and could not decide: defer and file the finding, citing the inconclusive runs each abstaining refuter named in its `reason`, and never describe its refuters as crashed. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
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 the maintainer instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher until answered; 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 from `<tree>`, the worktree this step runs from, at `origin/main` (`derive-testcmd.sh <tree> check --at origin/main` prints the first, `derive-testcmd.sh <tree> test --at origin/main` the second; every worktree reads the one cache). A refusal naming `--at` (`origin/main` does not resolve) is no cache fault, so fetch it and read again, never derive; exit 3 (a tool the reader needs could not run) is an environment fault, so fix it and read again, never derive; any other exit 1 is a refusal about the cache, so 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. Its `RECIPE NOT PROVEN` is a stop, reported with its reason, and **so is a read that refuses again after `RECIPE PROVEN`, reported with that refusal**: there is no second derivation. 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. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/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. `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.
@@ -49,6 +49,8 @@ Label names in this file are roles; the Label map gives the string to type; a me
49
49
 
50
50
  Three claims, none substituting for another: **run-binding** (this green belongs to this SHA) · **your green** (correct against its base) · **the bot's post-rebase green** (still correct against current `main`). Only the third catches a sibling renaming a symbol you use — a rebase can apply cleanly and still break the build, which is why it is the bot's job and not yours.
51
51
 
52
+ 7. **Standalone, as the last step, run the root sweep:** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --root <scratch> --apply`. With no ledger it refuses and evicts nothing. Under the fleet run no eviction step: the tick runs the sweep.
53
+
52
54
  ## The review result file
53
55
 
54
56
  **Dispatched as a fix-applier, you read the review off one file: `<scratch>/pr<pr>/<run>/review.json`, the path your prompt names — `<run>` the review's own run root, the one the PR's latest `reviewed=` token names.** It holds the bare result object the review returned, in this key order — the digest `pr`, `head`, `resume`, `testEnvironment`, `suiteVerdict`, `dimensionsRun`, `dimensionsUnrun`, `cwdAudit`, `counts`, then `snapshot`, `survived`, `refuted`, `unverified` — the `review-pr-<pr#>` runner member (`agents/fleet-review-runner.agent.md`) writes it. The controller reads the digest and never the findings, so **every per-PR ruling in this section is yours** — nobody upstream has made one for you. A prompt that pastes the findings in instead of naming the file hands you the same buckets, and every ruling here applies to them unchanged. Read the file a bucket at a time with `jq`, never whole into your context — a review's result runs to tens of KB:
@@ -69,7 +71,7 @@ jq '.refuted' "$R" # refuted: your
69
71
 
70
72
  **Read `testEnvironment` and `cwdAudit` before you act on any result of the shared test run.** `testEnvironment` says whether the snapshot the specialists ran in was verified as the reviewed tree: verified, a red there is a fact about the tree; UNVERIFIED, tests that ask git what ships decline or fail for the environment, so a red or a short count there is not a finding until you reproduce it in the worktree. `cwdAudit` is each specialist's audit of the checkout it inherited, `{dimension, state, line}`: `dirty` and `missing` are equally loud, because either names a checkout a specialist may have written to. Check it with `git -C <that path> status --porcelain -uall` — the path is in a `dirty` entry's `line`, and a `missing` entry's is the main checkout, the parent of `git rev-parse --path-format=absolute --git-common-dir` — and report what it printed; never revert content you did not write. A `dimensionsUnrun` entry is a specialist that returned nothing, its `reason` the crash: name it unrun in your report, because an absence of findings is not coverage, and re-run nothing — the review already re-dispatched every crashed specialist once, in-run. `suiteVerdict` is the review's one judgement on its shared test run, `{usable, reason}`: usable does not mean green, and the verdict says nothing about whether a dimension reviewed. When `suiteVerdict.usable` is false, name `shared test run not usable: <reason>` in your final verdict and do nothing more about it — your own `<testCmd>` run and CI cover the suite.
71
73
 
72
- **Scan the findings against each other for MUTUAL EXCLUSION, and rule before the conflicting change reaches the tree.** Refuters are blind to their siblings, so two can approve changes that cannot both land — one preserving a comment block another's change deletes, one keeping a binding another collapses. Two runs produced it; in one, a refuter proved a variable collapse behavior-equivalent over 844 cases while its own blast-radius scan named the two comment blocks a *different* refuter had just established as guarding distinct pinned hazards. You hold every finding, so only you can see the pair — and the scan's two inputs arrive at different times, so run it twice. **Before you apply anything**, group the findings by `file:line` and by whether one's fix undoes another's; that is in the findings' own text. **Then as each refuter you dispatch reports**, read its blast radius against what you have already ruled on. **A conflicting pair goes to a SINGLE refuter, briefed with both claims** — that is what settled one such pair, one refuter ruling *"B wins: A's premise is false"* where two independent refuters would each have approved their own side. Defer only when no single refuter can settle it, with the equivalence evidence recorded in the filed issue so the work is not redone. Never let both reach the tree and hope the diff coheres.
74
+ **Scan the findings against each other for MUTUAL EXCLUSION, and rule before the conflicting change reaches the tree.** Refuters are blind to their siblings, so two can approve changes that cannot both land — one preserving a comment block another's change deletes, one keeping a binding another collapses. You hold every finding, so only you can see the pair — and the scan's two inputs arrive at different times, so run it twice. **Before you apply anything**, group the findings by `file:line` and by whether one's fix undoes another's; that is in the findings' own text. **Then as each refuter you dispatch reports**, read its blast radius against what you have already ruled on. **A conflicting pair goes to a SINGLE refuter, briefed with both claims** — that is what settled one such pair, one refuter ruling *"B wins: A's premise is false"* where two independent refuters would each have approved their own side. Defer only when no single refuter can settle it, with the equivalence evidence recorded in the filed issue so the work is not redone. Never let both reach the tree and hope the diff coheres.
73
75
 
74
76
  **A finding whose suggested fix quotes text another applied finding deletes goes stale on arrival.** **Re-derive, never copy:** apply the finding that changes the text first, then derive the assertion from the post-fix tree. A `suggested_fix` is a hypothesis the review never ran; only the claim was refuted against.
75
77
 
@@ -98,7 +100,7 @@ It cannot ask the user anything and cannot wait on CI — rebasing, watching che
98
100
 
99
101
  Tell readers **`git show <sha>:<path>` is the source of truth** — the object store cannot be contaminated by any agent, needs no copy, and touches nothing. Make it the default for settling *what the PR contains*, not a fallback. A finding that disagrees with it is a probe artifact. **Then bound the read — the guarantee is the blob, not the byte count.** `git show <sha>:<path> | sed -n 'A,Bp'` reads the same uncontaminatable object; take the file whole only once `| wc -l` says it is small — a count, not a feeling. Where the *change* is what you are settling, diff instead of reading: `git diff <base>...<head> -- <path>` for the PR's whole change, `git show <sha> -- <path>` only for one named commit's. That second form is scoped to that single commit and prints **nothing, at exit 0**, when the commit did not touch the path (measured) — the same silent green as `tests 0`, and it reads as "the PR changed nothing here". What an unbounded read costs is in run-team's `references/reviewers.md` (**What an unbounded read costs**).
100
102
 
101
- **Brace a ref held in a variable — `git show "${SHA}:<path>"` — because quoting is not what fixes it.** zsh reads a `:x` suffix after an unbraced parameter as a history modifier, inside double quotes as well as outside, so git is handed a ref nobody typed; braces end the parameter name before the colon. Measured, fully quoted: the construct that fails loudly on one path exits 0 on another and prints the *commit* instead of the blob — and the silent shape is the hazard, because a survival `grep -c` scores it as a plausible hit and re-anchors a citation that was correct. A literal ref is unaffected either way; quote regardless — not for zsh's sake, which splits and globs an expansion's *result* only under `SH_WORD_SPLIT`/`GLOB_SUBST`, both off by default (measured: `V="a b"` unquoted still arrives as one argument), but so the same line survives a `bash` runner, where an unquoted path holding a space does split — measured, `fatal: path 'has' does not exist`.
103
+ **Brace a ref held in a variable — `git show "${SHA}:<path>"` — because quoting is not what fixes it.** zsh reads a `:x` suffix after an unbraced parameter as a history modifier, so git is handed a ref nobody typed; braces end the parameter name before the colon. Evidence: run-team's `references/reviewers.md` (**Bracing a ref held in a variable**).
102
104
 
103
105
  **The fan-out scales to the diff — the review computes it, you don't.** Its snapshot agent runs `diff-stats.mjs`, and `selectDimensions` keeps the applicable subset of the six-specialist catalog (fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify): fleet-review-correctness always; fleet-review-tests whenever the diff touches a test file, and also for a `production`-profile diff that changes source and touches no test file — there its job is the coverage gap, mutating the changed source and reporting behaviour no existing test kills, so untested source changes get asked that question during review — and dropped otherwise, so a diff with no source and no test file loses it; fleet-review-types / fleet-review-silent-failure / fleet-review-simplify with no source; a docs-only PR keeps only fleet-review-correctness + fleet-review-comments. **Then the size tier applies a floor on top:** a `single-file` or `small` profile keeps fleet-review-correctness + fleet-review-silent-failure + fleet-review-comments, plus fleet-review-tests when the diff touches a test file — so a small source PR runs three, not five, and the coverage-gap case above never reaches the size tier. **fleet-review-comments is unconditional on the floor**: it used to need a docs *file* in the diff, but `classify()` scores `.js`/`.mjs` `src` via the code-extension check and `.sh` `src` by falling through everything else, so a PR whose whole substance was prose in a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and lost the one specialist whose job it was — measured five times in production, all correction-class PRs, with `dimensionsUnrun` empty each time because the trim was by design. **The floor outranks the no-source drop for fleet-review-silent-failure**: a one-file `.yml` or `.github/` shell change runs fleet-review-correctness + fleet-review-silent-failure, which is the pair a swallowed error in CI needs. Above the size tier the no-source drop still stands, and `tests-only` outranks the size tier for a diff with no config file — a no-src, no-config diff that also touches a test file gets no fleet-review-silent-failure; a tests-only diff that also carries a config file keeps it. `single-file` is one file at *any* size. Profile unknown → the full six, the safe direction. Pin a subset explicitly with `args.dimensions` (keys or dimension objects). Dispatching by hand instead of automatically: apply the same heuristic yourself — two or three for annotation-only or single-file, the full six for production code.
104
106
 
@@ -109,5 +111,5 @@ Tell readers **`git show <sha>:<path>` is the source of truth** — the object s
109
111
  - **Verify, don't reason.** "Removing X makes this compile/fail" → compile it in an isolated copy. One command. Four successive confident claims about one file were all wrong; the compiler settled it.
110
112
  - **Distrust negative claims hardest.** "Nothing else references this", "the sweep is clean" — most likely false, least likely checked: a grep that found nothing looks like a grep never run. Make the specialist state its search scope. Negative claim vs specific finding with paths → paths win.
111
113
  - **Mutation-verify any "this test pins X".** Apply the mutation, confirm *that* test fails — a valid red, and a kill only against the green run on the unmutated tree, as step 2's refuter rules define them — revert. Then one it should **not** catch, staying green — else you proved it fails, not that it discriminates. **One syntactic form is not the class:** a stripper killing `// whole-line` passed a guard that `code; // trailing` walked through.
112
- - **Comments are findings**, and the most common one. A comment asserting what the code does not do is a defect. One run shipped five: an invented citation, a mis-stated failure mode, a test file named as covering what it had zero coverage of, an overstated cast fix, a claim its own dependency's source contradicts. Check every added assertion against the tree — **including comments in files this diff does not touch** but whose claims it falsifies (test-name references, "N of 3" counts, tracking-issue pointers).
114
+ - **Comments are findings**, and the most common one. A comment asserting what the code does not do is a defect. Check every added assertion against the tree — **including comments in files this diff does not touch** but whose claims it falsifies (test-name references, "N of 3" counts, tracking-issue pointers).
113
115
  - **A finding on a PR body or a commit body** names that surface in its `claim` ("PR body:", or "commit <sha>:") and carries no `file` and no `line`, so `dispositions-check.mjs` presumes it in scope. A false claim in the PR body is corrected there, by editing it with `gh pr edit`. **A commit body cannot be rewritten** — never rewrite history to correct one: correct a false commit-body claim in the PR body instead, say there what the change really does, and that counts as applying the finding. The finding still stands as the review's record: correcting the claim does not withdraw the finding.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.157.0",
3
+ "version": "3.158.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": {
package/scripts/evict.mjs CHANGED
@@ -89,9 +89,9 @@
89
89
  // run. Prints
90
90
  // `{"applied","worktree","install"}`; exit 0 restored (or would), 2 refused.
91
91
  //
92
- // That install sequence is `installIn()`, exported: finisher-tree.mjs runs the
93
- // same read, the same checks and the same words in the tree it builds for the
94
- // acceptance mutation, so there is one copy of it.
92
+ // That install sequence is `installIn()`, exported: finisher-tree.mjs and
93
+ // measure-copy.mjs run the same read, the same checks and the same words in
94
+ // the tree they build, so there is one copy of it.
95
95
 
96
96
  import { spawnSync } from "node:child_process";
97
97
  import { readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -418,15 +418,23 @@ function sweep({ afterRotate, apply }) {
418
418
  * called with `apply` set, after every check ahead of the Install step has
419
419
  * passed and just before it starts; it returns null, or the message of a
420
420
  * refusal, which then keeps the Install step from running. `install` is null in
421
- * a refusal that came before the command was read. Nothing here writes a mark
421
+ * a refusal that came before the command was read. `source` is the tree the
422
+ * Install step is read from, `tree` itself by default: a copy holds no Recipe
423
+ * cache of its own, so its caller names the worktree whose cache every
424
+ * worktree of the repository shares. `untracked`, set, makes an Install step
425
+ * that leaves untracked paths no refusal: the result is then `{install,
426
+ * untracked: {count, first}}`, `first` the first 20 lines of `git status
427
+ * --porcelain -uall` and `count` how many there are; a tracked file the step
428
+ * changed is still `dirtied`, and a status that cannot be read after the step
429
+ * is still `status-after`. Nothing here writes a mark
422
430
  * or a restore time, and it never exits the process.
423
431
  */
424
- export function installIn(tree, apply, { verb = "restore", retry = true, beforeRun = () => null } = {}) {
432
+ export function installIn(tree, apply, { verb = "restore", retry = true, beforeRun = () => null, source = tree, untracked = false } = {}) {
425
433
  const refuse = (kind, message, install = null, exit = null) => ({ refusal: { kind, message, install, exit } });
426
- const derived = run("sh", [join(SCRIPT_DIR, "derive-testcmd.sh"), tree, "install", "--at", "origin/main"]);
434
+ const derived = run("sh", [join(SCRIPT_DIR, "derive-testcmd.sh"), source, "install", "--at", "origin/main"]);
427
435
  const install = String(derived.stdout ?? "").replace(/\n$/, "");
428
436
  if (derived.error || derived.status !== 0 || install === "") {
429
- return refuse("derive", String(derived.stderr ?? "").trim() || `derive-testcmd.sh ${tree} install failed (${how(derived)})`);
437
+ return refuse("derive", String(derived.stderr ?? "").trim() || `derive-testcmd.sh ${source} install failed (${how(derived)})`);
430
438
  }
431
439
  // Dirty before anything runs is no Install step's doing: said in its own
432
440
  // words, so the dirty-after refusal below never blames the Recipe for it.
@@ -450,6 +458,14 @@ export function installIn(tree, apply, { verb = "restore", retry = true, beforeR
450
458
  if (r.status !== 0) return refuse("failed", `install failed in ${tree} (exit ${r.status})`, install, r.status);
451
459
  const status = git(tree, ["status", "--porcelain", "-uall"]);
452
460
  if (status.error || status.status !== 0) return refuse("status-after", `could not verify the tree state in ${tree} after the Install step`, install, 0);
461
+ if (untracked) {
462
+ const lines = status.stdout.split("\n").filter((l) => l !== "");
463
+ // An untracked path is reported; a tracked file the step changed leaves
464
+ // a tree that is no longer the one the step was run in.
465
+ const changed = lines.find((l) => !l.startsWith("?? "));
466
+ if (changed === undefined) return { install, untracked: { count: lines.length, first: lines.slice(0, 20) } };
467
+ return refuse("dirtied", `the Install step '${install}' changed a tracked file in ${tree} (first: ${changed}) — ${REDERIVE}`, install, 0);
468
+ }
453
469
  if (status.stdout !== "") return refuse("dirtied", `the Install step '${install}' changed the tree in ${tree} (first: ${status.stdout.split("\n")[0]}) — ${REDERIVE}`, install, 0);
454
470
  return { install };
455
471
  }
@@ -44,16 +44,18 @@
44
44
  // never when. Pruned to the live set on every tick, so a settled
45
45
  // member's stamp does not outlive it. Carried, never written, by
46
46
  // the heartbeat and by ledger.mjs.
47
- // applied fleet-tick only, and only under --apply. {run, reapAfter}: the
48
- // merge-bot numbers whose `merge-bot-<n>=done` the tick has already
49
- // run reap.sh, reclaim-scratch.mjs and evict.mjs after, and the
50
- // controller record's `at` they belong to. Written only under a
51
- // record: with none, nothing tells one run from the next. Merge-bot
52
- // numbering restarts at 1 in a run that carries no bot forward, and
53
- // this file outlives the rotation, so a list whose `run` is not the
54
- // current record's `at` is the previous run's and names nothing in
55
- // this one. Carried, never written, by the heartbeat and by
56
- // ledger.mjs.
47
+ // applied fleet-tick only, and only under --apply. {run, reapAfter,
48
+ // sweptAfter}: the merge-bot numbers whose `merge-bot-<n>=done` the
49
+ // tick has already run reap.sh, reclaim-scratch.mjs and evict.mjs
50
+ // after (`reapAfter`), the fix-applier, finisher and failed review
51
+ // launch names whose settle it has already run reclaim-scratch.mjs
52
+ // after (`sweptAfter`, left out while empty), and the controller
53
+ // record's `at` they belong to. Written only under a record: with none, nothing tells
54
+ // one run from the next. Merge-bot numbering restarts at 1 in a run
55
+ // that carries no bot forward, and this file outlives the rotation,
56
+ // so a list whose `run` is not the current record's `at` is the
57
+ // previous run's and names nothing in this one. Carried, never
58
+ // written, by the heartbeat and by ledger.mjs.
57
59
  //
58
60
  // One writer per key. A key two scripts wrote would need locking to be
59
61
  // correct, and none of them is in a position to hold one. That holds per key,
@@ -256,7 +258,8 @@ export function readState(path, name, warn = console.error) {
256
258
  const done = (v) => {
257
259
  if (!isRecord(v) || !Array.isArray(v.reapAfter)) return null;
258
260
  if (!(Number.isInteger(v.run) && v.run > 0)) return null;
259
- return { run: v.run, reapAfter: v.reapAfter.filter((n) => Number.isInteger(n) && n > 0) };
261
+ const swept = Array.isArray(v.sweptAfter) ? v.sweptAfter.filter((m) => typeof m === "string" && m !== "") : [];
262
+ return { run: v.run, reapAfter: v.reapAfter.filter((n) => Number.isInteger(n) && n > 0), ...(swept.length > 0 ? { sweptAfter: swept } : {}) };
260
263
  };
261
264
  const { quiet, digest, beat, ticked, acted, controller, seen, applied, ...rest } = parsed;
262
265
  // A controller key that ctl() rejects is a record someone wrote and nobody
@@ -153,7 +153,7 @@
153
153
  // the ledger; main() does the I/O. Split so the guard table and the reading are
154
154
  // both unit-testable without a network.
155
155
 
156
- import { parseMember, parseToken, premisesOf, rowNums, nextRetry, readRetired, pullEnded, dispositionsToken, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
156
+ import { parseMember, parseToken, premisesOf, rowNums, nextRetry, readRetired, pullEnded, dispositionsToken, failedReviewLaunches, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
157
157
 
158
158
  // The implementer and reviewer rows' TARGET is the In-flight bound; the merge
159
159
  // bot's is 1. Availability of work belongs in the ACTION, not the target: a
@@ -1227,6 +1227,10 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1227
1227
  // The number of every merge bot settled `done`: each is a merge pass
1228
1228
  // `--apply` reaps, reclaims and evicts after, once (reapDue).
1229
1229
  mergeBotDone: all.filter((m) => m.family === "merge-bot" && m.outcome === "done").map((m) => m.number).sort(asc),
1230
+ // The name of every fix-applier and finisher settled, whatever its outcome,
1231
+ // and of every review launch settled `=failed`: each is a settle
1232
+ // `--apply` runs the root sweep after, once (sweepDue).
1233
+ sweepAfter: [...all.filter((m) => (m.family === "fix-pr" || m.family === "finisher-pr") && m.outcome !== null).map((m) => m.name), ...failedReviewLaunches(rows)],
1230
1234
  reviewsLive: liveReviews.length,
1231
1235
  // The in-flight reviews of PRs the open list does not carry: the ones
1232
1236
  // the probe could retire, so the caller asks gh about these and no others.
@@ -1547,21 +1551,41 @@ export function ageChecks({ live, stems }) {
1547
1551
  ];
1548
1552
  }
1549
1553
 
1550
- // --apply's pure half. The merge-bot numbers `applied.reapAfter` names for
1551
- // THIS run: none when its `run` is not the controller record's `at`, since
1552
- // merge-bot numbering restarts with a run and the state file outlives it
1553
- // (fleet-state.mjs's `applied`). `controllerAt` is null with no record, and
1554
- // with no record nothing tells this run from the one before it: a list then
1555
- // names nothing, and the sweeps run again on the next tick.
1554
+ // --apply's pure half. `applied` when its `run` is THIS run's controller
1555
+ // record `at`, else null: merge-bot numbering restarts with a run, a name such
1556
+ // as `fix-pr-7` is reused by the next run's first member of its PR, and the
1557
+ // state file outlives both (fleet-state.mjs's `applied`). `controllerAt` is
1558
+ // null with no record, and with no record nothing tells this run from the one
1559
+ // before it: a list then names nothing, and the sweeps run again on the next
1560
+ // tick.
1561
+ const ofThisRun = (applied, controllerAt) => (applied !== null && controllerAt != null && applied.run === controllerAt ? applied : null);
1562
+
1563
+ // The entries of `names` that `ran` does not hold.
1564
+ const notIn = (names, ran) => {
1565
+ const done = new Set(ran);
1566
+ return names.filter((name) => !done.has(name));
1567
+ };
1568
+
1569
+ // The merge-bot numbers `applied.reapAfter` names for THIS run.
1556
1570
  export function reapedAfter(applied, controllerAt) {
1557
- return applied !== null && controllerAt != null && applied.run === controllerAt ? applied.reapAfter : [];
1571
+ return ofThisRun(applied, controllerAt)?.reapAfter ?? [];
1558
1572
  }
1559
1573
 
1560
1574
  // The merge passes owed their reap, reclaim and evict: every merge bot settled
1561
1575
  // `done` that reapedAfter() does not name.
1562
1576
  export function reapDue(done, applied, controllerAt) {
1563
- const ran = new Set(reapedAfter(applied, controllerAt));
1564
- return done.filter((n) => !ran.has(n));
1577
+ return notIn(done, reapedAfter(applied, controllerAt));
1578
+ }
1579
+
1580
+ // The members `applied.sweptAfter` names for THIS run.
1581
+ export function sweptAfter(applied, controllerAt) {
1582
+ return ofThisRun(applied, controllerAt)?.sweptAfter ?? [];
1583
+ }
1584
+
1585
+ // The settles owed the root sweep: every member in `settled` (run.sweepAfter)
1586
+ // that sweptAfter() does not name.
1587
+ export function sweepDue(settled, applied, controllerAt) {
1588
+ return notIn(settled, sweptAfter(applied, controllerAt));
1565
1589
  }
1566
1590
 
1567
1591
  // The implementers the tick would print `HOLD (tier unchecked …)` for: read
@@ -1594,13 +1618,13 @@ export function reapSummary(stdout) {
1594
1618
  + (warned.length ? `, warnings ${warned.length}${typeof first === "string" ? `: ${first}` : ""}` : "");
1595
1619
  }
1596
1620
 
1597
- // reclaim-scratch.mjs's receipt as `removed <k>, kept <m>, failed <f>`, or
1621
+ // reclaim-scratch.mjs's receipt as `removed <k>, [evicted <e>, ]kept <m>, failed <f>`, or
1598
1622
  // null. A removal that failed is in the receipt and exits 0: it is reported
1599
1623
  // here, and the pass still counts as reclaimed after.
1600
1624
  export function reclaimSummary(stdout) {
1601
1625
  const r = receiptOf(stdout);
1602
1626
  if (r === null || ![r.removed, r.kept, r.failed].every(Array.isArray)) return null;
1603
- return `removed ${r.removed.length}, kept ${r.kept.length}, failed ${r.failed.length}`;
1627
+ return `removed ${r.removed.length}, ${Array.isArray(r.evicted) ? `evicted ${r.evicted.length}, ` : ""}kept ${r.kept.length}, failed ${r.failed.length}`;
1604
1628
  }
1605
1629
 
1606
1630
  // evict.mjs's receipt as `evicted <k>, kept <m>, failed <f>`, or null. A tree
@@ -1697,7 +1721,9 @@ const OPTIONS = {
1697
1721
  "fold-unchanged": { type: "boolean", default: false },
1698
1722
  // `--apply` runs the idempotent follow-ups whose trigger the ledger and the
1699
1723
  // state file show, before the rows: reap.sh, reclaim-scratch.mjs and
1700
- // evict.mjs after every merge pass settled `done`, and tier-check.mjs on every implementer
1724
+ // evict.mjs after every merge pass settled `done`, reclaim-scratch.mjs
1725
+ // alone after every settle of a fix-applier, a finisher or a review launch
1726
+ // `=failed`, and tier-check.mjs on every implementer
1701
1727
  // the tick would hold as unchecked. It never dispatches, never settles a
1702
1728
  // member and writes no ledger row but through those scripts. Without it the
1703
1729
  // tick is read-only.
@@ -2057,11 +2083,24 @@ function reportDuty(r, { label, duty, what, summarise }) {
2057
2083
  // root or set of claim trees rather than one pass's share. Each runs whether
2058
2084
  // or not the one before it did: none reads another's result. True only when
2059
2085
  // all three applied, the one case `due` is recorded as reaped after; otherwise
2060
- // the next --apply tick runs them again.
2086
+ // the next --apply tick runs them again. `{all, reclaimed}`: the second is true
2087
+ // when the root sweep applied, which is also the sweep a settled member owes.
2061
2088
  function applyReap(due) {
2062
2089
  const label = `reap after ${due.map((n) => `merge-bot-${n}`).join(" ")}`;
2063
2090
  const reaped = reportDuty(runSibling("reap.sh", ["--apply"]), { label, duty: "reap", what: "reap.sh", summarise: reapSummary });
2064
- let reclaimed = false;
2091
+ const reclaimed = applySweep("reclaim");
2092
+ const evicted = reportDuty(runSibling("evict.mjs", ["--apply"]),
2093
+ { label: "evict", duty: "evict", what: "evict.mjs", summarise: evictSummary });
2094
+ return { all: reaped && reclaimed && evicted, reclaimed };
2095
+ }
2096
+
2097
+ // The root sweep, `reclaim-scratch.mjs --root <scratch> --apply`: after a merge
2098
+ // pass, and after the settle of a fix-applier, a finisher or a failed review
2099
+ // launch, each of which leaves trees nothing of their kind is left to use.
2100
+ // True when it applied: a receipt printed, failures listed in it included, the
2101
+ // next trigger retrying those. A non-zero exit or no receipt is not, and the
2102
+ // next --apply tick runs it again.
2103
+ function applySweep(label) {
2065
2104
  let root = null;
2066
2105
  try {
2067
2106
  root = scratchRoot();
@@ -2069,13 +2108,9 @@ function applyReap(due) {
2069
2108
  if (!(e instanceof FleetDirUnresolvable)) throw e;
2070
2109
  console.log(`APPLY FAILED reclaim: ${e.message}`);
2071
2110
  }
2072
- if (root !== null) {
2073
- reclaimed = reportDuty(runSibling("reclaim-scratch.mjs", ["--root", root, "--apply"]),
2074
- { label: "reclaim", duty: "reclaim", what: "reclaim-scratch.mjs", summarise: reclaimSummary });
2075
- }
2076
- const evicted = reportDuty(runSibling("evict.mjs", ["--apply"]),
2077
- { label: "evict", duty: "evict", what: "evict.mjs", summarise: evictSummary });
2078
- return reaped && reclaimed && evicted;
2111
+ if (root === null) return false;
2112
+ return reportDuty(runSibling("reclaim-scratch.mjs", ["--root", root, "--apply"]),
2113
+ { label, duty: "reclaim", what: "reclaim-scratch.mjs", summarise: reclaimSummary });
2079
2114
  }
2080
2115
 
2081
2116
  // tier-check.mjs's verdict by its exit status, each one a token the check
@@ -2372,16 +2407,26 @@ function main() {
2372
2407
 
2373
2408
  if (apply) {
2374
2409
  // Reap, reclaim and evict after every merge pass settled `done` since the
2375
- // last time they ran. Recorded only once all three applied, on a fresh read of the
2410
+ // last time they ran, and the root sweep after every settle `sweepAfter`
2411
+ // names that `sweptAfter` does not. A merge pass is recorded in `reapAfter`
2412
+ // only once all three applied, and a settle in `sweptAfter` once a root
2413
+ // sweep applied, the merge pass's own included; each on a fresh read of the
2376
2414
  // state file so nothing the heartbeat wrote meanwhile is reverted, never
2377
2415
  // onto a file that could not be read, and never with no controller
2378
2416
  // record: nothing could tell a list recorded then from the next run's.
2379
2417
  const run0 = controller?.at ?? null;
2380
2418
  const due = reapDue(run.mergeBotDone, priorState.applied, run0);
2381
- if (due.length && applyReap(due) && run0 !== null) {
2419
+ const owed = sweepDue(run.sweepAfter, priorState.applied, run0);
2420
+ const reap = due.length ? applyReap(due) : null;
2421
+ // The root sweep a merge pass ran is the one a settled member owes too.
2422
+ const swept = owed.length > 0 && (reap?.reclaimed || applySweep(`reclaim after ${owed.join(" ")}`));
2423
+ const reaped = reap?.all ? due : [];
2424
+ if (run0 !== null && (reaped.length > 0 || swept)) {
2382
2425
  const now = readState(path, NAME);
2383
2426
  if (!now.degraded) {
2384
- writeState(path, NAME, now, { applied: { run: run0, reapAfter: [...new Set([...reapedAfter(now.applied, run0), ...due])] } });
2427
+ const reapAfter = [...new Set([...reapedAfter(now.applied, run0), ...reaped])];
2428
+ const sweptNames = [...new Set([...sweptAfter(now.applied, run0), ...(swept ? owed : [])])];
2429
+ writeState(path, NAME, now, { applied: { run: run0, reapAfter, ...(sweptNames.length > 0 ? { sweptAfter: sweptNames } : {}) } });
2385
2430
  }
2386
2431
  }
2387
2432
  // The tier check, on exactly the members the implementer row would hold
@@ -760,6 +760,23 @@ function launchedRunners(text) {
760
760
  return out;
761
761
  }
762
762
 
763
+ /**
764
+ * The reviewer runner names every row's `review=member:<name>=failed` launch
765
+ * settled dead, once each, in row order: the launches whose review run root
766
+ * nothing is left to write to. A workflow launch is named by its runId, which
767
+ * no runner name matches, and a launch that is open or answered is not here.
768
+ */
769
+ export function failedReviewLaunches(rows) {
770
+ const out = [];
771
+ for (const text of rows) {
772
+ for (const word of text.split(/\s+/)) {
773
+ const m = REVIEW.exec(word);
774
+ if (m !== null && m.groups.failed !== undefined && m.groups.kind === "member" && REVIEWER.test(m.groups.name) && !out.includes(m.groups.name)) out.push(m.groups.name);
775
+ }
776
+ }
777
+ return out;
778
+ }
779
+
763
780
  /**
764
781
  * The names an `ancestor` rotate retires: every member the archive settled —
765
782
  * in `## Dispatched` or on any row, the same two places `ledger.mjs dispatch`
@@ -0,0 +1,242 @@
1
+ #!/usr/bin/env node
2
+ // A measuring copy as one command: the tree an agent mutates, runs a suite in
3
+ // or reproduces a failure in, built at a pinned commit with the Install step
4
+ // already run in it. Every copy a fix-applier, a fix-applier's refuter, a
5
+ // review specialist or a review refuter measures in is built by this script,
6
+ // so each is a repository of its own (the root sweep evicts only a directory
7
+ // that holds a `.git` of its own) and each has what the Install step leaves.
8
+ //
9
+ // measure-copy.mjs --worktree <abs> --pin <sha> --dest <abs> --pr <N> --scratch <abs>
10
+ //
11
+ // `--worktree` is the PR's worktree: git runs there, and every worktree of that
12
+ // repository shares its refs and Recipe cache, which a copy of tracked files
13
+ // holds none of — so the Install step is read from it, never from the copy or
14
+ // from a review snapshot. `--pin` is the full 40-hex commit to copy. `--dest`
15
+ // is the copy: a new directory inside a `fix-*` round root or a `run-*` run
16
+ // root that sits directly under `<scratch>/pr<N>/`. `--scratch` is the absolute
17
+ // scratch root the dispatch prompt names. Reached through the Resolver:
18
+ // `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run measure-copy.mjs ...`.
19
+ //
20
+ // In order, each step only once every earlier one held:
21
+ //
22
+ // 1 The destination. It is written down from `--scratch` as
23
+ // `<scratch>/pr<N>/<root>/…/<dest>` (`<scratch>` as given or by realpath),
24
+ // `<root>` a directory named `fix-…` or `run-…` that is there, and it has no
25
+ // `.` or `..` segment; nothing from `<scratch>` down to the destination that
26
+ // exists may be a symlink; and nothing may exist at the destination itself,
27
+ // a dangling symlink or an empty directory included. Anything else builds
28
+ // nothing.
29
+ // 2 `git init` in it, then the pin's objects fetched from the worktree, its
30
+ // tree read into the index and checked out, `git add -A` and a commit.
31
+ // The commit's tree must be the pin's tree. Never `git archive`, which
32
+ // leaves out gitlinks and `export-ignore` paths and rewrites
33
+ // `export-subst` files.
34
+ // 3 The Install step, by evict.mjs's `installIn()`: read from the worktree
35
+ // with `derive-testcmd.sh <worktree> install --at origin/main`, run from the
36
+ // copy's root through `sh -c` with `CI` unset, no timeout, under no suite
37
+ // slot, a clean `git status --porcelain -uall` required before it. What the
38
+ // step leaves untracked afterwards is reported, never refused; a tracked
39
+ // file it changed is a refusal.
40
+ //
41
+ // Stdout is one JSON line, the receipt, whatever happened after the arguments
42
+ // parsed:
43
+ //
44
+ // {dest, pr, pin, head, tree, install, kind, exit, untracked, untrackedCount, message}
45
+ //
46
+ // dest the path the copy was, or would have been, built at
47
+ // head the copy's commit, null when never read
48
+ // tree the copy's commit tree, null when never read
49
+ // install the Install step's command, null when never read
50
+ // kind `built`, or what stopped it: `outside`, `occupied`,
51
+ // `unreadable`, `pin-unreadable`, `init-failed`,
52
+ // `fetch-failed`, `checkout-failed`, `tree-mismatch`, or one of
53
+ // evict.mjs's `installIn()` kinds: `derive`, `status-before`,
54
+ // `dirty-before`, `not-run`, `failed`, `dirtied`, `status-after`
55
+ // exit the Install step's own exit status, null when it produced none
56
+ // untracked the first 20 lines of `git status --porcelain -uall` in the
57
+ // copy after the Install step, null when it was never read
58
+ // untrackedCount how many lines there are in all
59
+ // message null when built, else the refusal in words
60
+ //
61
+ // Exit vocabulary:
62
+ //
63
+ // 0 built: the copy is the pin's tree and its Install step exited 0
64
+ // 1 no usable copy, nothing the Install step did: a destination outside a
65
+ // round root or run root, or one that exists; an init, a fetch, a
66
+ // checkout or a commit that failed; a tree that is not the pin's; a Recipe
67
+ // that could not be read; a status that could not be read before the
68
+ // Install step
69
+ // 2 a refusal on stderr with no receipt: a usage refusal, as in every other
70
+ // script, or a receipt that could not be written to stdout
71
+ // 3 the Install step did not run: exit 126 or 127, or it could not be started
72
+ // 4 the Install step failed: another non-zero exit, or a signal, or it
73
+ // changed a tracked file
74
+ // 5 the Install step ran and the copy's state could not be read after it
75
+ //
76
+ // Any non-zero exit leaves the copy where it stands: this script removes
77
+ // nothing.
78
+
79
+ import { spawnSync } from "node:child_process";
80
+ import { lstatSync, mkdirSync, realpathSync } from "node:fs";
81
+ import { isAbsolute, join, resolve, sep } from "node:path";
82
+ import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
83
+ import { how } from "./evict-mark.mjs";
84
+ import { installIn } from "./evict.mjs";
85
+ import { gitEnv } from "./git-env.mjs";
86
+ import { isCLI } from "./is-cli.mjs";
87
+
88
+ const NAME = "measure-copy";
89
+ const die = makeDie(NAME);
90
+ const USAGE = "usage: measure-copy.mjs --worktree <abs> --pin <sha> --dest <abs> --pr <N> --scratch <abs>";
91
+ const SHA = /^[0-9a-f]{40}$/;
92
+ const ROOT = /^(?:fix|run)-./;
93
+ const GIT_TIMEOUT_MS = 5 * 60_000;
94
+ const MAX_BUFFER = 64 * 1024 * 1024;
95
+
96
+ // The installIn() refusal kinds an Install step that ran or tried to run
97
+ // answers for; every other refusal is exit 1.
98
+ const EXIT = {
99
+ "not-run": 3,
100
+ failed: 4,
101
+ dirtied: 4,
102
+ "status-after": 5,
103
+ };
104
+
105
+ const git = (dir, args) =>
106
+ spawnSync("git", ["-C", dir, ...args], { encoding: "utf8", maxBuffer: MAX_BUFFER, env: gitEnv(), timeout: GIT_TIMEOUT_MS });
107
+
108
+ /**
109
+ * Why `dest` is not a place this script builds, as `{kind, message}`, or null
110
+ * when it is. `scratch` and `pr` are the arguments; no path is created or
111
+ * changed.
112
+ */
113
+ export function destRefusal(dest, scratch, pr) {
114
+ const outside = (message) => ({ kind: "outside", message });
115
+ if (dest.split(sep).some((s) => s === "." || s === "..")) return outside(`${dest} has a '.' or '..' segment`);
116
+ const bases = [resolve(scratch)];
117
+ try {
118
+ bases.push(realpathSync(scratch));
119
+ } catch (e) {
120
+ return { kind: "unreadable", message: `cannot resolve --scratch ${scratch} (${e.code ?? e.message})` };
121
+ }
122
+ const base = bases.find((b) => dest.startsWith(join(b, `pr${pr}`) + sep));
123
+ if (base === undefined) return outside(`${dest} is not inside <scratch>/pr${pr}/ (${scratch})`);
124
+ const parts = dest.slice(join(base, `pr${pr}`).length + 1).split(sep);
125
+ if (parts.some((s) => s === "")) return outside(`${dest} has an empty segment`);
126
+ if (parts.length < 2 || !ROOT.test(parts[0])) {
127
+ return outside(`${dest} is not inside a fix-* round root or a run-* run root directly under ${join(base, `pr${pr}`)}`);
128
+ }
129
+ let at = base;
130
+ for (const [i, part] of [`pr${pr}`, ...parts].entries()) {
131
+ at = join(at, part);
132
+ let st;
133
+ try {
134
+ st = lstatSync(at);
135
+ } catch (e) {
136
+ if (e.code !== "ENOENT") return { kind: "unreadable", message: `cannot look at ${at} (${e.code ?? e.message})` };
137
+ // The round root or run root is made before any copy: a missing one is
138
+ // a typo, not a place to create. Below it, nothing exists to refuse.
139
+ return i <= 1 ? outside(`${at} does not exist — make the round root or run root before the copy`) : null;
140
+ }
141
+ // Anything at the destination, a symlink included, is an occupied path.
142
+ if (at === dest) return { kind: "occupied", message: `${dest} already exists — a copy built over it would not be the pin's` };
143
+ if (st.isSymbolicLink()) return outside(`${at} is a symlink`);
144
+ if (!st.isDirectory()) return outside(`${at} is not a directory`);
145
+ }
146
+ return null;
147
+ }
148
+
149
+ function main() {
150
+ const { arg, sweep, stray } = defineFlags(die, {
151
+ flags: { worktree: "value", pin: "value", dest: "value", pr: "value", scratch: "value" },
152
+ });
153
+ // The sweep runs before the required-flag check so a misspelled flag is
154
+ // named as that, not buried under a missing-flag usage line.
155
+ sweep();
156
+ stray();
157
+ const worktree = arg("worktree");
158
+ const pinArg = arg("pin");
159
+ const destArg = arg("dest");
160
+ const pr = arg("pr");
161
+ const scratchArg = arg("scratch");
162
+ if ([worktree, pinArg, destArg, pr, scratchArg].includes(null)) die(USAGE);
163
+ if (!isAbsolute(worktree)) die(`--worktree needs an absolute path, got ${worktree}`);
164
+ if (!isAbsolute(destArg)) die(`--dest needs an absolute path, got ${destArg}`);
165
+ if (!isAbsolute(scratchArg)) die(`--scratch needs an absolute path, got ${scratchArg}`);
166
+ const pin = pinArg.toLowerCase();
167
+ if (!SHA.test(pin)) die(`--pin needs a full 40-character commit SHA, got ${pinArg}`);
168
+ if (!isDigits(pr) || Number(pr) < 1) die(`--pr needs a PR number, got ${pr}`);
169
+
170
+ // Only a trailing slash is forgiven; every other oddity is a refusal below.
171
+ const dest = destArg.length > 1 ? destArg.replace(/\/+$/, "") : destArg;
172
+ const receipt = { dest, pr: Number(pr), pin, head: null, tree: null, install: null, kind: null, exit: null, untracked: null, untrackedCount: null, message: null };
173
+ const finish = (code, kind, message = null) => {
174
+ receipt.kind = kind;
175
+ receipt.message = message;
176
+ // A receipt lost on its way to stdout must not leave its exit standing: an
177
+ // exit 0 with no receipt names no copy to work in, so a lost write is the
178
+ // no-receipt exit.
179
+ if (!writeAll(1, `${JSON.stringify(receipt)}\n`)) die("the receipt could not be written to stdout");
180
+ process.exitCode = code;
181
+ };
182
+
183
+ // 1: the destination.
184
+ const refusal = destRefusal(dest, scratchArg, pr);
185
+ if (refusal !== null) return finish(1, refusal.kind, refusal.message);
186
+
187
+ // 2: the copy, at the pin, as its own repository. The pin's tree is read
188
+ // first: a pin the worktree does not hold builds nothing, and the comparison
189
+ // at the end is against what git says the pin is, never against the copy.
190
+ const want = git(worktree, ["rev-parse", "--verify", "--end-of-options", `${pin}^{tree}`]);
191
+ const wanted = String(want.stdout ?? "").trim();
192
+ if (want.error || want.status !== 0 || wanted === "") return finish(1, "pin-unreadable", `could not read the tree of ${pin} in ${worktree} (${how(want)})`);
193
+ try {
194
+ mkdirSync(dest, { recursive: true });
195
+ } catch (e) {
196
+ return finish(1, "unreadable", `cannot make ${dest} (${e.code ?? e.message})`);
197
+ }
198
+ // The pin's objects are fetched into the copy and its tree checked out from
199
+ // them, never archived: `git archive` leaves out a submodule's gitlink and
200
+ // every `export-ignore` path and rewrites an `export-subst` file, so its copy
201
+ // of such a pin is never the pin's tree. A gitlink is checked out as an empty
202
+ // directory and stays in the index as the pin holds it. The add reads the
203
+ // checked-out files back, so one the checkout does not carry back unchanged
204
+ // is a tree mismatch below. Each step is its own child, so the one that
205
+ // failed names the refusal with git's own words.
206
+ const made = [
207
+ ["init-failed", ["init", "-q"]],
208
+ ["fetch-failed", ["-c", "protocol.version=2", "fetch", "-q", "--no-tags", "--depth=1", worktree, pin]],
209
+ ["checkout-failed", ["read-tree", pin]],
210
+ ["checkout-failed", ["checkout-index", "-a", "-f"]],
211
+ ["init-failed", ["add", "-A"]],
212
+ ["init-failed", ["-c", "user.name=fleet", "-c", "user.email=fleet@invalid", "-c", "commit.gpgsign=false", "commit", "-q", "--no-verify", "--allow-empty", "-m", `measuring copy of ${pin}`]],
213
+ ];
214
+ for (const [kind, args] of made) {
215
+ const step = git(dest, args);
216
+ if (step.error || step.status !== 0) return finish(1, kind, `git ${args.filter((a) => a !== "-c" && !a.includes("=")).join(" ")} failed in ${dest} (${how(step)})`);
217
+ }
218
+ const head = git(dest, ["rev-parse", "HEAD", "HEAD^{tree}"]);
219
+ const [at, tree] = String(head.stdout ?? "").trim().split("\n");
220
+ if (head.error || head.status !== 0 || !at || !tree) return finish(1, "init-failed", `could not read HEAD in ${dest} (${how(head)})`);
221
+ receipt.head = at;
222
+ receipt.tree = tree;
223
+ if (tree !== wanted) return finish(1, "tree-mismatch", `the copy's tree ${tree} is not the tree ${wanted} of ${pin}`);
224
+
225
+ // 3: the Install step, read from the worktree, run in the copy. No retry in a
226
+ // dirty-before refusal: the caller runs none of this script's steps by hand
227
+ // to get past one.
228
+ const done = installIn(dest, true, { verb: "install", retry: false, source: worktree, untracked: true });
229
+ if (done.refusal) {
230
+ const { kind, message, install, exit } = done.refusal;
231
+ receipt.install = install;
232
+ receipt.exit = exit;
233
+ return finish(EXIT[kind] ?? 1, kind, message);
234
+ }
235
+ receipt.install = done.install;
236
+ receipt.exit = 0;
237
+ receipt.untracked = done.untracked.first;
238
+ receipt.untrackedCount = done.untracked.count;
239
+ finish(0, "built");
240
+ }
241
+
242
+ if (isCLI(import.meta.url)) main();
@@ -35,9 +35,10 @@
35
35
  // finisher-pr-<M>[-x]. A live merge-bot-<n> token holds every one
36
36
  // of them: a bot's token names no PR, and GitHub reads MERGED
37
37
  // while the bot is still writing under pr<M>/merge-bot-<n>/. An
38
- // OPEN PR's pr<M>/ is kept whole except its run-* roots, which
39
- // follow the --pr rule below. A MERGED PR's entry that holds
40
- // review evidence — a `<run>/review.json` under pr<M>/, or a
38
+ // OPEN PR's pr<M>/ is kept, but for its run-* roots, which follow
39
+ // the --pr rule below, and the trees named below. A MERGED PR's
40
+ // entry that holds review evidence — a `<run>/review.json` under
41
+ // pr<M>/, or a
41
42
  // Charges file naming its run — is also kept until origin/main
42
43
  // holds every file of it where run-records.mjs's reviewTargets()
43
44
  // puts it, under docs/metrics/reviews/<M>/: the Close-out PR
@@ -46,6 +47,21 @@
46
47
  // or evidence that cannot be read, keeps the entry with that
47
48
  // reason. A CLOSED PR gets no Ruling, and its entries keep the
48
49
  // rule above.
50
+ // EVERY pr<M>/ the sweep keeps — an OPEN PR's, a live holder's or
51
+ // review evidence's, and one a live merge bot holds — also has
52
+ // the trees in it evicted (evict-tree.mjs's rule), by the kind of
53
+ // member that made them, once none of that kind is live on the
54
+ // ledger: the trees under its fix-* round roots, and under a
55
+ // mutate/ left from before, when no fix-pr-<M>[-x] is live; the
56
+ // trees under its run-* roots, when no review launch of PR #M is
57
+ // open; every finish-* tree, when no finisher-pr-<M>[-x] is live.
58
+ // The ledger is read for that after the directory's roots are
59
+ // listed, just before they are evicted, and a merge bot's hold
60
+ // keeps the directory but never its trees. A directory kept for
61
+ // a reason that names no state of the PR — GitHub did not answer,
62
+ // or the number names an issue — is not evicted. What is left in
63
+ // it — verdict files, prompts, receipts, logs, review.json, the
64
+ // mutants — stays.
49
65
  // impl-<N>/
50
66
  // removed when issue #N is CLOSED, or OPEN with no live
51
67
  // impl-<N>[-x] token, no claim worktree standing, and idle past
@@ -120,13 +136,16 @@
120
136
  // "kept":[{"path","reason"}],"failed":[{"path","error"}]}
121
137
  // The sibling pass's kept entries also carry "idle": true when nothing under
122
138
  // the key was found modified within the retention, false otherwise.
123
- // `--pr` mode adds `"evicted":[{"path","reason","ignored"}]` after `removed`:
124
- // each tree that held ignored paths, `ignored` naming them, and
139
+ // `--pr` mode and the root sweep add `"evicted":[{"path","reason","ignored"}]`
140
+ // after `removed`: each tree that held ignored paths, `ignored` naming them and
141
+ // `reason` naming the rule that evicted it, and
125
142
  // `"skipped":[{"path","reason"}]` after `failed`: each directory in a kept run
126
- // root that evict-tree.mjs could not evaluate — one with a `.git` git does not
127
- // resolve to it, one it cannot look in for a `.git`, or one it cannot list for
128
- // EACCES or EPERM. A skipped directory is never in `failed`, so the snapshot
129
- // step's marker, which reads `failed`, does not fire for it.
143
+ // root, round root or finisher tree that evict-tree.mjs could not evaluate —
144
+ // one with a `.git` git does not resolve to it, one it cannot look in for a
145
+ // `.git`, or one it cannot list for EACCES or EPERM. A skipped directory is
146
+ // never in `failed`, so the snapshot step's marker, which reads `failed`, does
147
+ // not fire for it. A kept pr<N>/ whose roots cannot be listed, or whose ledger
148
+ // cannot be read just before its eviction, is in `failed`.
130
149
  // `ledger` is the file read, or null when none was (`--pr` mode, or
131
150
  // `--after-rotate` with no file) — so "never read" stays distinct from "read
132
151
  // and found empty". A dry run prints the same receipt with "applied":false,
@@ -149,7 +168,7 @@ import { fleetFile, FleetDirUnresolvable, SCRATCH_KEY_SHAPE, scratchRoot } from
149
168
  import { gitEnv } from "./git-env.mjs";
150
169
  import { ghAliasedRead, how } from "./gh-aliased-read.mjs";
151
170
  import { isCLI } from "./is-cli.mjs";
152
- import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
171
+ import { liveOnLedger, parseMember, REVIEW, REVIEWER, rowNums } from "./ledger-grammar.mjs";
153
172
  import { REVIEWS_DIR, reviewTargets } from "./run-records.mjs";
154
173
 
155
174
  const NAME = "reclaim-scratch";
@@ -172,6 +191,8 @@ const REPORTS_DIR = "reports";
172
191
  const REPORT_PR_ENTRY = /^(?:fix-pr|finisher-pr|review-pr)-([1-9][0-9]*)(?:-[a-z])?(?:\.check)?\.json$/;
173
192
  const REPORT_IMPL_ENTRY = /^impl-([1-9][0-9]*)(?:-[a-z])?(?:\.check)?\.json$/;
174
193
  const RUN_ROOT = /^run-/;
194
+ const FIX_ROOT = /^fix-/;
195
+ const FINISH_ROOT = /^finish-/;
175
196
 
176
197
  /** The path of something under `path` (itself included) modified at or after
177
198
  * `cutoff`, or null when everything is older. Symlinks are not followed. A
@@ -227,10 +248,18 @@ export function readLedger(file, die, undone) {
227
248
  return { rows: d.rows, dispatched: d.dispatched };
228
249
  }
229
250
 
230
- // The live tokens the ledger holds, by name.
231
- function liveNames(file) {
232
- const { rows, dispatched } = readLedger(file, die, "reclaimed");
233
- return liveOnLedger(rows, dispatched).tokens.map((t) => t.name);
251
+ // The live tokens the ledger holds, as `{name, launchOf}`: `launchOf` the PR
252
+ // whose rows carry the token when it is an open review launch — a runner's, or
253
+ // a workflow's, whose name is its runId — else null. `fail` and `undone` are
254
+ // readLedger()'s: a read made after removals have started throws, so the one
255
+ // directory's eviction is a failure on the receipt and the sweep goes on.
256
+ function liveTokens(file, fail = die, undone = "reclaimed") {
257
+ const { rows, dispatched } = readLedger(file, fail, undone);
258
+ const launchPr = new Map();
259
+ for (const text of rows) {
260
+ for (const word of text.split(/\s+/)) if (REVIEW.test(word) && !launchPr.has(word)) launchPr.set(word, rowNums(text).pr);
261
+ }
262
+ return liveOnLedger(rows, dispatched).tokens.map((t) => ({ name: t.name, launchOf: launchPr.get(t.token) ?? null }));
234
263
  }
235
264
 
236
265
  // The checkout the fleet dir sits in, and its ledger file — `file` null when it
@@ -345,11 +374,72 @@ function githubStates(numbers) {
345
374
  return out;
346
375
  }
347
376
 
348
- // The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}]}`.
377
+ // The roots under a kept `pr<N>/` whose trees the sweep evicts when no member
378
+ // of the kind that made them is live, each as `{path, kind}`: a fix-applier's
379
+ // round root (`fix-*`) or a `mutate/` left from before, a review's run root
380
+ // (`run-*`) and a finisher's tree (`finish-*`). `skip` is the paths already
381
+ // being removed whole. An absent directory holds none; one that cannot be
382
+ // listed throws.
383
+ function treeRoots(pdir, skip) {
384
+ let entries;
385
+ try {
386
+ entries = readdirSync(pdir, { withFileTypes: true });
387
+ } catch (e) {
388
+ if (e.code === "ENOENT" || e.code === "ENOTDIR") return [];
389
+ throw e;
390
+ }
391
+ const roots = [];
392
+ for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
393
+ if (!e.isDirectory()) continue;
394
+ const path = join(pdir, e.name);
395
+ if (skip.has(path)) continue;
396
+ const kind = e.name === "mutate" || FIX_ROOT.test(e.name) ? "fix" : RUN_ROOT.test(e.name) ? "run" : FINISH_ROOT.test(e.name) ? "finish" : null;
397
+ if (kind !== null) roots.push({ path, kind });
398
+ }
399
+ return roots;
400
+ }
401
+
402
+ // The live holder of the kind `kind` names on PR `n`, by name, or undefined:
403
+ // a `fix-pr-<n>[-x]`, a `finisher-pr-<n>[-x]`, or an open review launch of PR
404
+ // #n — `review-pr-<n>[-x]`, or a workflow launch on PR #n's rows, named by its
405
+ // runId. `live` is liveTokens()'s list.
406
+ function kindHolder(live, kind, n) {
407
+ return live.find(({ name, launchOf }) => {
408
+ if (kind === "run") {
409
+ const r = REVIEWER.exec(name);
410
+ return launchOf === n || (r !== null && Number(r[1]) === n);
411
+ }
412
+ const m = parseMember(name);
413
+ return m !== null && m.family === (kind === "fix" ? "fix-pr" : "finisher-pr") && m.number === n;
414
+ })?.name;
415
+ }
416
+
417
+ const EVICT_RULE = {
418
+ fix: (n, name) => (name === "mutate" ? `a tree in pr${n}/mutate/, left from before, with no live fix-pr-${n}[-x] on the ledger` : `a tree in a fix-applier round root, with no live fix-pr-${n}[-x] on the ledger`),
419
+ run: (n) => `a tree in a review run root, with no open review launch of PR #${n} on the ledger`,
420
+ finish: (n) => `a finisher tree, with no live finisher-pr-${n}[-x] on the ledger`,
421
+ };
422
+
423
+ // The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}],
424
+ // evict: [{n, path, roots}]}`. `evict` is each kept `pr<N>/` directory whose
425
+ // trees the sweep evicts, `roots` the roots it listed in it, or `{n, path,
426
+ // error}` when it could not list them: whether a root's kind of member is live
427
+ // is read later, just before the eviction.
349
428
  function judgeRoot(root, names, live, now, listing, checkout) {
350
429
  const cutoff = now - RETENTION_MS;
351
430
  const remove = [];
352
431
  const kept = [];
432
+ const evict = [];
433
+ // A kept pr<N>/ keeps its trees only while a member of the kind that made
434
+ // them is live; a live merge bot's hold on the directory is no such member.
435
+ const evictIn = (path, n) => {
436
+ const skip = new Set(remove.map((r) => r.path));
437
+ try {
438
+ evict.push({ n, path, roots: treeRoots(path, skip) });
439
+ } catch (e) {
440
+ evict.push({ n, path, error: e.message });
441
+ }
442
+ };
353
443
  const liveMembers = live.map(parseMember).filter((m) => m !== null);
354
444
  const bot = liveMembers.find((m) => m.family === "merge-bot");
355
445
  const prHolder = (n) => live.find((name) => {
@@ -452,18 +542,21 @@ function judgeRoot(root, names, live, now, listing, checkout) {
452
542
  continue;
453
543
  }
454
544
  if (kind === "pr") {
545
+ const isDir = name === `pr${n}`;
455
546
  if (bot !== undefined) {
456
547
  kept.push({ path, reason: `live ${bot.name} holds every pr<N>` });
548
+ if (isDir) evictIn(path, n);
457
549
  continue;
458
550
  }
459
551
  if (s.state === "OPEN") {
460
552
  kept.push({ path, reason: `PR #${n} is OPEN` });
461
- if (name === `pr${n}`) {
553
+ if (isDir) {
462
554
  try {
463
555
  remove.push(...staleRunRoots(path, cutoff, kept));
464
556
  } catch (e) {
465
557
  kept.push({ path, reason: `its run-* roots cannot be listed: ${e.message}` });
466
558
  }
559
+ evictIn(path, n);
467
560
  }
468
561
  continue;
469
562
  }
@@ -474,11 +567,14 @@ function judgeRoot(root, names, live, now, listing, checkout) {
474
567
  const holder = prHolder(n);
475
568
  if (holder !== undefined) {
476
569
  kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
570
+ if (isDir) evictIn(path, n);
477
571
  continue;
478
572
  }
479
573
  const held = s.state === "MERGED" ? evidenceHold(path, name, n) : null;
480
- if (held !== null) kept.push({ path, reason: held });
481
- else remove.push({ path, reason: `PR #${n} is ${s.state}` });
574
+ if (held !== null) {
575
+ kept.push({ path, reason: held });
576
+ if (isDir) evictIn(path, n);
577
+ } else remove.push({ path, reason: `PR #${n} is ${s.state}` });
482
578
  continue;
483
579
  }
484
580
  if (s.state === "CLOSED") {
@@ -502,7 +598,7 @@ function judgeRoot(root, names, live, now, listing, checkout) {
502
598
  if (freshUnder(path, cutoff) === null) remove.push({ path, reason: `issue #${n} is OPEN, no live impl-${n} token, idle past 7 days` });
503
599
  else kept.push({ path, reason: `issue #${n} is OPEN; modified within 7 days` });
504
600
  }
505
- return { remove, kept };
601
+ return { remove, kept, evict };
506
602
  }
507
603
 
508
604
  // The run-* directories directly under `parent` idle past the retention, as
@@ -691,12 +787,20 @@ function main() {
691
787
 
692
788
  const now = Date.now();
693
789
  let ledger = null;
694
- // `--pr` mode's evictions and skipped directories, in its receipt only.
790
+ // The evictions and skipped directories of `--pr` mode and the root sweep.
695
791
  const evicted = [];
696
792
  const skipped = [];
697
793
  let remove;
698
794
  let kept = [];
795
+ let evict = [];
699
796
  const failed = [];
797
+ // Evicts the trees under `path`, each named on the receipt with `reason`.
798
+ const evictRoot = (path, reason) => {
799
+ const done = evictTrees(path, { apply });
800
+ for (const t of done.evicted) evicted.push({ path: t.path, reason, ignored: t.ignored });
801
+ failed.push(...done.failed);
802
+ skipped.push(...done.skipped);
803
+ };
700
804
  if (pr !== null) {
701
805
  const parent = join(root, `pr${Number(pr)}`);
702
806
  try {
@@ -706,12 +810,7 @@ function main() {
706
810
  failed.push({ path: parent, error: e.message });
707
811
  }
708
812
  // `--pr` mode also evicts the trees in every run root it keeps.
709
- for (const run of kept) {
710
- const done = evictTrees(run.path, { apply });
711
- for (const t of done.evicted) evicted.push({ path: t.path, reason: "a tree in a kept review run root", ignored: t.ignored });
712
- failed.push(...done.failed);
713
- skipped.push(...done.skipped);
714
- }
813
+ for (const run of kept) evictRoot(run.path, "a tree in a kept review run root");
715
814
  } else if (siblings) {
716
815
  if (apply) {
717
816
  const wrote = writeCheckout(root);
@@ -730,7 +829,7 @@ function main() {
730
829
  const found = ledgerFile(die);
731
830
  ledger = found.file;
732
831
  if (ledger === null && !afterRotate) die("no .fleet/ledger.md — without it no live member can hold its scratch, so nothing is reclaimed; pass --after-rotate only straight after `ledger.mjs rotate`");
733
- const live = ledger === null ? [] : liveNames(ledger);
832
+ const live = ledger === null ? [] : liveTokens(ledger).map((t) => t.name);
734
833
  let names;
735
834
  try {
736
835
  names = readdirSync(root).sort();
@@ -738,7 +837,7 @@ function main() {
738
837
  die(`could not list --root ${root}: ${e.message}`);
739
838
  }
740
839
  const listing = worktreeListing(found.checkout);
741
- ({ remove, kept } = judgeRoot(root, names, live, now, listing, found.checkout));
840
+ ({ remove, kept, evict } = judgeRoot(root, names, live, now, listing, found.checkout));
742
841
  }
743
842
 
744
843
  const removed = [];
@@ -765,7 +864,28 @@ function main() {
765
864
  if (error === null) removed.push(entry);
766
865
  else failed.push({ path: entry.path, error });
767
866
  }
768
- const receipt = { applied: apply, ledger, removed, ...(pr === null ? {} : { evicted }), kept, failed, ...(pr === null ? {} : { skipped }) };
867
+ // The trees of every kept pr<N>/, once the removals are done: a root is
868
+ // evicted only while no member of the kind that made it is live, and the
869
+ // ledger is read for that now, after the roots were listed, so a member
870
+ // dispatched in between holds its trees.
871
+ for (const dir of evict) {
872
+ if (dir.error !== undefined) {
873
+ failed.push({ path: dir.path, error: `its roots cannot be listed: ${dir.error}` });
874
+ continue;
875
+ }
876
+ if (dir.roots.length === 0) continue;
877
+ let liveNow;
878
+ try {
879
+ liveNow = ledger === null ? [] : liveTokens(ledger, (message) => { throw new Error(message); }, "evicted");
880
+ } catch (e) {
881
+ failed.push({ path: dir.path, error: e.message });
882
+ continue;
883
+ }
884
+ for (const r of dir.roots) {
885
+ if (kindHolder(liveNow, r.kind, dir.n) === undefined) evictRoot(r.path, EVICT_RULE[r.kind](dir.n, basename(r.path)));
886
+ }
887
+ }
888
+ const receipt = { applied: apply, ledger, removed, ...(siblings ? {} : { evicted }), kept, failed, ...(siblings ? {} : { skipped }) };
769
889
  writeAll(1, `${JSON.stringify(receipt)}\n`);
770
890
  }
771
891
 
@@ -743,24 +743,35 @@ function countsOf(run) {
743
743
  }
744
744
 
745
745
  // How a specialist or refuter makes "your own copy of the snapshot", in
746
- // every prompt that sends one to work there. Tracked files only, then the
747
- // Install step in the copy: what an install writes can record absolute paths
748
- // back into the tree it ran in, so a copy that shares the snapshot's
749
- // installed output imports the snapshot's source, and a mutation made in the
750
- // copy never runs.
751
- export function copyRule(snap) {
752
- const step = snap && snap.installCmd
753
- ? `the Install step, \`${snap.installCmd}\`,`
754
- : "the Install step (this review read none, so a copy has nothing installed and a suite run in it does not measure the tree)";
755
- return `Make your own copy of the snapshot from its tracked files only —
756
- \`git -C ${snap && snap.path} archive HEAD | tar -x -C <copy>\`, or a \`git clone\`
757
- of the snapshot repository — then make it a repository with \`git init\`,
758
- \`git add -A -f\` and a commit (a clone already is one), then run
759
- ${step} from the copy's root before you measure anything in it.
760
- Never \`cp -R\` the snapshot, and never symlink or clone its ignored paths: an
761
- install can record absolute paths back into the tree it ran in, so a copy
762
- sharing the snapshot's installed output runs the snapshot's source, and a
763
- mutation in the copy never runs.`;
746
+ // every prompt that sends one to work there: by measure-copy.mjs, the one
747
+ // script that builds every measuring copy. It builds the copy from the PR
748
+ // worktree at the reviewed head, makes it a repository of its own and runs the
749
+ // Install step in it, so the copy holds what an install leaves — which one that
750
+ // shares the snapshot's installed output would not, since an install can record
751
+ // absolute paths back into the tree it ran in and a mutation made there would
752
+ // never run. `worktree` is the PR worktree, never the snapshot: the snapshot
753
+ // holds tracked files only, and the Install step is read from the repository's
754
+ // shared Recipe cache, which every worktree reads. `dir` is the agent's own
755
+ // directory of the run root; the copy is built under it. `scratch` and `pr`
756
+ // are runReview's own, the ones the run root was checked against, never read
757
+ // back off the run root the snapshot agent reported.
758
+ export function copyRule(snap, worktree, dir, scratch, pr) {
759
+ return `Make your own copy of the tree at the reviewed head with the one script that
760
+ builds every measuring copy, never by hand — it builds the copy from the PR
761
+ worktree at that commit, makes it a repository of its own and runs the Install
762
+ step from the copy's root:
763
+ ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run measure-copy.mjs --worktree ${worktree} --pin ${snap.head} --dest ${dir}/copy --pr ${pr} --scratch ${scratch}
764
+ For each further copy, give \`--dest\` another new directory under ${dir}/. The
765
+ Install step can take minutes: run the command as ONE blocking foreground
766
+ command with a command deadline of 3600 seconds, never backgrounded and never
767
+ polled. It prints one JSON line, the receipt, and exits 0 only when the copy is
768
+ the reviewed head's tree and its Install step exited 0; the receipt lists what
769
+ the step left untracked. Any other exit is no usable copy: measure nothing in
770
+ it, never make one by hand, and name the exit and the receipt's \`message\` in
771
+ what you report. \`--worktree\` is the one use of the PR worktree this prompt
772
+ allows, and the script's own: you never read or write it. Never \`cp -R\` or clone
773
+ the snapshot, and never symlink its ignored paths: it holds tracked files only,
774
+ and a copy sharing the snapshot's installed output runs the snapshot's source.`;
764
775
  }
765
776
 
766
777
  // The Tests paragraph of every specialist prompt: the shared run's
@@ -1464,7 +1475,7 @@ READ ONLY FROM THE SNAPSHOT: ${snap.path} (HEAD ${snap.head}) — plus the diff
1464
1475
  file named below, if one is given.
1465
1476
  Never read or write ${worktree} — other agents are using it.
1466
1477
  Run any mutation or probe work inside your own copy of the snapshot.
1467
- ${copyRule(snap)}
1478
+ ${copyRule(snap, worktree, `${snap.runRoot}/${d.key}`, scratch, pr)}
1468
1479
 
1469
1480
  Your shell starts in NEITHER of those directories, and what it does start in is
1470
1481
  a tree you must not write to: this dispatch carries no working directory of its
@@ -1563,7 +1574,7 @@ decide it and nothing else:
1563
1574
 
1564
1575
  ${KILL_RULES}
1565
1576
 
1566
- ${copyRule(snap)}
1577
+ ${copyRule(snap, worktree, `${snap.runRoot}/verify-${d.key}/f${fi + 1}-l${i + 1}`, scratch, pr)}
1567
1578
 
1568
1579
  ${PATTERN_KILL_RULE}
1569
1580
 
@@ -118,6 +118,22 @@ or a fix-applier into one; before you run code in one by hand, restore it with
118
118
  `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run evict.mjs --restore <tree> --apply`, which runs the
119
119
  Install step there as a claim does.
120
120
 
121
+ **One script builds every measuring copy.** A copy an agent mutates or runs a
122
+ suite in — a fix-applier's own, its refuters', a review specialist's and a
123
+ review refuter's — is built by `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run measure-copy.mjs --worktree <abs-path> --pin <sha> --dest <abs> --pr <N> --scratch <scratch>`:
124
+ the tree at the pinned commit, made a repository of its own, with the Install
125
+ step run in it. It reads the Install step from the PR worktree, since a copy
126
+ holds no Recipe cache, and it refuses any `--dest` that is not a new directory
127
+ inside a `fix-*` round root or a `run-*` run root directly under
128
+ `<scratch>/pr<N>/`. A fix-applier makes its round root with `mktemp -d` before
129
+ its first copy, whatever kind of dispatch it is, and no `pr<N>/mutate/` is
130
+ made. Exit 0 means the copy is the pin's tree and the Install step exited 0;
131
+ any other exit is no usable copy. The root sweep evicts the installed
132
+ dependencies of every such tree once no member of the kind that made them is
133
+ live on the ledger, and the tick runs the sweep after each fix-applier,
134
+ failed review launch and finisher settles, so no fix-applier or finisher runs
135
+ an eviction step of its own.
136
+
121
137
  ## Filesystem isolation is not stack isolation
122
138
 
123
139
  Private copy and test command solve different problems; conflating them is how second gets skipped: compose project name comes from environment, not working directory, so three agents on three snapshots still collide on one postgres. Observed: a probe returned `No test files found / No such container` and would have read as a test failure. Symlinking installed dependencies in does not help. "I'm on my own copy" is exactly the intuition that skips command — say both, every time. Which command depends on audience: member in worktree uses `./agent-test`; specialist on snapshot does not, takes one `review-and-fix.md` hands out. Which runner the worktree holds decides why: the runner a claim writes is untracked, so a `git archive` snapshot never carries it; one the repository tracks does ride along, but no claim exported ports into it — its isolation is whatever that repository built, not one triple per snapshot.
@@ -237,3 +237,15 @@ diff.
237
237
  ## What an unbounded read costs
238
238
 
239
239
  `review-and-fix.md`'s **Then bound the read** rests on this. The cost of not bounding is never one-off: a specialist that dumps a 37 KB file carries it in its prefix for every remaining turn, re-billed as cache-read on each. Over one run's 92 subagents the 88 unpiped whole-file calls carried 434 KB (~110k tokens) — the single largest attributed line item in that run — against 319 piped ones. Agents already reach for the bounded form; nothing told them when it is required.
240
+
241
+ ## Bracing a ref held in a variable
242
+
243
+ `review-and-fix.md`'s **Brace a ref held in a variable** rests on this. The history modifier applies inside double quotes as well as outside. Measured, fully quoted: the construct that fails loudly on one path exits 0 on another and prints the *commit* instead of the blob — and the silent shape is the hazard, because a survival `grep -c` scores it as a plausible hit and re-anchors a citation that was correct. A literal ref is unaffected either way; quote regardless — not for zsh's sake, which splits and globs an expansion's *result* only under `SH_WORD_SPLIT`/`GLOB_SUBST`, both off by default (measured: `V="a b"` unquoted still arrives as one argument), but so the same line survives a `bash` runner, where an unquoted path holding a space does split — measured, `fatal: path 'has' does not exist`.
244
+
245
+ ## Two refuters approved changes that could not both land
246
+
247
+ `review-and-fix.md`'s **Scan the findings against each other for MUTUAL EXCLUSION** rests on this. Two runs produced it; in one, a refuter proved a variable collapse behavior-equivalent over 844 cases while its own blast-radius scan named the two comment blocks a *different* refuter had just established as guarding distinct pinned hazards.
248
+
249
+ ## What a comment's false claim cost
250
+
251
+ `review-and-fix.md`'s **Comments are findings** rests on this. One run shipped five: an invented citation, a mis-stated failure mode, a test file named as covering what it had zero coverage of, an overstated cast fix, a claim its own dependency's source contradicts.