@feigi/fleet-ctl 3.156.2 → 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.
@@ -145,11 +145,12 @@ export async function runReviewOnOmp(args) {
145
145
  // keep out of its context. The run root is the review's own
146
146
  // `<scratch>/pr<pr>/run-XXXXXXXX`, the directory review-core.mjs's snapshot
147
147
  // step made with `mktemp` and the snapshot it returns sits in, so two reviews
148
- // of one PR — at one head or two — never write one file, and the ledger token
149
- // names the run whose file it is. No file is ever replaced. The file leaves
148
+ // of one PR — at one head or two — never write one file, and the `reviewed=`
149
+ // `ledger.mjs review --result` derives names the run whose file it is. No
150
+ // file is ever replaced. The file leaves
150
151
  // with its run root: the snapshot step of a later review of the same PR
151
- // removes that PR's run roots not touched for seven days, so a token older
152
- // than that names a file that is gone.
152
+ // removes that PR's run roots not touched for seven days, so a `reviewed=`
153
+ // older than that names a file that is gone.
153
154
  //
154
155
  // Failure is a throw or an empty return. The holder of the review call retries
155
156
  // once; a second failure returns `failed` with both errors, and writes no
@@ -186,22 +187,18 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
186
187
  errors.push(`attempt ${attempt}: ${e?.message ?? String(e)}`);
187
188
  continue;
188
189
  }
189
- // `result.counts` is read below to build the digest and the ledger
190
- // token, but that read happens AFTER `mkdir`/`writeFile` have already put
191
- // the file on disk — so a `run` that resolves to a truthy, object-shaped
192
- // result missing `.counts` would otherwise throw on the destructure below
193
- // OUTSIDE this function's own retry try/catch (which wraps only the
194
- // `run(args)` call), leaving a half-written review file on disk
195
- // that a fix-applier reading it would mistake for a completed review that
196
- // never actually finished. Treated the same as an empty return: retried,
197
- // then reported `failed`, and no file is written for it.
190
+ // A result with no object `counts` is no completed review: its digest
191
+ // would carry no counts, and `ledger.mjs review --result` derives no
192
+ // `reviewed=` from a file without them, so a fix-applier reading it would
193
+ // hold a review nothing can record. Treated the same as an empty return:
194
+ // retried, then reported `failed`, and no file is written for it.
198
195
  if (!result || typeof result !== "object" || !result.counts || typeof result.counts !== "object") {
199
196
  errors.push(`attempt ${attempt}: empty return (${String(result)})`);
200
197
  continue;
201
198
  }
202
199
  // The run root is read off the result, never rebuilt: only the snapshot
203
200
  // step's shell knew the `mktemp` name. A result whose snapshot is not in
204
- // a run root of this PR under this scratch names no run the ledger token
201
+ // a run root of this PR under this scratch names no run a `reviewed=`
205
202
  // could point a reader back to, so it is a failed attempt like the one
206
203
  // above.
207
204
  const runRoot = runRootOf(result.snapshot, scratch, pr);
@@ -231,12 +228,9 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
231
228
  errors.push(`attempt ${attempt}: could not write ${path}: ${e?.message ?? String(e)}`);
232
229
  continue;
233
230
  }
234
- const { survived, refuted, unverified } = result.counts;
235
231
  return {
236
232
  status: "completed",
237
233
  path,
238
- // The review's result token, ready for `ledger.mjs review <pr>`.
239
- ledger: `reviewed=${result.head}:${survived}/${refuted}/${unverified}:${basename(runRoot)}`,
240
234
  attempts: attempt,
241
235
  errors,
242
236
  digest: digestOf(result),
@@ -223,7 +223,7 @@ Record each ruling with `ledger.mjs ruled <pr> <decision>`, one line with its re
223
223
 
224
224
  ### Dispatching the members a wake names
225
225
 
226
- - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path and `reviewed=` token.
226
+ - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path.
227
227
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
228
228
  - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none, and a refuter report that surfaces to you is its to retrieve, never yours to scan or pass on. On a PR carrying `ready-to-merge`, its push moves the head after the label: a fresh finisher, per **Failure handling**.
229
229
  - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement; a second `failed` since its latest review escalates. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands.
@@ -256,9 +256,9 @@ references/isolation.md.
256
256
 
257
257
  **You read the digest; the findings are the fix-applier's.**
258
258
  `jq '{pr, head, resume, testEnvironment, suiteVerdict, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' <scratch>/pr<pr>/<run>/review.json`
259
- is the whole of your read, and it is what you record: `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`,
260
- off `head`, `counts` and the run root's name — the runner's `ledger` field — on
261
- the PR's row, with `ledger.mjs review <pr>`. Every later path to the review is built from that token, before a
259
+ is the whole of your read. The record is the `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
260
+ the `fleet-event.mjs review-result <pr> <path>` wake writes on the PR's row, off `head`, `counts` and the run root's
261
+ name, never one typed with `ledger.mjs review <pr>`. Every later path to the review is built from that token, before a
262
262
  restart or after one: `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's
263
263
  latest `reviewed=`. Findings never enter your context. The fix-applier
264
264
  reads every one off the file and makes every ruling on them
@@ -748,7 +748,7 @@ decides the rest — two resolve automatically, every other one escalates:
748
748
  | Cause | Resolution |
749
749
  |---|---|
750
750
  | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
751
- | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
751
+ | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
752
752
  | `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
753
753
  | `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry`, `.content` and `.remote`. Push or discard is yours, or the maintainer's if they cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
754
754
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
@@ -385,14 +385,14 @@ absent; `carries` null: the read could not be told, and `error` says why). A
385
385
  commit that undoes something the pin carries reads clean by content (`paths`
386
386
  empty) and only its `+` line catches it, so a `+` beside empty `paths` is not
387
387
  by itself safe to discard. A pushed stray is a head no reviewer read: record
388
- its review by hand with `ledger.mjs review <M>`, under the next runner letter
388
+ its review launch by hand with `ledger.mjs review <M>`, under the next runner letter
389
389
  as for a `past-pin` re-review below, before any finisher is dispatched.
390
390
 
391
391
  A `human` halt is a Ticketless PR whose diff is not inert: the maintainer adds
392
392
  `ready-to-merge` at the pinned head, which the merge bot merges off the
393
393
  finisher's `ready-to-merge-head:` comment; a moved head is merged by hand.
394
394
 
395
- The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate.
395
+ The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result, recorded by the `review-result` wake, reaches a fresh finisher through the same gate.
396
396
 
397
397
  A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
398
398
  and the causes `finisher-audit.mjs` names are the ones seen so far, not a
@@ -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.
@@ -104,7 +104,7 @@ PR stays queued, label untouched, and no member is dispatched to restore the lin
104
104
 
105
105
  ## The review pair on a PR's row
106
106
 
107
- A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`.
107
+ A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`. A `reviewed=` is a Gate verdict: `ledger.mjs review <pr> --result <path>` derives it from that file, and the `fleet-event.mjs review-result <pr> <path>` wake runs it. No `review` argument carries one, and one typed there is refused.
108
108
 
109
109
  ## The ledger's readability field: `ledger.ok`
110
110
 
@@ -6,7 +6,7 @@ Why member name load-bearing, why every member single-use, how a member's job ou
6
6
 
7
7
  ## Every member is named
8
8
 
9
- The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch and result are recorded on the PR's row with `ledger.mjs review <pr#>`), `finisher-pr-<pr#>` (the finisher gate's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
9
+ The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch is recorded on the PR's row with `ledger.mjs review <pr#>`, its result by the `review-result` wake), `finisher-pr-<pr#>` (the finisher gate's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
10
10
 
11
11
  ## The coordination contract
12
12
 
@@ -191,7 +191,7 @@ A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick pro
191
191
 
192
192
  ## Dispatching the members a wake names, in full
193
193
 
194
- - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path and `reviewed=` token.
194
+ - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path; the `fleet-event.mjs review-result <pr> <path>` wake records its `reviewed=`.
195
195
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
196
196
  - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>` and its report's settle takes the label off; then a fresh finisher, per **Failure handling**.
197
197
  - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement, but a second `failed` since the PR's latest review escalates (`ESCALATE fix-failed`).
@@ -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.