@feigi/fleet-ctl 3.35.10 → 3.36.1

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.
@@ -95,13 +95,14 @@ repository, with no per-member address for it — so this prohibition is the
95
95
  whole of the protection, not a stopgap standing in for one.
96
96
 
97
97
  **Every scratch file, fixture or mutation copy you create goes under
98
- `<scratch>/impl-<N>/`, never into the scratch root by itself.** The scratchpad
99
- root your own system prompt names is injected unprompted into every dispatched
100
- member and is shared with every sibling running this session — `SKILL.md` does
101
- not choose that root and cannot keep it from being handed to you, so writing to
102
- it directly, not a subdir under it, is the defect. Derive your own path the
103
- same way `claim-ticket.sh` already derives per-ticket ports from the issue
104
- number (`postgres=16<N>`, `ollama=22<N>`): `<scratch>/impl-<N>/`, not a second
98
+ `<scratch>/impl-<N>/`, never into the scratch root by itself.** Your dispatch
99
+ prompt names your partition with an absolute path, and no harness supplies one:
100
+ the root above it is shared with every sibling running this session, so writing
101
+ to it directly, not into your own subdirectory, is the defect. Never build a
102
+ root of your own — if your prompt names no path, ask the controller by name and
103
+ never invent one. Your partition is `<scratch>/impl-<N>/`, shaped the same
104
+ way `claim-ticket.sh` already derives per-ticket ports from the issue
105
+ number (`postgres=16<N>`, `ollama=22<N>`), not a second
105
106
  scheme, and `mkdir -p` it yourself the first time — nothing creates it for you.
106
107
  The harm is a false measurement, not untidiness: a mutation harness writes a
107
108
  broken copy of a file, measures against it, then restores from `.orig`, and
@@ -122,8 +123,8 @@ which can carry spaces and `/` and would split or nest the path in an
122
123
  unquoted shell command — unique among your children and never one of your
123
124
  own entries (`probe`, `mutate`, or any other name you write under
124
125
  `<scratch>/impl-<N>/` yourself), so no child shares a directory with a
125
- sibling or with you. A child left to derive its own path has only the
126
- injected root above to derive it from, which is this block's collision one
126
+ sibling or with you. A child left to derive its own path has no root to
127
+ derive it from but a guess, which is this block's collision one
127
128
  level down — and its files under your partition are what show the controller
128
129
  you are alive while you wait on it.
129
130
 
@@ -95,13 +95,14 @@ repository, with no per-member address for it — so this prohibition is the
95
95
  whole of the protection, not a stopgap standing in for one.
96
96
 
97
97
  **Every scratch file, fixture or mutation copy you create goes under
98
- `<scratch>/impl-<N>/`, never into the scratch root by itself.** The scratchpad
99
- root your own system prompt names is injected unprompted into every dispatched
100
- member and is shared with every sibling running this session — `SKILL.md` does
101
- not choose that root and cannot keep it from being handed to you, so writing to
102
- it directly, not a subdir under it, is the defect. Derive your own path the
103
- same way `claim-ticket.sh` already derives per-ticket ports from the issue
104
- number (`postgres=16<N>`, `ollama=22<N>`): `<scratch>/impl-<N>/`, not a second
98
+ `<scratch>/impl-<N>/`, never into the scratch root by itself.** Your dispatch
99
+ prompt names your partition with an absolute path, and no harness supplies one:
100
+ the root above it is shared with every sibling running this session, so writing
101
+ to it directly, not into your own subdirectory, is the defect. Never build a
102
+ root of your own — if your prompt names no path, ask the controller by name and
103
+ never invent one. Your partition is `<scratch>/impl-<N>/`, shaped the same
104
+ way `claim-ticket.sh` already derives per-ticket ports from the issue
105
+ number (`postgres=16<N>`, `ollama=22<N>`), not a second
105
106
  scheme, and `mkdir -p` it yourself the first time — nothing creates it for you.
106
107
  The harm is a false measurement, not untidiness: a mutation harness writes a
107
108
  broken copy of a file, measures against it, then restores from `.orig`, and
@@ -122,8 +123,8 @@ which can carry spaces and `/` and would split or nest the path in an
122
123
  unquoted shell command — unique among your children and never one of your
123
124
  own entries (`probe`, `mutate`, or any other name you write under
124
125
  `<scratch>/impl-<N>/` yourself), so no child shares a directory with a
125
- sibling or with you. A child left to derive its own path has only the
126
- injected root above to derive it from, which is this block's collision one
126
+ sibling or with you. A child left to derive its own path has no root to
127
+ derive it from but a guess, which is this block's collision one
127
128
  level down — and its files under your partition are what show the controller
128
129
  you are alive while you wait on it.
129
130
 
@@ -95,13 +95,14 @@ repository, with no per-member address for it — so this prohibition is the
95
95
  whole of the protection, not a stopgap standing in for one.
96
96
 
97
97
  **Every scratch file, fixture or mutation copy you create goes under
98
- `<scratch>/impl-<N>/`, never into the scratch root by itself.** The scratchpad
99
- root your own system prompt names is injected unprompted into every dispatched
100
- member and is shared with every sibling running this session — `SKILL.md` does
101
- not choose that root and cannot keep it from being handed to you, so writing to
102
- it directly, not a subdir under it, is the defect. Derive your own path the
103
- same way `claim-ticket.sh` already derives per-ticket ports from the issue
104
- number (`postgres=16<N>`, `ollama=22<N>`): `<scratch>/impl-<N>/`, not a second
98
+ `<scratch>/impl-<N>/`, never into the scratch root by itself.** Your dispatch
99
+ prompt names your partition with an absolute path, and no harness supplies one:
100
+ the root above it is shared with every sibling running this session, so writing
101
+ to it directly, not into your own subdirectory, is the defect. Never build a
102
+ root of your own — if your prompt names no path, ask the controller by name and
103
+ never invent one. Your partition is `<scratch>/impl-<N>/`, shaped the same
104
+ way `claim-ticket.sh` already derives per-ticket ports from the issue
105
+ number (`postgres=16<N>`, `ollama=22<N>`), not a second
105
106
  scheme, and `mkdir -p` it yourself the first time — nothing creates it for you.
106
107
  The harm is a false measurement, not untidiness: a mutation harness writes a
107
108
  broken copy of a file, measures against it, then restores from `.orig`, and
@@ -122,8 +123,8 @@ which can carry spaces and `/` and would split or nest the path in an
122
123
  unquoted shell command — unique among your children and never one of your
123
124
  own entries (`probe`, `mutate`, or any other name you write under
124
125
  `<scratch>/impl-<N>/` yourself), so no child shares a directory with a
125
- sibling or with you. A child left to derive its own path has only the
126
- injected root above to derive it from, which is this block's collision one
126
+ sibling or with you. A child left to derive its own path has no root to
127
+ derive it from but a guess, which is this block's collision one
127
128
  level down — and its files under your partition are what show the controller
128
129
  you are alive while you wait on it.
129
130
 
@@ -95,13 +95,14 @@ repository, with no per-member address for it — so this prohibition is the
95
95
  whole of the protection, not a stopgap standing in for one.
96
96
 
97
97
  **Every scratch file, fixture or mutation copy you create goes under
98
- `<scratch>/impl-<N>/`, never into the scratch root by itself.** The scratchpad
99
- root your own system prompt names is injected unprompted into every dispatched
100
- member and is shared with every sibling running this session — `SKILL.md` does
101
- not choose that root and cannot keep it from being handed to you, so writing to
102
- it directly, not a subdir under it, is the defect. Derive your own path the
103
- same way `claim-ticket.sh` already derives per-ticket ports from the issue
104
- number (`postgres=16<N>`, `ollama=22<N>`): `<scratch>/impl-<N>/`, not a second
98
+ `<scratch>/impl-<N>/`, never into the scratch root by itself.** Your dispatch
99
+ prompt names your partition with an absolute path, and no harness supplies one:
100
+ the root above it is shared with every sibling running this session, so writing
101
+ to it directly, not into your own subdirectory, is the defect. Never build a
102
+ root of your own — if your prompt names no path, ask the controller by name and
103
+ never invent one. Your partition is `<scratch>/impl-<N>/`, shaped the same
104
+ way `claim-ticket.sh` already derives per-ticket ports from the issue
105
+ number (`postgres=16<N>`, `ollama=22<N>`), not a second
105
106
  scheme, and `mkdir -p` it yourself the first time — nothing creates it for you.
106
107
  The harm is a false measurement, not untidiness: a mutation harness writes a
107
108
  broken copy of a file, measures against it, then restores from `.orig`, and
@@ -122,8 +123,8 @@ which can carry spaces and `/` and would split or nest the path in an
122
123
  unquoted shell command — unique among your children and never one of your
123
124
  own entries (`probe`, `mutate`, or any other name you write under
124
125
  `<scratch>/impl-<N>/` yourself), so no child shares a directory with a
125
- sibling or with you. A child left to derive its own path has only the
126
- injected root above to derive it from, which is this block's collision one
126
+ sibling or with you. A child left to derive its own path has no root to
127
+ derive it from but a guess, which is this block's collision one
127
128
  level down — and its files under your partition are what show the controller
128
129
  you are alive while you wait on it.
129
130
 
@@ -95,13 +95,14 @@ repository, with no per-member address for it — so this prohibition is the
95
95
  whole of the protection, not a stopgap standing in for one.
96
96
 
97
97
  **Every scratch file, fixture or mutation copy you create goes under
98
- `<scratch>/impl-<N>/`, never into the scratch root by itself.** The scratchpad
99
- root your own system prompt names is injected unprompted into every dispatched
100
- member and is shared with every sibling running this session — `SKILL.md` does
101
- not choose that root and cannot keep it from being handed to you, so writing to
102
- it directly, not a subdir under it, is the defect. Derive your own path the
103
- same way `claim-ticket.sh` already derives per-ticket ports from the issue
104
- number (`postgres=16<N>`, `ollama=22<N>`): `<scratch>/impl-<N>/`, not a second
98
+ `<scratch>/impl-<N>/`, never into the scratch root by itself.** Your dispatch
99
+ prompt names your partition with an absolute path, and no harness supplies one:
100
+ the root above it is shared with every sibling running this session, so writing
101
+ to it directly, not into your own subdirectory, is the defect. Never build a
102
+ root of your own — if your prompt names no path, ask the controller by name and
103
+ never invent one. Your partition is `<scratch>/impl-<N>/`, shaped the same
104
+ way `claim-ticket.sh` already derives per-ticket ports from the issue
105
+ number (`postgres=16<N>`, `ollama=22<N>`), not a second
105
106
  scheme, and `mkdir -p` it yourself the first time — nothing creates it for you.
106
107
  The harm is a false measurement, not untidiness: a mutation harness writes a
107
108
  broken copy of a file, measures against it, then restores from `.orig`, and
@@ -122,8 +123,8 @@ which can carry spaces and `/` and would split or nest the path in an
122
123
  unquoted shell command — unique among your children and never one of your
123
124
  own entries (`probe`, `mutate`, or any other name you write under
124
125
  `<scratch>/impl-<N>/` yourself), so no child shares a directory with a
125
- sibling or with you. A child left to derive its own path has only the
126
- injected root above to derive it from, which is this block's collision one
126
+ sibling or with you. A child left to derive its own path has no root to
127
+ derive it from but a guess, which is this block's collision one
127
128
  level down — and its files under your partition are what show the controller
128
129
  you are alive while you wait on it.
129
130
 
@@ -13,7 +13,9 @@ how it is built and tested. You decide by reading; a script proves what you
13
13
  decided; nothing is cached on a guess.
14
14
 
15
15
  Your dispatch prompt gives you `<repo>` (the repository's main checkout, an
16
- absolute path) and `<scratch>` (a directory that is yours alone). Read files
16
+ absolute path) and `<scratch>` (a directory that is yours alone, an absolute
17
+ path; standalone, with no dispatcher, it is `<root>/derive-recipe/` with
18
+ `<root>` what `~/.fleet/bin/fleet-run scratch-root.mjs` prints). Read files
17
19
  under `<repo>`; write only under `<scratch>`. **Never edit, create or delete a
18
20
  file under `<repo>`, and never write `.fleet/recipe.json` yourself** — the
19
21
  proof below is the cache's only writer, and it writes only on proof.
@@ -3,12 +3,14 @@ description: review a PR, apply recommended actions, push, watch checks until gr
3
3
  argument-hint: [pr-number]
4
4
  ---
5
5
 
6
+ `<scratch>` below is the absolute path your dispatch prompt names. Run standalone, with no dispatcher, it is what `~/.fleet/bin/fleet-run scratch-root.mjs` prints — never a directory you pick.
7
+
6
8
  1. Run the review yourself. **Dispatched as a fix-applier, skip this step**: the review already ran, and its result came with your prompt — see **The review result file**, which also holds the rulings on it that are yours to make. Re-running it re-reviews a PR nobody asked you to review. Otherwise — no `eval` access at your level — hand-dispatch the six `fleet-review-*` specialists yourself, by name:
7
9
 
8
10
  `fleet-review-<key>` (e.g. `fleet-review-correctness`).
9
11
 
10
12
  See **Specialists** — those constraints are not optional.
11
- 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. Out of the PR's ticket scope → defer and file. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the repository, and a fresh scratch dir's `fatal: not a git repository` (exit 128) is the pass, not a failure; before any `git commit` it must resolve to your scratch path — compare resolved forms (`realpath`), since `--show-toplevel` can report `/private/tmp/…` for a `/tmp` scratch dir on macOS.* 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. "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.**
13
+ 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. Out of the PR's ticket scope → defer and file. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. "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.**
12
14
  **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` (an in-scope suggestion's refuter verdict file) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to a human instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher, and nothing retries it; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the closed suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
13
15
  3. **Run `testCmd` before you commit**, from the worktree, copied verbatim — not a runner you picked. `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you one, it is the repo's own test command**, the Test entrypoint in the repo's Recipe cache (`derive-testcmd.sh <repo> test` prints it). Read it off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no usable Recipe cache (`derive-testcmd.sh` refuses), run the Recipe derivation step first — dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it proves both commands in a throwaway worktree and writes the cache only on proof, and its `RECIPE NOT PROVEN` is a stop, reported with its reason. Never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `git push origin HEAD:<branch>`, the explicit refspec: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`) and any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`) — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Measured twice in one run — one body kept asserting a calibration its own fix had just deleted as false, another kept claiming a hunk the fix had removed as "this diff owns it" — both caught by a finisher's reading rather than by any rule, and both would otherwise have merged intact. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify`.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
14
16
  4. **Under the fleet, do not hold this wait.** The controller owns a persistent CI Monitor and dispatches a finisher once your report has arrived and CI is green — so push, then report to the controller a **final verdict** (every specialist you dispatched + its outcome + your apply/defer adjudication + the pushed SHA) and stop. A specialist that has neither reported nor been relayed to you is not a verdict line — ask the controller for it by name before ruling; see **Specialists**. The controller keys "review complete" on that verdict, **never on you merely going idle** — a slow specialist can still be running when your turn ends, and finishing off idle-alone ships a premature label (observed: a PR labelled while its contract-test specialist was still running and about to surface a vacuous pin). A turn-based reviewer re-reading `gh pr checks` each idle cycle rebuilds its whole context for nothing the Monitor lacks. **Standalone (no controller): watch** the run until the diff-validating jobs are green (bind via `ci-state.mjs` below); fix a **genuine** failure and repeat from 3. **Staleness is not a failure:** a `rebase-check` red or heavy jobs `skipped` **solely from a non-zero behind-count** never clears by waiting and must not be rebased away here — see **`skipped` is not `passed`** and **Do NOT rebase to label** below for what it looks like and why. Stop watching and go to 6. A turn-based reviewer that "waits for green" on a behind PR stalls forever and ends its turn without labelling. **`ci-state.mjs` returns `verdict: "no-ci"`** → there is no run to watch, so don't: go straight to 6 and let that step's `--declare-no-ci` branch decide.
@@ -226,7 +226,7 @@ For each labeled PR clearing the hold rule, lowest first:
226
226
  --out <scratch>/pr<N>/merge-bot-<n>/ci.json; rc=$?
227
227
  ```
228
228
 
229
- `--pre` is the head you recorded at **The labelled head**; `--post` is the head step 1's rebase produced — omit it when no rebase ran, which is the same as passing `pre` twice. `pr<N>` is this PR and `merge-bot-<n>` is your own name, so the reading lands under a directory only you write, never in the scratch root by itself: that root is injected into every dispatched member and shared with every sibling. The gate is read-only — it runs the instrument re-check, `gh pr view <pr> --json labels,reviewDecision,headRefOid,body`, the main-gain check against that head in the main checkout, the rebase-carry proof when that head is neither `pre` nor `post`, and `ci-state.mjs --pr <pr>`, answers their conjunction, and never merges, labels, rebases or waits. Stdout is exactly one JSON line, `{pr, verdict, reason, head, pre, post, rebaseCarry, behind, instruments, mainGain, ci}`; stderr is its children's diagnostics, so never fold `2>&1` into the line you read. Read `rc` straight off the call, as above — never through a pipe.
229
+ `--pre` is the head you recorded at **The labelled head**; `--post` is the head step 1's rebase produced — omit it when no rebase ran, which is the same as passing `pre` twice. `pr<N>` is this PR and `merge-bot-<n>` is your own name, so the reading lands under a directory only you write, never in the scratch root by itself: `<scratch>` is the absolute path your dispatch prompt names, and that root is shared with every sibling. The gate is read-only — it runs the instrument re-check, `gh pr view <pr> --json labels,reviewDecision,headRefOid,body`, the main-gain check against that head in the main checkout, the rebase-carry proof when that head is neither `pre` nor `post`, and `ci-state.mjs --pr <pr>`, answers their conjunction, and never merges, labels, rebases or waits. Stdout is exactly one JSON line, `{pr, verdict, reason, head, pre, post, rebaseCarry, behind, instruments, mainGain, ci}`; stderr is its children's diagnostics, so never fold `2>&1` into the line you read. Read `rc` straight off the call, as above — never through a pipe.
230
230
 
231
231
  **Run a plain `git fetch origin` in the main checkout before every gate run** — never `git fetch origin <src>:<dst>`, for the reason step 1's fallback gives. The main-gain check and the rebase-carry proof read `origin/main` and the head objects there as they stand and fetch nothing themselves: an unfetched head is `main-gain-unanswerable`, an unheld labelled or carried head is no carry, and a stale `origin/main` is a check against the wrong `main`.
232
232
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.35.10",
3
+ "version": "3.36.1",
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": {
@@ -368,16 +368,25 @@ esac
368
368
  # `tests 0` and exits 0. The suite moved and the Recipe did not, so it is
369
369
  # stale, refused like a binary that is gone. Tracked, not present on disk: a
370
370
  # fresh worktree holds only what is tracked. Only a word the shell globs as
371
- # written, from <repo>, can be settled without running the command. A word
372
- # carrying quoting or an expansion is accepted unprobed, whole, since an
373
- # operator in it may be quoted; any other word is split at each `;`, `&`, `|`,
374
- # `(` and `)`, operators to the shell whether or not whitespace surrounds
375
- # them, and each piece is judged as a word of its own. An option, an `=`
371
+ # written, from <repo>, can be settled without running the command. The scan
372
+ # reads the whole command one character at a time under one rule: a region
373
+ # inside `'…'`, `"…"`, backticks, `$(…)` or `${…}`, or a `\`-escaped byte, is
374
+ # opaque, and makes the piece it belongs to quoted or expansion-bearing,
375
+ # accepted unprobed whole; so does a `{`, `}`, `~` or bare `$`. Inside a `$(…)`
376
+ # or a `${…}` the quotes and the substitutions are read as the shell reads
377
+ # them, so a quoted `)` or `}` closes nothing, and a `"…"` holds substitutions
378
+ # of its own. A backslash and a newline together are removed before the shell
379
+ # splits words, so they quote nothing and end nothing. An unquoted `;`, `&`,
380
+ # `|`, `(`, `)`, `<` or `>` is an operator to the shell whether or not
381
+ # whitespace surrounds it, and an unquoted blank ends a piece: each piece is
382
+ # judged as a word of its own. A quote, a backtick or a `$(` or `${` still open
383
+ # at the end of the command is refused: `sh -c` dies on it, so it is a Recipe
384
+ # that cannot run. An option, an `=`
376
385
  # assignment or value, a path outside <repo>, or the target of a `<` or `>`
377
386
  # redirection is the program's own to read, or selects no test, and is
378
- # accepted unprobed too. The scan stops at a `cd` or `pushd`, past which a
379
- # pattern no longer resolves from <repo>, and at a word that is not split but
380
- # ends in an operator then `cd` or `pushd`. A program's own directory option,
387
+ # accepted unprobed too. The scan stops judging at a `cd` or `pushd` piece,
388
+ # past which a pattern no longer resolves from <repo>.
389
+ # A program's own directory option,
381
390
  # such as `git -C`, does not stop it: whether that option moves where the
382
391
  # program resolves a pattern is the program's to say, so a Recipe must quote a
383
392
  # pattern that a program resolves under its own directory option, as in
@@ -428,71 +437,154 @@ if [ "$field" = test ]; then
428
437
  esac
429
438
  done; exit 1; }
430
439
  }
431
- set -f
432
- prev=
433
- # shellcheck disable=SC2086 # field splitting is the point: scanning every word
434
- for word in $value; do
435
- case $word in
436
- *[\'\"\\\$\`\{\}\~]*)
437
- case $word in *[\(\;\&\|]cd|*[\(\;\&\|]pushd) break ;; esac
438
- prev=$word
439
- continue ;;
440
+ # Judge one piece of the command: $1 is `P` (plain: the shell globs it as
441
+ # written) or `Q` (quoted or expansion-bearing: opaque), $2 the piece. Dies
442
+ # on a stale pattern; otherwise returns 0 having accepted the piece.
443
+ judge() {
444
+ [ -z "$stop" ] || return 0
445
+ piece=$2
446
+ was=$before
447
+ before=$piece
448
+ if [ -n "$redir" ]; then redir=; return 0; fi
449
+ [ "$1" = P ] || return 0
450
+ case $piece in
451
+ cd|pushd) stop=1; return 0 ;;
452
+ -*|*=*|/*|*..*) return 0 ;;
453
+ *'*'*|*'?'*|*'['*']'*) ;;
454
+ *) return 0 ;;
455
+ esac
456
+ case $was in
457
+ -*=*) ;;
458
+ -*) case $piece in */*|*.*) ;; *) return 0 ;; esac ;;
440
459
  esac
441
- before=$prev
442
- rest=$word
443
- first=1
460
+ # The second pathspec is the directories the piece matches: the shell
461
+ # hands `tests/*` the directory `tests/unit`, which ls-files lists only as
462
+ # the prefix of the files beneath it.
463
+ tracked=$(git -C "$repo" ls-files -- ":(glob)$piece" ":(glob)${piece%/}/**" 2>"$errf") || {
464
+ listed=$?
465
+ die "cannot list the files tracked in $where to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)"
466
+ }
467
+ [ -z "$tracked" ] || return 0
468
+ lead=${piece%%[*?[]*}
444
469
  while :; do
445
- if [ -z "$first" ]; then
446
- case $rest in
447
- *[\;\&\|\(\)]*) rest=${rest#*[\;\&\|\(\)]} ;;
448
- *) break ;;
449
- esac
450
- before=
451
- fi
452
- first=
453
- piece=${rest%%[\;\&\|\(\)]*}
454
- follows=$prev
455
- prev=$piece
456
- case $follows in *[\<\>]) continue ;; esac
457
- case $piece in
458
- cd|pushd) break 2 ;;
459
- -*|*=*|/*|*..*|*[\<\>]*) continue ;;
460
- *'*'*|*'?'*|*'['*']'*) ;;
461
- *) continue ;;
462
- esac
463
- case $before in
464
- -*=*) ;;
465
- -*) case $piece in */*|*.*) ;; *) continue ;; esac ;;
466
- esac
467
- # The second pathspec is the directories the piece matches: the shell
468
- # hands `tests/*` the directory `tests/unit`, which ls-files lists only as
469
- # the prefix of the files beneath it.
470
- tracked=$(git -C "$repo" ls-files -- ":(glob)$piece" ":(glob)${piece%/}/**" 2>"$errf") || {
471
- listed=$?
472
- die "cannot list the files tracked in $where to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)"
473
- }
474
- [ -z "$tracked" ] || continue
475
- lead=${piece%%[*?[]*}
476
- while :; do
477
- case $lead in */*) lead=${lead%/*} ;; *) break ;; esac
478
- opq=0
479
- opaque "$lead" || opq=$?
480
- case $opq in
481
- 0) continue 2 ;;
482
- 1) ;;
483
- *) die "cannot ask git whether '$lead' is a symlink or a submodule in $where, to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)" ;;
484
- esac
485
- done
486
- ignored=0
487
- git -C "$repo" check-ignore -q --no-index -- "$piece" 2>"$errf" || ignored=$?
488
- case $ignored in
489
- 0) ;;
490
- 1) die "the Recipe cache at $cache is invalid: its test command's pattern '$piece' matches no file tracked in $where — a Test entrypoint that selects no tests passes having run nothing, so the Recipe is stale, not a finding; a pattern that a program resolves under its own directory option, such as git -C, must be quoted; $derive" ;;
491
- *) die "cannot ask git whether $repo ignores its test command's pattern '$piece' (git check-ignore exit $ignored): $(cat "$errf" 2>/dev/null)" ;;
470
+ case $lead in */*) lead=${lead%/*} ;; *) break ;; esac
471
+ opq=0
472
+ opaque "$lead" || opq=$?
473
+ case $opq in
474
+ 0) return 0 ;;
475
+ 1) ;;
476
+ *) die "cannot ask git whether '$lead' is a symlink or a submodule in $where, to check its test command's pattern '$piece' (git ls-files exit $listed): $(cat "$errf" 2>/dev/null)" ;;
492
477
  esac
493
478
  done
479
+ ignored=0
480
+ git -C "$repo" check-ignore -q --no-index -- "$piece" 2>"$errf" || ignored=$?
481
+ case $ignored in
482
+ 0) ;;
483
+ 1) die "the Recipe cache at $cache is invalid: its test command's pattern '$piece' matches no file tracked in $where — a Test entrypoint that selects no tests passes having run nothing, so the Recipe is stale, not a finding; a pattern that a program resolves under its own directory option, such as git -C, must be quoted; $derive" ;;
484
+ *) die "cannot ask git whether $repo ignores its test command's pattern '$piece' (git check-ignore exit $ignored): $(cat "$errf" 2>/dev/null)" ;;
485
+ esac
486
+ }
487
+ # End the piece being read, if there is one, and judge it.
488
+ flush() {
489
+ if [ -n "$scan_piece" ]; then judge "$scan_kind" "$scan_piece"; fi
490
+ scan_piece=
491
+ scan_kind=P
492
+ }
493
+ nl='
494
+ '
495
+ before=
496
+ redir=
497
+ stop=
498
+ scan_rest=$value
499
+ scan_piece=
500
+ scan_kind=P
501
+ scan_sq=
502
+ scan_ctx=
503
+ scan_top=
504
+ # The regions open around the scan point, innermost first: `"` a double
505
+ # quote, a backtick, `(` a `$(`, `{` a `${`. A single quote holds nothing
506
+ # inside it, so it is a flag, not a region.
507
+ scan_push() {
508
+ scan_ctx=$1$scan_ctx
509
+ scan_top=$1
510
+ }
511
+ scan_pop() {
512
+ scan_ctx=${scan_ctx#?}
513
+ scan_top=${scan_ctx%"${scan_ctx#?}"}
514
+ }
515
+ # After a `$` already read: a `(` or `{` right behind it opens a region.
516
+ scan_dollar() {
517
+ case $scan_rest in
518
+ '('*) scan_push '('; scan_piece=$scan_piece'('; scan_rest=${scan_rest#?} ;;
519
+ '{'*) scan_push '{'; scan_piece=$scan_piece'{'; scan_rest=${scan_rest#?} ;;
520
+ esac
521
+ }
522
+ while [ -n "$scan_rest" ]; do
523
+ scan_c=${scan_rest%"${scan_rest#?}"}
524
+ scan_rest=${scan_rest#?}
525
+ if [ -n "$scan_sq" ]; then
526
+ scan_piece=$scan_piece$scan_c
527
+ if [ "$scan_c" = "'" ]; then scan_sq=; fi
528
+ continue
529
+ fi
530
+ if [ "$scan_c" = '\' ]; then
531
+ scan_next=${scan_rest%"${scan_rest#?}"}
532
+ scan_rest=${scan_rest#?}
533
+ # A backslash and a newline are removed before the shell splits words:
534
+ # they quote nothing and end nothing.
535
+ if [ "$scan_next" = "$nl" ]; then continue; fi
536
+ scan_piece=$scan_piece$scan_c$scan_next
537
+ scan_kind=Q
538
+ continue
539
+ fi
540
+ case $scan_top in
541
+ '"')
542
+ scan_piece=$scan_piece$scan_c
543
+ case $scan_c in
544
+ '"') scan_pop ;;
545
+ '`') scan_push '`' ;;
546
+ '$') scan_dollar ;;
547
+ esac
548
+ continue ;;
549
+ '`')
550
+ scan_piece=$scan_piece$scan_c
551
+ if [ "$scan_c" = '`' ]; then scan_pop; fi
552
+ continue ;;
553
+ '('|'{')
554
+ scan_piece=$scan_piece$scan_c
555
+ case $scan_c in
556
+ "'") scan_sq=1 ;;
557
+ '"') scan_push '"' ;;
558
+ '`') scan_push '`' ;;
559
+ '$') scan_dollar ;;
560
+ '(') if [ "$scan_top" = '(' ]; then scan_push '('; fi ;;
561
+ ')') if [ "$scan_top" = '(' ]; then scan_pop; fi ;;
562
+ '{') if [ "$scan_top" = '{' ]; then scan_push '{'; fi ;;
563
+ '}') if [ "$scan_top" = '{' ]; then scan_pop; fi ;;
564
+ esac
565
+ continue ;;
566
+ esac
567
+ case $scan_c in
568
+ "'") scan_sq=1; scan_kind=Q; scan_piece=$scan_piece$scan_c ;;
569
+ '"') scan_push '"'; scan_kind=Q; scan_piece=$scan_piece$scan_c ;;
570
+ '`') scan_push '`'; scan_kind=Q; scan_piece=$scan_piece$scan_c ;;
571
+ '$')
572
+ scan_kind=Q
573
+ scan_piece=$scan_piece$scan_c
574
+ scan_dollar ;;
575
+ '{'|'}'|'~') scan_kind=Q; scan_piece=$scan_piece$scan_c ;;
576
+ ' '|' '|"$nl") flush ;;
577
+ ';'|'&'|'|'|'('|')'|'<'|'>')
578
+ flush
579
+ before=
580
+ case $scan_c in '<'|'>') redir=1 ;; esac ;;
581
+ *) scan_piece=$scan_piece$scan_c ;;
582
+ esac
494
583
  done
495
- set +f
584
+ flush
585
+ if [ -n "$scan_sq" ] || [ -n "$scan_ctx" ]; then
586
+ die "the Recipe cache at $cache is invalid: its test command leaves a quote, a backtick, a \$( or a \${ open, so sh cannot run it — a Recipe that cannot run is stale, not a finding; $derive"
587
+ fi
496
588
  fi
497
589
 
498
590
  printf '%s\n' "$value"
@@ -20,10 +20,18 @@
20
20
  // on its base port — and each says so in its own words around this error's
21
21
  // message, which names what failed.
22
22
  //
23
+ // The same workspace answer keys the run's scratch root, scratchRoot() below:
24
+ // ONE fixed root per repository under the user's home, computed and never
25
+ // recorded, so a re-invoked controller and every standalone entry point land
26
+ // on the same path. scratch-root.mjs is its CLI.
27
+ //
23
28
  // Zero deps: node builtins and sibling scripts only.
24
29
 
25
30
  import { spawnSync } from "node:child_process";
26
- import { join } from "node:path";
31
+ import { createHash } from "node:crypto";
32
+ import { existsSync } from "node:fs";
33
+ import { homedir } from "node:os";
34
+ import { basename, dirname, join } from "node:path";
27
35
  import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
28
36
 
29
37
  // A `rev-parse` answers in milliseconds; this bound exists so a git that
@@ -36,6 +44,10 @@ const DEFAULT_GIT_TIMEOUT_MS = 10_000;
36
44
  // keeping the END — the part of a child's stderr that says why it stopped.
37
45
  const CAUSE_MAX = 500;
38
46
 
47
+ // What `git rev-parse --show-toplevel` says (exit 128, under LC_ALL=C) outside
48
+ // a work tree: no repository at all, or one with no work tree to name.
49
+ const NOT_A_WORK_TREE = /not a git repository|must be run in a work tree/;
50
+
39
51
  export class FleetDirUnresolvable extends Error {
40
52
  constructor(message) {
41
53
  super(message);
@@ -93,3 +105,74 @@ export function fleetFile(name, { cwd = process.cwd(), timeoutMs, canonicalise =
93
105
  }
94
106
  return name === null ? join(workspace, ".fleet") : join(workspace, ".fleet", name);
95
107
  }
108
+
109
+ /**
110
+ * The scratch root of this run's repository: `~/.fleet/scratch/<repo-key>/`,
111
+ * COMPUTED here and never recorded or injected, so a compacted or re-invoked
112
+ * controller derives the same path again and so does any standalone entry
113
+ * point that has no dispatcher to name one.
114
+ *
115
+ * `<repo-key>` is `<basename>-<8 hex>`. `<basename>` is the folder name of the
116
+ * workspace — the directory holding the COMMON git dir, the same lookup
117
+ * fleetFile() makes, so a linked worktree maps to its main checkout — and the
118
+ * hex is the first 8 characters of the sha256 of that directory's realpath,
119
+ * so two clones that share a name get different roots. Both come from the
120
+ * canonical form, so a symlinked route to one workspace is not a second root.
121
+ *
122
+ * `home` exists for tests; it defaults to the user's home directory. Throws
123
+ * FleetDirUnresolvable exactly as fleetFile() does.
124
+ */
125
+ export function scratchRoot({ cwd = process.cwd(), timeoutMs, home = homedir() } = {}) {
126
+ const workspace = dirname(fleetFile(null, { cwd, timeoutMs, canonicalise: true }));
127
+ const hex = createHash("sha256").update(workspace).digest("hex").slice(0, 8);
128
+ return join(home, ".fleet", "scratch", `${basename(workspace)}-${hex}`);
129
+ }
130
+
131
+ function nearestExisting(path) {
132
+ let at = path;
133
+ while (!existsSync(at)) {
134
+ const up = dirname(at);
135
+ if (up === at) return at;
136
+ at = up;
137
+ }
138
+ return at;
139
+ }
140
+
141
+ /**
142
+ * Why `root` may not be used as a scratch root, or `null` when it may.
143
+ *
144
+ * A root inside a git work tree is refused unless `git check-ignore` says that
145
+ * work tree ignores it: scratch inside a tree that does not ignore it is the
146
+ * write into a repository the scratch discipline exists to prevent (`git add
147
+ * -A` there stages it). The main checkout is held to the same rule: a write
148
+ * into it is refused unless `git check-ignore` says the path is ignored. A root
149
+ * under an OUTER repository whose ignore rules cover it passes — a dotfiles
150
+ * `$HOME` that ignores `.fleet/` is an ordinary setup.
151
+ *
152
+ * Asked before the root exists, from its nearest existing ancestor: refusing
153
+ * must not create a directory inside the repository it refuses. The trailing
154
+ * slash makes a directory-only ignore pattern (`.fleet/`) match a path that is
155
+ * not on disk yet.
156
+ */
157
+ export function scratchRootRefusal(root, { timeoutMs } = {}) {
158
+ const cwd = nearestExisting(root);
159
+ // LC_ALL=C: the not-a-work-tree answer below is read off git's own words, so
160
+ // they must not arrive translated.
161
+ const opts = { cwd, encoding: "utf8", timeout: timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS, env: gitEnv({ LC_ALL: "C" }) };
162
+ const top = spawnSync("git", ["rev-parse", "--show-toplevel"], opts);
163
+ // Not in a work tree — no repository, a bare one, the inside of a `.git` —
164
+ // so there is no tree for scratch to dirty. That is git's own answer, read
165
+ // off its stderr: any other failure — a git that never ran, one killed by a
166
+ // signal, one that refused (`detected dubious ownership`) — says nothing
167
+ // about whether a work tree is there, and is refused below rather than read
168
+ // as that answer.
169
+ if (top.status !== 0 && !top.error && NOT_A_WORK_TREE.test(top.stderr)) return null;
170
+ if (top.error || top.status !== 0) {
171
+ return `could not ask git whether ${root} is inside a work tree: ${cause(top.error && top.error.message, top.stderr) || ended(top)}`;
172
+ }
173
+ const tree = top.stdout.trim();
174
+ const ignored = spawnSync("git", ["check-ignore", "-q", `${root}/`], opts);
175
+ if (ignored.status === 0) return null;
176
+ const why = ignored.status === 1 ? "which does not ignore it" : cause(ignored.error && ignored.error.message, ignored.stderr) || ended(ignored);
177
+ return `scratch root ${root} is inside the git work tree ${tree}, ${why} — scratch there would be staged by \`git add -A\``;
178
+ }
@@ -21,11 +21,17 @@
21
21
  // `null`, which every guard here — `if (snap) {...}`, `unrunCrashed`,
22
22
  // `verdictFor` — is written against).
23
23
  //
24
- // Two imports. arg.mjs's isDigits(): this file is an ordinary
24
+ // Three imports. arg.mjs's isDigits(): this file is an ordinary
25
25
  // module, so it consumes the repo's digits rule directly rather than
26
26
  // declaring its own copy. node:path's `posix`, to normalise a
27
27
  // scratch path before `runnerScratchRefusal` reads its last component, and
28
28
  // its `isAbsolute`, to refuse a scratch that is not an absolute path.
29
+ // fleet-dir.mjs's scratchRoot(), scratchRootRefusal() and FleetDirUnresolvable.
30
+ // scratchRoot() and FleetDirUnresolvable serve the one caller that passes no
31
+ // `scratch` at all — a standalone review with no dispatcher — which takes the
32
+ // fleet's own scratch root for this repository; scratchRootRefusal() vets every
33
+ // scratch, given or defaulted, against landing in a work tree that does not
34
+ // ignore it.
29
35
  //
30
36
  // `.mjs`, not `.js`: this file was once `review-core.js`, and
31
37
  // nothing that ships declares a `type`, so Node below 20.19.0/22.7.0 —
@@ -35,6 +41,7 @@
35
41
 
36
42
  import { isAbsolute, posix } from "node:path";
37
43
  import { isDigits } from "./arg.mjs";
44
+ import { FleetDirUnresolvable, scratchRoot, scratchRootRefusal } from "./fleet-dir.mjs";
38
45
 
39
46
  // --- Schemas ----------------------------------------------------------
40
47
  export const FINDINGS_SCHEMA = {
@@ -739,6 +746,23 @@ async function defaultPipeline(items, stage1, stage2) {
739
746
  );
740
747
  }
741
748
 
749
+ // A review dispatched by the controller is handed its scratch root; one run on
750
+ // its own (`/review-and-fix` with no dispatcher) resolves it the way
751
+ // scratch-root.mjs does, through the same functions, and is refused the same
752
+ // way when that root would sit inside a work tree that does not ignore it.
753
+ function standaloneScratchRoot() {
754
+ let root;
755
+ try {
756
+ root = scratchRoot();
757
+ } catch (e) {
758
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
759
+ throw new Error(`review-pr: no args.scratch, and the scratch root could not be resolved — ${e.message}`);
760
+ }
761
+ const refusal = scratchRootRefusal(root);
762
+ if (refusal !== null) throw new Error(`review-pr: no args.scratch, and ${refusal}`);
763
+ return root;
764
+ }
765
+
742
766
  export async function runReview(host, args) {
743
767
  const { agent, phase, log } = host;
744
768
  const pipeline = host.pipeline ?? defaultPipeline;
@@ -748,9 +772,6 @@ export async function runReview(host, args) {
748
772
  const pr = A.pr;
749
773
  const branch = A.branch;
750
774
  const worktree = A.worktree;
751
- const scratch = A.scratch === undefined ? `/tmp/review-pr-${pr}` : A.scratch;
752
- const runRootParent = `${scratch}/pr${pr}`;
753
- const runRootPrefix = `${runRootParent}/run-`;
754
775
  // Every dispatch label ends in `:pr${pr}`: the member id the harness derives
755
776
  // from a label is all a transcript keeps of it, and member-record.mjs's
756
777
  // parseMemberName reads the PR back out of that id to book its cost.
@@ -765,7 +786,7 @@ export async function runReview(host, args) {
765
786
  // passes all three — `gh` resolves a non-numeric ref as a BRANCH, so the
766
787
  // snapshot is a real diff belonging to whatever PR that branch heads while
767
788
  // every return value here still reports the string that was passed. It is
768
- // also a PATH component by then (`scratch`, `runRootParent` above), so a
789
+ // also a PATH component by then (`scratch`, `runRootParent` below), so a
769
790
  // value like `../x` names a run root outside the scratch tree.
770
791
  //
771
792
  // REFUSED, never coerced. `Number(pr)` would make a bad value the string
@@ -781,6 +802,12 @@ export async function runReview(host, args) {
781
802
  // into it: an absent `pr` is owed "required", not a complaint about digits.
782
803
  if (!isDigits(pr)) throw new Error(`review-pr: args.pr must be a PR number, got ${JSON.stringify(pr)}`);
783
804
 
805
+ // Resolved only now: the default spawns git, so a missing or malformed `pr`
806
+ // is refused on its own terms before anything is resolved or spawned.
807
+ const scratch = A.scratch === undefined ? standaloneScratchRoot() : A.scratch;
808
+ const runRootParent = `${scratch}/pr${pr}`;
809
+ const runRootPrefix = `${runRootParent}/run-`;
810
+
784
811
  const scratchRefusal = runnerScratchRefusal(scratch);
785
812
  if (scratchRefusal) throw new Error(`review-pr: ${scratchRefusal}`);
786
813
 
@@ -794,6 +821,15 @@ export async function runReview(host, args) {
794
821
  throw new Error(`review-pr: args.scratch must be an absolute path, got ${JSON.stringify(scratch)}`);
795
822
  }
796
823
 
824
+ // A given scratch is held to the same rule as the default: the controller
825
+ // hands over the path scratch-root.mjs vetted, but nothing on this side can
826
+ // tell that from a path inside a tracked tree, and `git add -A` there stages
827
+ // the run root. The default was already asked in standaloneScratchRoot().
828
+ if (A.scratch !== undefined) {
829
+ const rootRefusal = scratchRootRefusal(scratch);
830
+ if (rootRefusal !== null) throw new Error(`review-pr: args.scratch: ${rootRefusal}`);
831
+ }
832
+
797
833
  const explicitDimensions = resolveDimensions(A.dimensions, DEFAULT_DIMENSIONS);
798
834
 
799
835
  phase("Snapshot");
@@ -1062,11 +1098,13 @@ Scratch files go in ${snap.runRoot}/${d.key}/ and nowhere else. Chain the
1062
1098
  directory change into the command, \`cd "$D" && git …\`, never
1063
1099
  \`cd "$D"; git …\`, so a failed \`cd\` cannot leave a \`git\` command running in the
1064
1100
  checkout — and bracket a fixture's own git with \`git rev-parse --show-toplevel\`:
1065
- before \`git init\` it must NOT resolve to the repository, and a fresh scratch
1066
- dir's \`fatal: not a git repository\` (exit 128) is the pass, not a failure;
1067
- before any \`git commit\` it must resolve to your scratch path — compare
1068
- resolved forms (\`realpath\`), since \`--show-toplevel\` can report
1069
- \`/private/tmp/…\` for a \`/tmp\` scratch dir on macOS.
1101
+ before \`git init\` it must NOT resolve to the host repository, and
1102
+ \`fatal: not a git repository\` (exit 128) is the usual pass, not a failure — an
1103
+ outer repository whose ignore rules cover your scratch dir is a pass too;
1104
+ before any \`git commit\` it must resolve to your scratch path, which catches a
1105
+ forgotten \`git init\` under any enclosing repository — compare resolved forms
1106
+ (\`realpath\`), since \`--show-toplevel\` can report a symlinked parent such as
1107
+ \`/tmp\` or a symlinked \`$HOME\` under its resolved name.
1070
1108
 
1071
1109
  Report only what you RAN. A claim you reasoned to but did not execute belongs
1072
1110
  in 'suggestion', not 'critical'. State your search scope for every negative
@@ -1143,11 +1181,13 @@ an abstaining vote — an undecided run never defaults to refuted=true.
1143
1181
  Chain the directory change into the command, \`cd "$D" && git …\`, never
1144
1182
  \`cd "$D"; git …\`, so a failed \`cd\` cannot leave a \`git\` command running in the
1145
1183
  checkout — and bracket a fixture's own git with \`git rev-parse --show-toplevel\`:
1146
- before \`git init\` it must NOT resolve to the repository, and a fresh scratch
1147
- dir's \`fatal: not a git repository\` (exit 128) is the pass, not a failure;
1148
- before any \`git commit\` it must resolve to your scratch path — compare
1149
- resolved forms (\`realpath\`), since \`--show-toplevel\` can report
1150
- \`/private/tmp/…\` for a \`/tmp\` scratch dir on macOS.
1184
+ before \`git init\` it must NOT resolve to the host repository, and
1185
+ \`fatal: not a git repository\` (exit 128) is the usual pass, not a failure — an
1186
+ outer repository whose ignore rules cover your scratch dir is a pass too;
1187
+ before any \`git commit\` it must resolve to your scratch path, which catches a
1188
+ forgotten \`git init\` under any enclosing repository — compare resolved forms
1189
+ (\`realpath\`), since \`--show-toplevel\` can report a symlinked parent such as
1190
+ \`/tmp\` or a symlinked \`$HOME\` under its resolved name.
1151
1191
 
1152
1192
  A failure injection with no positive control has produced NO result, never a
1153
1193
  negative one. Before you read an injected fault — an env var, an argv word, a
@@ -0,0 +1,53 @@
1
+ #!/usr/bin/env node
2
+ // The fleet's scratch root for this repository, printed as an absolute path.
3
+ //
4
+ // scratch-root.mjs
5
+ //
6
+ // `~/.fleet/scratch/<repo-key>/`, computed by fleet-dir.mjs's scratchRoot() —
7
+ // the same path from the main checkout and from any linked worktree, a
8
+ // different one for a second clone with the same folder name. Nothing is
9
+ // written to `.fleet/` or anywhere else to record it: the controller (and any
10
+ // standalone entry point with no dispatcher) runs this again and gets the same
11
+ // answer. The controller writes the printed path, absolute, into the prompt of
12
+ // every member it dispatches; a member never runs this to build a root of its
13
+ // own.
14
+ //
15
+ // The root is created (`mkdir -p`) once it passes the refusal below.
16
+ //
17
+ // Exit 0: the path on stdout, nothing else. Exit 1: the root would sit inside
18
+ // a git work tree that does not ignore it — the reason, naming the work tree,
19
+ // on stderr, and nothing created. Exit 2: usage, no repository to key on, or the
20
+ // root could not be created (a filesystem fault, not a refusal).
21
+
22
+ import { mkdirSync } from "node:fs";
23
+ import { makeDie } from "./arg.mjs";
24
+ import { FleetDirUnresolvable, scratchRoot, scratchRootRefusal } from "./fleet-dir.mjs";
25
+ import { isCLI } from "./is-cli.mjs";
26
+
27
+ const NAME = "scratch-root";
28
+
29
+ function main() {
30
+ const die = makeDie(NAME);
31
+ if (process.argv.length > 2) die(`takes no arguments, got: ${process.argv.slice(2).join(" ")}`);
32
+ let root;
33
+ try {
34
+ root = scratchRoot();
35
+ } catch (e) {
36
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
37
+ die(e.message);
38
+ }
39
+ const refusal = scratchRootRefusal(root);
40
+ if (refusal !== null) {
41
+ process.stderr.write(`${NAME}: ${refusal}\n`);
42
+ process.exitCode = 1;
43
+ return;
44
+ }
45
+ try {
46
+ mkdirSync(root, { recursive: true });
47
+ } catch (e) {
48
+ die(`could not create ${root}: ${e.message}`);
49
+ }
50
+ process.stdout.write(`${root}\n`);
51
+ }
52
+
53
+ if (isCLI(import.meta.url)) main();
@@ -76,7 +76,7 @@ gh label create in-progress --color FBCA04 --force # first time only
76
76
  gh issue edit <N> --add-label in-progress
77
77
  ```
78
78
 
79
- Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, run the Install step, run the Test entrypoint as the baseline — both the repo's **Recipe**, read from its Recipe cache: `~/.fleet/bin/fleet-run derive-testcmd.sh . install` and `… . test --at origin/main` print them. **No usable cache (either exits 1) → 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 reads the repo, proves both commands in a throwaway worktree and writes the cache only on proof. `RECIPE NOT PROVEN` → stop and give the maintainer its reason; never pick a command yourself. Exit 3 is no verdict on the cache — the reader could not run a tool it needs — so fix that environment fault and re-run instead of deriving.
79
+ Infer branch/worktree convention from `git worktree list` / `git branch -r` — commonly `feat|fix|refactor/<N>-slug` and `.worktrees/<N>-slug`. Branch off fresh `origin/main`, run the Install step, run the Test entrypoint as the baseline — both the repo's **Recipe**, read from its Recipe cache: `~/.fleet/bin/fleet-run derive-testcmd.sh . install` and `… . test --at origin/main` print them. **No usable cache (either exits 1) → 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 `<scratch>/derive-recipe/` as its scratch directory, `<scratch>` the output of `~/.fleet/bin/fleet-run scratch-root.mjs`; it reads the repo, proves both commands in a throwaway worktree and writes the cache only on proof. `RECIPE NOT PROVEN` → stop and give the maintainer its reason; never pick a command yourself. Exit 3 is no verdict on the cache — the reader could not run a tool it needs — so fix that environment fault and re-run instead of deriving.
80
80
 
81
81
  Abandoned before PR opens → remove `in-progress`.
82
82
 
@@ -148,6 +148,24 @@ the poll it was waiting on was structurally incapable of firing. Say it in
148
148
  every dispatch prompt — this file is yours, not theirs, so a member learns
149
149
  it only if you write it into the prompt.
150
150
 
151
+ **The scratch root is computed, never invented and never recorded.** No harness
152
+ supplies a scratch directory to a member, so a member left to name its own
153
+ invents one — and the liveness read below, which looks at the files under the
154
+ directory a member's own prompt assigned it, then watches a directory nobody
155
+ else can find. You run `~/.fleet/bin/fleet-run scratch-root.mjs`: it prints one
156
+ absolute path, `~/.fleet/scratch/<repo-key>/`, the same from the main checkout
157
+ and from every linked worktree, and the same again when a compacted or
158
+ re-invoked controller runs it, so nothing writes it down. It exits non-zero,
159
+ with its reason, when the root would sit inside a git work tree that does not
160
+ ignore it; that is an environment to fix, not a cue to pick another root.
161
+ `<scratch>` in this file is that path, resolved before you send anything: every
162
+ prompt below that carries one carries the absolute path you wrote — an
163
+ implementer's `<scratch>/impl-<N>/`, the recipe deriver's
164
+ `<scratch>/derive-recipe/`, a fix-applier's, a finisher's and a merge bot's
165
+ `<scratch>/pr<N>/…`, and a review runner's `scratch` argument, which is the
166
+ root itself. A member whose prompt names no path asks you by name and never
167
+ makes one up.
168
+
151
169
  ## Shell traps
152
170
 
153
171
  Monitor and Bash commands run under **zsh**, and the shell in this file is
@@ -453,8 +471,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
453
471
  > scratch directory is `<scratch>/derive-recipe/`; write nowhere else.
454
472
  > Follow your definition's procedure exactly, and end with its report line.
455
473
 
456
- `<repo>` is this main checkout's absolute path and `<scratch>` is resolved
457
- to an absolute path before you send it. The member reads the repository,
474
+ `<repo>` is this main checkout's absolute path and `<scratch>` is the
475
+ absolute path `scratch-root.mjs` prints (**The scratch root is computed**
476
+ above), written into the prompt before you send it. The member reads the repository,
458
477
  proposes both commands and proves them with `recipe-prove.mjs` in a
459
478
  throwaway worktree of `origin/main`: the Install step must leave the tree
460
479
  clean, and the Test entrypoint must be shown to run real tests — the
@@ -1100,7 +1119,8 @@ is the body of every `agents/fleet-implementer-<cell>.agent.md`, byte-identical
1100
1119
  across all of them, and each harness injects it as the
1101
1120
  member's system prompt. Never re-paste it. The prompt fills that body's
1102
1121
  placeholders — the ticket number, the worktree abs path and branch
1103
- (`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/`, and the
1122
+ (`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/` — absolute,
1123
+ `<scratch>` as `scratch-root.mjs` printed it — and the
1104
1124
  distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
1105
1125
  comment or the issue body, whichever carries the brief, and its `Out of
1106
1126
  scope`, pasted verbatim from the Pull's own read. Beyond those it carries only
@@ -2201,7 +2221,7 @@ report recovery, never the exit code alone.
2201
2221
  The tick names every PR owed one — `DISPATCH review PR#<M>`, oldest first —
2202
2222
  and each gets one review, once per PR:
2203
2223
 
2204
- a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch` — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file into the review's own run root and reports its path and `reviewed=` token; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call. **`scratch` is the scratch root itself, never the review side's `<scratch>/pr<N>` partition:** the review creates `pr<N>/` under it, so a `pr<N>` passed in nests every run root at `pr<N>/pr<N>/`, and the review refuses a `scratch` whose last component is `pr` plus digits before dispatching anything.
2224
+ a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch` — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file into the review's own run root and reports its path and `reviewed=` token; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call. **`scratch` is the scratch root itself, the absolute path `scratch-root.mjs` prints, never the review side's `<scratch>/pr<N>` partition:** the review creates `pr<N>/` under it, so a `pr<N>` passed in nests every run root at `pr<N>/pr<N>/`, and the review refuses a `scratch` whose last component is `pr` plus digits before dispatching anything.
2205
2225
 
2206
2226
  Write the `review=` token with `ledger.mjs row`, which **replaces the whole
2207
2227
  line**, so carry every other field. The tick counts in-flight reviews off the
@@ -2365,7 +2385,9 @@ on record), never the PR's
2365
2385
  implementer, recorded with `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the
2366
2386
  call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
2367
2387
  the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`,
2368
- `<run>` off the PR's latest `reviewed=` — never the findings. The fix-applier owns every per-PR ruling you once made
2388
+ `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>`
2389
+ in that prompt is the absolute path `scratch-root.mjs` printed, the
2390
+ `dispositions-<its name>.json` record's included. The fix-applier owns every per-PR ruling you once made
2369
2391
  before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
2370
2392
  `refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
2371
2393
  `testEnvironment`/`cwdAudit` before any result of the shared test run. It
@@ -2610,11 +2632,13 @@ all.
2610
2632
  > > `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
2611
2633
  > > the checkout — and bracket a fixture's own git with
2612
2634
  > > `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
2613
- > > the repository, and a fresh scratch dir's `fatal: not a git repository`
2614
- > > (exit 128) is the pass, not a failure; before any `git commit` it must
2615
- > > resolve to your scratch path — compare resolved forms (`realpath`), since
2616
- > > `--show-toplevel` can report `/private/tmp/…` for a `/tmp` scratch dir on
2617
- > > macOS.
2635
+ > > the host repository, and `fatal: not a git repository` (exit 128) is the
2636
+ > > usual pass, not a failure — an outer repository whose ignore rules cover
2637
+ > > your scratch dir is a pass too; before any `git commit` it must resolve to
2638
+ > > your scratch path, which catches a forgotten `git init` under any enclosing
2639
+ > > repository — compare resolved forms (`realpath`), since `--show-toplevel`
2640
+ > > can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under
2641
+ > > its resolved name.
2618
2642
  >
2619
2643
  > Survives → apply it, with one hold: if its refuter reports a blast radius
2620
2644
  > touching lines another finding also changes, that is the mutual-exclusion
@@ -2981,7 +3005,7 @@ a minute apart showed *different* mutants, so a member's report and any single
2981
3005
  **At your dispatch pin, never at the fetched branch tip** — duty 1 just
2982
3006
  proved the owned worktree sits at that pin, and `PR headRefOid` may carry
2983
3007
  commits no reviewer read, the substitution the halt block's head-equality
2984
- check rejects for the same reason. The member name is in the path because
3008
+ check rejects for the same reason. `<scratch>` is the absolute root your dispatch prompt names. The member name is in the path because
2985
3009
  the scratch root is shared with every sibling, so `<scratch>/pr<N>` alone
2986
3010
  collides whenever a PR gets a second finisher, and `worktree add` on an
2987
3011
  occupied path fails closed into a halt with a purely mechanical cause.
@@ -3344,7 +3368,8 @@ touch, and to read each corrected sentence literally, clause by clause. It then
3344
3368
  does the fix-applier's job too:
3345
3369
  apply, defer, file, push, report, exit — and before it reports, it writes its
3346
3370
  findings as a review result file in a run root of its own, made with
3347
- `mktemp -d "<scratch>/pr<pr>/run-XXXXXXXX"`, in the shape `review-and-fix.md`'s
3371
+ `mktemp -d "<scratch>/pr<pr>/run-XXXXXXXX"` (`<scratch>` the absolute path you
3372
+ named in its prompt), in the shape `review-and-fix.md`'s
3348
3373
  **The review result file** describes, and reports that file's path. On its
3349
3374
  report, record `reviewed=<head>:0/<refuted>/<deferred>:<run>`, `<run>` that run
3350
3375
  root's name, against the head it pushed — it applied
@@ -3414,7 +3439,9 @@ enough, and it never waits for the finisher's report. Tell it to read
3414
3439
  `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
3415
3440
  pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
3416
3441
  for late labels, then report once and exit — and say that you dispatched it,
3417
- which is what makes it hold that grace instead of arming its own watcher. **Dispatch
3442
+ which is what makes it hold that grace instead of arming its own watcher. Its
3443
+ prompt names the absolute `<scratch>` (`scratch-root.mjs`'s output): the bot
3444
+ writes only under `<scratch>/pr<N>/merge-bot-<n>/`. **Dispatch
3418
3445
  it with the `agent` that `ledger.mjs dispatch merge-bot` printed and omit
3419
3446
  `model` on the call** — the tier lives in that definition's frontmatter,
3420
3447
  `agents/fleet-merge-bot.agent.md`, as the `@smol:low` route, which resolves
@@ -16,7 +16,7 @@ Private copy and test command solve different problems; conflating them is how s
16
16
 
17
17
  One flat namespace, generic filenames (`b.min.js`, `probe.mjs`) — one agent overwrote sibling's `package.json`. And finding ids restart at 1 every review, so two fix-appliers on different PRs both reach for `unv1`. Two levels, and nothing outside them — a probe built a git repo at the *checkout root*.
18
18
 
19
- The axis is two-sided: the member partitions, and the parent assigns each child's path. A member owns one directory — `<scratch>/impl-<N>/` for an implementer, `<scratch>/pr<N>/…` on the review side — and every agent it dispatches gets a directory under that one, unique to that child and never shared, written into the child's prompt as an absolute path; a child never derives its own. The review side is already laid out this way: `review-core.mjs` makes the run root `<scratch>/pr<N>/run-XXXXXXXX/` with `mktemp` — it appends `pr<N>/` to the scratch root it is handed and refuses a scratch already ending in one, so a review runner is given the root, never `<scratch>/pr<N>` — then writes `<run>/<dim>/` into each specialist's prompt and `<run>/verify-<dim>/f<i>-l<j>/` into each refuter's. A fix-applier makes its own run root the same way — `<scratch>/pr<N>/fix-XXXXXXXX/` with `mktemp` — then resolves `<run>/<finding>/` to an absolute path for the refuter it dispatches on a suggestion; the bare `<scratch>/pr<N>/<finding>/` is not that path, since finding ids restart at 1 each fix-applier round too, and a later round on the same PR would reach for the same directory a prior round's refuter left fixtures in. An implementer's child gets `<scratch>/impl-<N>/<childName>/`, named after its dispatch name. Refuters are grandchildren, not members, which is why the member partition alone is not the rule: the agents that actually collided were ones no member rule reaches, and a parent-assigned path is what reaches them. Read from the object store at a pinned ref, write only under own path.
19
+ The axis is two-sided: the member partitions, and the parent assigns each child's path. `<scratch>` itself is assigned, never invented: the controller resolves it with `scratch-root.mjs` and writes the absolute path into each member's prompt. A member owns one directory — `<scratch>/impl-<N>/` for an implementer, `<scratch>/pr<N>/…` on the review side — and every agent it dispatches gets a directory under that one, unique to that child and never shared, written into the child's prompt as an absolute path; a child never derives its own. The review side is already laid out this way: `review-core.mjs` makes the run root `<scratch>/pr<N>/run-XXXXXXXX/` with `mktemp` — it appends `pr<N>/` to the scratch root it is handed and refuses a scratch already ending in one, so a review runner is given the root, never `<scratch>/pr<N>` — then writes `<run>/<dim>/` into each specialist's prompt and `<run>/verify-<dim>/f<i>-l<j>/` into each refuter's. A fix-applier makes its own run root the same way — `<scratch>/pr<N>/fix-XXXXXXXX/` with `mktemp` — then resolves `<run>/<finding>/` to an absolute path for the refuter it dispatches on a suggestion; the bare `<scratch>/pr<N>/<finding>/` is not that path, since finding ids restart at 1 each fix-applier round too, and a later round on the same PR would reach for the same directory a prior round's refuter left fixtures in. An implementer's child gets `<scratch>/impl-<N>/<childName>/`, named after its dispatch name. Refuters are grandchildren, not members, which is why the member partition alone is not the rule: the agents that actually collided were ones no member rule reaches, and a parent-assigned path is what reaches them. Read from the object store at a pinned ref, write only under own path.
20
20
 
21
21
  ## IDE/harness diagnostics attribute by bare filename, with no path
22
22
 
@@ -15,7 +15,7 @@ Read first: `gh issue view <N> --json title,body,comments --jq '.title, .body, (
15
15
  | **light** | States exactly what to change, one-two files, no design choice open | Test first, make the one change, run it with the repo's test runner |
16
16
  | **heavy** | Ambiguity in *what* to build, >~3 files, new API/schema/UX, or several viable approaches | Write a short plan, then carry it out inline, test first |
17
17
 
18
- **Fleet member on heavy: write the plan under your own scratch path, `<scratch>/impl-<N>/`, then carry it out inline, test first.**
18
+ **Fleet member on heavy: write the plan under your own scratch path, `<scratch>/impl-<N>/` (`<scratch>` is the path your dispatch prompt names; with no dispatcher, the output of `~/.fleet/bin/fleet-run scratch-root.mjs`), then carry it out inline, test first.**
19
19
  Heavy is never a reason to give up: a `ready-for-agent` ticket's `## Agent Brief`
20
20
  already settles the open design choices, so plan from it. Solo session has a user:
21
21
  settle the open design choices with them before planning.