@feigi/fleet-ctl 3.24.3 → 3.24.5

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.
package/scripts/net.sh CHANGED
@@ -1,5 +1,5 @@
1
1
  # shellcheck shell=sh
2
- # The fleet's bounded, prompt-suppressed git transport (#92, #346, #347).
2
+ # The fleet's bounded, prompt-suppressed git transport.
3
3
  # Sourced, never executed — no shebang, and the `shell=sh` directive above is
4
4
  # what tells shellcheck what to check it as.
5
5
  #
@@ -16,19 +16,19 @@
16
16
  # builtin, so failing to open its operand aborts a non-interactive shell before
17
17
  # any `||` on the line can run.
18
18
  #
19
- # WHY A LIB. #346 landed this mechanism inside inflight.sh's probe 2, for the
19
+ # WHY A LIB. This mechanism first landed inside inflight.sh's probe 2, for the
20
20
  # one call that probe makes. Every other unattended `git` network call in the
21
21
  # fleet — release-ticket.sh's pushed-branch lookup, and the fetches in
22
22
  # prove-merge.sh, reap.sh and verify-sha.sh — still ran raw, so each of them
23
23
  # could prompt on a credential or a host key, or stall on a transport that
24
- # connects and then goes quiet, holding a fleet slot indefinitely (#347). The
24
+ # connects and then goes quiet, holding a fleet slot indefinitely. The
25
25
  # alternative considered was copying the transport flags to each call site; it
26
26
  # is what this file exists to avoid, and it would not have bounded the connect
27
27
  # phase in any case, since git exposes no knob for it. So the mechanism moved
28
28
  # here whole and probe 2 became its first caller rather than its owner.
29
29
  #
30
- # `gh` calls are deliberately NOT routed through this. Measured during the
31
- # PR #332 review, `gh issue view` against a silent listener failed on its own at
30
+ # `gh` calls are deliberately NOT routed through this. Measured: `gh issue
31
+ # view` against a silent listener failed on its own at
32
32
  # 10.0s with `net/http: TLS handshake timeout` — `gh` is already bounded, and
33
33
  # wrapping it would buy a second bound over the first.
34
34
  #
@@ -41,7 +41,7 @@
41
41
  # The override exists so the tests can buy a short budget instead of paying the
42
42
  # default one per case. It can only ever SHORTEN: a knob that could lengthen it
43
43
  # would be one more way for configuration to remove the bound, which is the
44
- # defect the ssh half of #346 reports, and reproducing it here to be convenient
44
+ # defect this lib exists to close, and reproducing it here to be convenient
45
45
  # would be its own bug. A value that is not a positive integer is not an error
46
46
  # and not a bound either — the default stands.
47
47
  #
@@ -100,11 +100,12 @@ net_fetch_budget() {
100
100
  # reparents its children and the links this walk follows are gone by then.
101
101
  #
102
102
  # Ceiling: with no `ps` to read, this falls back to the named process alone and
103
- # a helper can survive it. That is the pre-#346 behaviour for that one case, not
104
- # a new failure, and it is preferred over signalling a set derived from nothing.
103
+ # a helper can survive it. That is the old named-process-only kill for that
104
+ # one case, not a new failure, and it is preferred over signalling a set
105
+ # derived from nothing.
105
106
  # But it is not silent: the fallback records itself in $net_wdfile so the reason
106
107
  # printed downstream can say the bound may not have held. A degraded kill that
107
- # reads exactly like a clean one is the defect #346 asks this script not to
108
+ # reads exactly like a clean one is a defect this script must not
108
109
  # have — measured, `ps` shimmed to exit 127 produced byte-identical stderr to
109
110
  # the healthy run while a `git remote-https` survived and held the caller for
110
111
  # its whole cap. `${net_wdfile:-/dev/null}` because net_kill_tree also runs
@@ -126,7 +127,7 @@ net_fetch_budget() {
126
127
  # parents first, which is exactly why every end-to-end case here stays green on
127
128
  # that mutant.
128
129
  #
129
- # What holds it is the descending-pid chain in net.test.mjs's net_kill_tree
130
+ # What holds it is the descending-pid chain in the suite's net_kill_tree
130
131
  # case — each child's pid BELOW its parent's, the shape pid wraparound produces.
131
132
  # Feeding the rows in a different order does not hold it: the hash order is not
132
133
  # the input order, and measured, the same key set fed parents-first and
@@ -234,7 +235,7 @@ net_stalled() {
234
235
  # above: it gates the banner exchange, not only the TCP handshake, so a peer
235
236
  # that accepts the connection and then never speaks is cut off at
236
237
  # ConnectTimeout. Measured against that exact case (OpenSSH_10.2p1, the
237
- # accept-then-silent listener the test at inflight.test.mjs uses) — both
238
+ # suite's accept-then-silent listener) — both
238
239
  # options set: "Connection timed out during banner exchange" at 10.0s;
239
240
  # ConnectTimeout alone, ServerAlive dropped: 10.0s, identical; ServerAlive
240
241
  # alone, ConnectTimeout dropped: still running at 30s, killed from outside.
@@ -269,9 +270,9 @@ net_stalled() {
269
270
  # asked for, and terminates only where that value does. Measured on the same
270
271
  # listener: a user ConnectTimeout of 0 is accepted, wins by the same rule and
271
272
  # left the call still connecting at 40s, where the 10s set here cut at 10.2s —
272
- # unbounded, through the user's own config, which is the #92 hang again. The
273
+ # unbounded, through the user's own config, which is the unattended hang again. The
273
274
  # watchdog below is what now bounds that case, since it bounds the call rather
274
- # than the transport and so does not depend on any value ssh resolved (#346).
275
+ # than the transport and so does not depend on any value ssh resolved.
275
276
  # Ordering these first would bound the call at its own value instead,
276
277
  # at the cost of silently overriding a deliberate proxy or timeout config: a
277
278
  # real regression traded for a hypothetical one, so it is not done.
@@ -283,7 +284,7 @@ net_stalled() {
283
284
  # the BatchMode=yes set here alone, an unknown host key fails at once ("Host key
284
285
  # verification failed"); with a user's BatchMode=no ahead of it and a terminal
285
286
  # reachable, ssh sat on "Are you sure you want to continue connecting" until
286
- # killed — the unattended hang #92 exists to stop. Reachable is the operative
287
+ # killed — the unattended hang this lib exists to stop. Reachable is the operative
287
288
  # word: with no terminal available it aborts rather than waiting. Honoured
288
289
  # anyway, because it is the user's explicit setting; this records what that
289
290
  # costs rather than warning about a choice they made on purpose. The watchdog
@@ -291,7 +292,7 @@ net_stalled() {
291
292
  # the prompt is ssh's, so no git-side variable reaches it, and the setting that
292
293
  # opens it is the user's own, so overriding it is not on offer either. No test
293
294
  # covers this one — the exposure needs a reachable terminal, and the harness
294
- # runs without one, where ssh aborts at once instead of asking (#346).
295
+ # runs without one, where ssh aborts at once instead of asking.
295
296
  #
296
297
  # http: lowSpeedLimit/lowSpeedTime is git's (curl's) own bound for a transfer
297
298
  # that goes quiet — abort if it sits under 1000 bytes/s for 10s.
@@ -308,7 +309,7 @@ net_stalled() {
308
309
  # script does not set and cannot shorten.
309
310
  #
310
311
  # Hence the watchdog below, and hence these knobs are no longer the bound. They
311
- # stay anyway, and that is a decision rather than an oversight (#346): each one
312
+ # stay anyway, and that is a decision rather than an oversight: each one
312
313
  # fails earlier than the watchdog and in git's own words, which is the more
313
314
  # useful thing to read on a terminal, and dropping them would make every ssh
314
315
  # stall wait out the full budget where ConnectTimeout ends it in a fraction of
@@ -320,9 +321,10 @@ net_stalled() {
320
321
  # call — its own `sleep` is a child, and an orphaned sleeper does not sit
321
322
  # harmlessly: it wakes at the end of its budget and fires net_kill_tree at a pid
322
323
  # this shell no longer owns, which after a budget's worth of pid churn can be an
323
- # unrelated process — and, since #346, an unrelated SUBTREE. It cannot leak onto
324
- # the caller's stderr whatever else it does, because the `>/dev/null 2>&1` below
325
- # is on the sleeper itself and both its descriptors are already closed.
324
+ # unrelated process — and, because the kill walks every descendant, that
325
+ # process's whole SUBTREE. It cannot leak onto the caller's stderr whatever else
326
+ # it does, because the `>/dev/null 2>&1` below is on the sleeper itself and both
327
+ # its descriptors are already closed.
326
328
  #
327
329
  # `wait` is captured through an explicit `|| net_status=$?`, and `set -e` is
328
330
  # why: a bare `wait` on a killed child aborts at that line, which is after the
@@ -352,7 +354,7 @@ net_git() {
352
354
  # sends TERM then KILL with no pause, so whichever one reaps the job first is
353
355
  # a race, not a property either shell owns. What the shell DOES fix is the
354
356
  # FORM — bash-as-sh names the job (the long form); dash's notice is bare, just
355
- # `<signal>: <n>`. Measured for #1042 by replaying net_git's own mechanism
357
+ # `<signal>: <n>`. Measured by replaying net_git's own mechanism
356
358
  # against a plain `sleep`: on this machine, `/bin/sh` (bash 3.2.57) and
357
359
  # `/bin/dash` both gave TERM, every run — a quiet-system sample, not a signal
358
360
  # either shell is owed, which is why a caller has to accept either.
@@ -379,7 +381,7 @@ net_git() {
379
381
  # worktree directory, HEAD, or anything else in the entry — is pruned on
380
382
  # sight: the 3-month floor bounds staleness git can measure from the
381
383
  # entry's own files, and a missing pointer gives it nothing to measure,
382
- # so the floor does not apply. Measured (#2078): a fixture with exactly
384
+ # so the floor does not apply. Measured: a fixture with exactly
383
385
  # that fault, fetched through this function unmodified, loses the
384
386
  # registry entry between the fetch returning and the caller's own next
385
387
  # read of it — a worktree whose fault is seconds old, not months.
@@ -33,7 +33,7 @@
33
33
  # parent that looks right.
34
34
  #
35
35
  # The payload splits the checks into three kinds, because a flat object could not
36
- # say which of its fields were load-bearing for the verdict it sits next to (#18):
36
+ # say which of its fields were load-bearing for the verdict it sits next to:
37
37
  #
38
38
  # preconditions — every `die` above the verdict. They exit 2 with NO payload, so
39
39
  # they never appear as a false field beside `proved`. `merge ∈
@@ -55,7 +55,7 @@ set -eu
55
55
  NAME=prove-merge
56
56
  die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
57
57
 
58
- # The escaping helpers (#119). json.sh's header holds the sourcing contract and
58
+ # The escaping helpers. json.sh's header holds the sourcing contract and
59
59
  # the measurements behind it. Exit 1 out of THIS script means "the proof is a
60
60
  # no", which the merge bot reads as a reason to refuse a merge, so a missing
61
61
  # library must not be able to say it — which is why `[ -r ]` has to fire before
@@ -66,7 +66,7 @@ json_lib="$(dirname "$0")/json.sh"
66
66
  # shellcheck source=json.sh
67
67
  . "$json_lib" || die "$json_lib failed to load"
68
68
 
69
- # The bounded, prompt-suppressed git transport (#92, #346, #347). The fetch
69
+ # The bounded, prompt-suppressed git transport. The fetch
70
70
  # below is unattended: with no bound it can prompt for a credential or a host
71
71
  # key, or stall on a transport that connects and then goes quiet, and either
72
72
  # holds a fleet slot until something outside kills it. net.sh's header holds the
@@ -116,7 +116,7 @@ for obj in "$pre" "$post" "$merge"; do
116
116
  git cat-file -e "${obj}^{commit}" || die "cannot resolve $obj to a commit in this repository"
117
117
  # -e above peels through a tag to reach the commit underneath, so an
118
118
  # annotated tag clears that line even though $obj itself is not a commit —
119
- # only the object at the far end of the peel is (#585). $pre and $post are
119
+ # only the object at the far end of the peel is. $pre and $post are
120
120
  # then resolved UNPEELED by plain `git rev-parse` below, so a tag there hands
121
121
  # back the tag object's own sha rather than the commit's, and the identity
122
122
  # test later in this script compares that against a commit sha and can never
@@ -139,7 +139,7 @@ echo "\$ git merge-base --is-ancestor $merge $base" >&2
139
139
  # Assigned first, not tested inline: `die` inside `$(...)` exits the subshell,
140
140
  # and `[ ]` discards that status, so `set -e` never fires and a probe that could
141
141
  # not answer falls through to the disproof below — a verdict never established.
142
- # An assignment is a simple command, so its status is the substitution's (#267).
142
+ # An assignment is a simple command, so its status is the substitution's.
143
143
  merge_anc=$(is_ancestor "$merge" "$base")
144
144
  [ "$merge_anc" = true ] || die "$merge is not reachable from $base — that merge did not land"
145
145
 
@@ -213,8 +213,8 @@ echo "$NAME: proved=$proved (path=$proof_path)" >&2
213
213
  # come from `git rev-parse`, 40 hex characters and nothing else, and
214
214
  # `$proof_path` is this script's own `rebase`/`no-rebase` literal. They go
215
215
  # through `jstr` for uniformity against a later edit that changes where a field
216
- # comes from, the same reason inflight.sh wraps `$pr`, and it costs nothing
217
- # (#119). Assigned before the printf, never inline in its argument list — a
216
+ # comes from, the same reason inflight.sh wraps `$pr`, and it costs nothing.
217
+ # Assigned before the printf, never inline in its argument list — a
218
218
  # `$()` there sits outside this `|| die`, contributes an empty argument on
219
219
  # failure, and printf still exits 0 with a malformed payload.
220
220
  second_j=$(jstr "$second") && first_j=$(jstr "$first") && path_j=$(jstr "$proof_path") \
@@ -1,5 +1,4 @@
1
- // review-core.mjs — the review body for PR review (#1349, per #1303's ruling
2
- // on #1296). Read that ruling before touching this file.
1
+ // review-core.mjs — the review body for PR review.
3
2
  //
4
3
  // This file holds every host-independent declaration PR review needs: the
5
4
  // JSON schemas, `usableDiff`, `readRules`, `resolveTestCmd`,
@@ -22,15 +21,15 @@
22
21
  // `null`, which every guard here — `if (snap) {...}`, `unrunCrashed`,
23
22
  // `verdictFor` — is written against).
24
23
  //
25
- // Two imports. arg.mjs's isDigits(), added by #878: this file is an ordinary
24
+ // Two imports. arg.mjs's isDigits(): this file is an ordinary
26
25
  // module, so it consumes the repo's digits rule directly rather than
27
- // declaring its own copy. node:path's `posix`, added by #2323, to normalise a
26
+ // declaring its own copy. node:path's `posix`, to normalise a
28
27
  // scratch path before `runnerScratchRefusal` reads its last component.
29
28
  //
30
- // `.mjs`, not `.js` (#1763): this file was `review-core.js` until then, and
29
+ // `.mjs`, not `.js`: this file was once `review-core.js`, and
31
30
  // nothing that ships declares a `type`, so Node below 20.19.0/22.7.0 —
32
31
  // inside the declared consumer floor — read it as CommonJS and
33
- // review-eval.mjs's import of it failed. node-floor-sweep.test.mjs keeps a
32
+ // review-eval.mjs's import of it failed. A suite sweep keeps a
34
33
  // shipped `.mjs` from importing a relative module under any other extension.
35
34
 
36
35
  import { posix } from "node:path";
@@ -91,7 +90,7 @@ export const SNAPSHOT_SCHEMA = {
91
90
  path: { type: "string" },
92
91
  head: { type: "string" },
93
92
  pathVerified: { type: "boolean" },
94
- // #1056. `pathVerified` says the tree is THERE; this says the tree is
93
+ // `pathVerified` says the tree is THERE; this says the tree is
95
94
  // MEASURABLE — that the snapshot is a git repository holding the reviewed
96
95
  // commit's tree. Required for `pathVerified`'s reason: an omitted boolean
97
96
  // must not read as a verified environment, because the whole defect was a
@@ -111,7 +110,7 @@ export const SNAPSHOT_SCHEMA = {
111
110
  },
112
111
  };
113
112
 
114
- // #2315. What the review's one shared test run reports back. `command` and the
113
+ // What the review's one shared test run reports back. `command` and the
115
114
  // log path are NOT asked for: the caller handed both out, so it already knows
116
115
  // them, and an agent's echo of either could only disagree. Every count is
117
116
  // optional and stays absent when the log does not state it — an absent
@@ -133,7 +132,7 @@ export const TEST_RUN_SCHEMA = {
133
132
  };
134
133
 
135
134
  // --- Dimension catalog --------------------------------------------------
136
- // #1349, per #1303's gap 3: no dimension carries a `model`/`effort` field —
135
+ // No dimension carries a `model`/`effort` field —
137
136
  // dispatch tier lives ONLY in each fleet-owned agent definition's own
138
137
  // frontmatter. `agentType` is a bare frontmatter `name:` (omp's native
139
138
  // `agent()` lookup is an exact match on one).
@@ -174,14 +173,14 @@ export const DEFAULT_DIMENSIONS = [
174
173
  },
175
174
  ];
176
175
 
177
- // #2102: the omp `fleet-review-runner` agent definition's `spawns:`
176
+ // The omp `fleet-review-runner` agent definition's `spawns:`
178
177
  // frontmatter must allow exactly the agent types dispatched below (the
179
- // snapshot agent, the shared test run's agent (#2315), every
178
+ // snapshot agent, the shared test run's agent, every
180
179
  // DEFAULT_DIMENSIONS entry, and the verifier) — omp denies every spawn by
181
180
  // default, and the runner declared no `spawns` at all until this fix.
182
181
  // Exporting the three literal-only types (snapshot/test-run/verifier have no
183
182
  // DEFAULT_DIMENSIONS entry of their own) plus the derived full set lets
184
- // review-runner-spawns.test.mjs pin the frontmatter against what this file
183
+ // a test pin the frontmatter against what this file
185
184
  // actually dispatches, instead of a hand-copied list that can drift.
186
185
  export const SNAPSHOT_AGENT_TYPE = "fleet-review-snapshot";
187
186
  export const TEST_RUN_AGENT_TYPE = "fleet-review-test-run";
@@ -197,15 +196,17 @@ export const SPAWNED_AGENT_TYPES = [
197
196
  // computeStats owns both thresholds).
198
197
  export const SIZE_TIER_PROFILES = new Set(["single-file", "small"]);
199
198
  // The refuter-budget floor: `correctness`/`silent-failure` miss silently and
200
- // permanently; `comments` sits beside them for a different reason (#218).
199
+ // permanently; `comments` sits beside them because a comment-only edit to a
200
+ // code file classifies as `src`, never `docs`, and would otherwise get no
201
+ // comment review at all.
201
202
  // Keyed on recoverability of a MISS, never on tier — `verifiersFor` takes a
202
203
  // severity and nothing else.
203
204
  export const SIZE_TIER_DIMS = new Set(["correctness", "silent-failure", "comments"]);
204
205
 
205
206
  // The refuter budget per severity, derived once per run from the caller's
206
207
  // own `A.verifiers`/`A.verifiersBySeverity` overrides (or the defaults) and
207
- // bound to a `(severity) => count` closure — `select-dimensions.test.mjs`
208
- // imports this directly rather than re-deriving it from a lifted copy.
208
+ // bound to a `(severity) => count` closure — the suite imports this directly
209
+ // rather than re-deriving it from a lifted copy.
209
210
  export function verifiersFor(A) {
210
211
  const verifiers = A.verifiers || 2;
211
212
  const by = A.verifiersBySeverity || { critical: verifiers, important: verifiers, suggestion: 0 };
@@ -214,8 +215,8 @@ export function verifiersFor(A) {
214
215
 
215
216
  // --- Pure functions -------------------------------------------------------
216
217
  // Every function below was ported byte-identical (function body) from this
217
- // repo's retired pre-cutover review workflow script's own declaration, before
218
- // ADR 0014 retired that file — see this repo's git history for the full
218
+ // repo's pre-cutover review workflow script's own declaration, before that
219
+ // file was retired — see this repo's git history for the full
219
220
  // historical rationale on each; it is not repeated here to avoid a second
220
221
  // copy of PROSE disconnecting the way this repo's own "recurring pin defect"
221
222
  // comment warns a second copy of CODE does.
@@ -270,12 +271,12 @@ reads carried 434 KB.`;
270
271
 
271
272
  // The step a missing Test entrypoint is derived by, named in the refusal so the
272
273
  // caller — a controller or a reviewer — knows what to run rather than what went
273
- // wrong (ADR 0015). derive-testcmd.sh's refusals about the cache name the same
274
+ // wrong. derive-testcmd.sh's refusals about the cache name the same
274
275
  // step; its exit-3 refusals name an environment fault instead, which the caller
275
276
  // fixes rather than deriving. This one covers the case where the snapshot agent
276
277
  // reported no reason at all.
277
278
  const DERIVATION_STEP =
278
- "run the Recipe derivation step (run-team phase 0, before the first claim — ADR 0015) to derive, prove and write the Recipe cache";
279
+ "run the Recipe derivation step (run-team phase 0, before the first claim) to derive, prove and write the Recipe cache";
279
280
 
280
281
  export function resolveTestCmd(explicit, snap) {
281
282
  if (explicit) return explicit;
@@ -323,12 +324,12 @@ export function selectDimensions(all, stats) {
323
324
  // documents `args.dimensions` as accepting "keys or dimension objects" — but
324
325
  // until now only objects worked: a key array passed straight through and
325
326
  // every dereference below (`d.key`, `d.prompt`, `d.agentType` — three) came
326
- // back `undefined`, with no throw and no warning (#113). Resolve strings
327
+ // back `undefined`, with no throw and no warning. Resolve strings
327
328
  // against the workflow's own catalog, and check every object has the three
328
329
  // fields it REQUIRES AND that each of those is a string — presence alone let
329
330
  // a non-string field reach the specialist dispatch machinery downstream
330
331
  // instead of failing at this validated boundary. `model` is no longer a
331
- // fourth optional field (#1349): an override entry that still sends one is
332
+ // fourth optional field: an override entry that still sends one is
332
333
  // refused outright, loudly, rather than silently accepted and ignored — see
333
334
  // the check below.
334
335
  // Anything unresolvable stops the run and names what was not recognised — a
@@ -394,7 +395,7 @@ export function snapshotMissing(snap, runRootPrefix) {
394
395
  return null;
395
396
  }
396
397
 
397
- // #1056. What a suite run inside the snapshot is evidence ABOUT, in one
398
+ // What a suite run inside the snapshot is evidence ABOUT, in one
398
399
  // paragraph every specialist prompt and the returned payload both carry.
399
400
  //
400
401
  // `repoVerified` false is deliberately NOT a refusal (`snapshotMissing` says
@@ -434,7 +435,7 @@ validation of the tree: its counts are snapshot-measured, and a failure in it
434
435
  cannot be told apart from a regression.`;
435
436
  }
436
437
 
437
- // #2315. Every run-quality verdict below reads the review's ONE shared test
438
+ // Every run-quality verdict below reads the review's ONE shared test
438
439
  // run — `{command, logPath, exitCode?, tests?, pass?, fail?, cancelled?,
439
440
  // skipped?, error?}`, `command`/`logPath` the caller's own and the rest the
440
441
  // test-run agent's report — never a specialist's own run: no specialist runs
@@ -474,7 +475,7 @@ function failingDesc(run) {
474
475
  return run.cancelled ? `${run.fail || 0} failing and ${run.cancelled} cancelled tests` : `${run.fail} failing tests`;
475
476
  }
476
477
 
477
- // Failing tests are owned by the review as a whole (#2315): `findings` is
478
+ // Failing tests are owned by the review as a whole: `findings` is
478
479
  // every finding that reached the payload, and ONE from any dimension
479
480
  // satisfies the check for all — no dimension is asked to duplicate a
480
481
  // sibling's, and none is marked unrun because a sibling filed it. A refuted
@@ -509,7 +510,7 @@ function countsOf(run) {
509
510
  .join(", ");
510
511
  }
511
512
 
512
- // #2315. The Tests paragraph of every specialist prompt: the shared run's
513
+ // The Tests paragraph of every specialist prompt: the shared run's
513
514
  // command, counts, exit status and log path, in place of the instruction to
514
515
  // run the full suite that each specialist used to follow — one review was up
515
516
  // to six full sweeps of one immutable snapshot. `owner` is the one dimension
@@ -547,7 +548,7 @@ bears on your own lens.`,
547
548
  return lines.join("\n");
548
549
  }
549
550
 
550
- // #1433 gap: the CWD-AUDIT line the Review dispatch below asks a specialist
551
+ // The CWD-AUDIT line the Review dispatch below asks a specialist
551
552
  // to fold into `scope_searched` is a convention, not schema — FINDINGS_SCHEMA
552
553
  // accepts any string there, so a specialist that satisfies the schema while
553
554
  // never emitting the line, or misspelling it, produces a fully valid,
@@ -574,7 +575,7 @@ export function verdictFor(dispatched, votes) {
574
575
  return { verdict, votes: live, refutersDispatched: dispatched };
575
576
  }
576
577
 
577
- // #1802. One in-run re-dispatch for a crashed dispatch, before the result is
578
+ // One in-run re-dispatch for a crashed dispatch, before the result is
578
579
  // assembled — the specialist call and the refuter PAIR are the two units it
579
580
  // wraps. `crashed(value)` says whether a settled first attempt counts as a
580
581
  // crash; a THROWN first attempt is handed to it as `null`, because a
@@ -589,21 +590,21 @@ export function retryCrashed(dispatch, crashed) {
589
590
  .then(again, () => again(null));
590
591
  }
591
592
 
592
- // omp has no cached-replay mechanism (ADR 0004/0005, #1349 gap 1): a fresh
593
+ // omp has no cached-replay mechanism: a fresh
593
594
  // review re-dispatches every agent() live rather than only the crashed
594
595
  // legs, and the one re-dispatch this run gets was already spent in-run
595
- // (#1802) — a crashed finding is reported and deferred, never resumed.
596
+ // — a crashed finding is reported and deferred, never resumed.
596
597
  export function resumeFor(unverified) {
597
598
  const crashed = unverified.filter((f) => f.refutersDispatched > 0);
598
599
  if (!crashed.length) return { crashed, resume: null };
599
600
  const claim =
600
601
  "Findings in `unverified` with `refutersDispatched` above zero and no surviving vote had every refuter die, and die again on the in-run retry — nothing looked at them. ";
601
602
  const verb =
602
- "Defer them as crashed — reported, not acted on: omp's eval has no cached-replay mechanism (ADR 0004/0005, #1349 gap 1), so a fresh review re-dispatches every agent() live rather than only the crashed legs, and the in-run retry was this review's one re-dispatch. Re-run nothing for them.";
603
+ "Defer them as crashed — reported, not acted on: omp's eval has no cached-replay mechanism, so a fresh review re-dispatches every agent() live rather than only the crashed legs, and the in-run retry was this review's one re-dispatch. Re-run nothing for them.";
603
604
  return { crashed, resume: claim + verb };
604
605
  }
605
606
 
606
- // #1802. The digest: every field a controller acts on, and nothing bulky.
607
+ // The digest: every field a controller acts on, and nothing bulky.
607
608
  // The result object LEADS with exactly these keys, in this order
608
609
  // (`runReview`'s return below) — historically so the pre-cutover harness's
609
610
  // ~8 KB inline `<result>` cut landed in the finding arrays, never in the
@@ -621,18 +622,17 @@ export function digestOf(result) {
621
622
  return Object.fromEntries(DIGEST_KEYS.map((k) => [k, result[k]]));
622
623
  }
623
624
 
624
- // #1802. The digits refusal review-eval.mjs's `runReviewToFile` runs before
625
+ // The digits refusal review-eval.mjs's `runReviewToFile` runs before
625
626
  // its first attempt, so a dispatch mistake is refused once instead of being
626
627
  // retried and sent to the fallback reviewer. It lives here, not there, because
627
628
  // review-eval.mjs is a library and arg.mjs's `scripts/*.mjs` importers are its
628
- // CLI roster, each one probed to refuse a stray flag
629
- // (arg-header-probes-prose.test.mjs); this module already consumes the digits
630
- // rule on the review path. Null when `pr` is a PR number.
629
+ // CLI roster, each one probed to refuse a stray flag; this module already
630
+ // consumes the digits rule on the review path. Null when `pr` is a PR number.
631
631
  export function runnerPrRefusal(pr) {
632
632
  return isDigits(pr) ? null : `args.pr must be a PR number, got ${JSON.stringify(pr)}`;
633
633
  }
634
634
 
635
- // #2323. `runReview` owns the review side's `pr<N>/` partition — it appends
635
+ // `runReview` owns the review side's `pr<N>/` partition — it appends
636
636
  // `/pr${pr}` to the scratch it is given — so a scratch whose last component
637
637
  // is already `pr` plus digits is a caller that partitioned too, and its run
638
638
  // roots would nest at `<root>/pr<N>/pr<N>/run-*`, below the snapshot prompt's
@@ -662,7 +662,7 @@ export function runnerScratchRefusal(scratch) {
662
662
  // contract every guard below is written against), `phase(title)`,
663
663
  // `log(message)`, and OPTIONALLY `pipeline`/`parallel` (see
664
664
  // defaultPipeline/defaultParallel below for the omp shim's implementation
665
- // of both, built from #1296 Q3's analysis).
665
+ // of both).
666
666
  function defaultParallel(fns) {
667
667
  return Promise.all(fns.map((fn) => fn()));
668
668
  }
@@ -670,7 +670,7 @@ function defaultParallel(fns) {
670
670
  // Per-item independence, INCLUDING the null short-circuit: a stage-1 throw
671
671
  // or a stage-1 falsy result must land in the SAME null slot a stage-2 throw
672
672
  // would, so `unrunCrashed`'s index-aligned read of the pipeline result sees
673
- // one uniform shape for every crash cause (#1296 Q3).
673
+ // one uniform shape for every crash cause.
674
674
  async function defaultPipeline(items, stage1, stage2) {
675
675
  return Promise.all(
676
676
  items.map(async (item) => {
@@ -710,7 +710,7 @@ export async function runReview(host, args) {
710
710
 
711
711
  if (!pr || !worktree) throw new Error("review-pr: args.pr and args.worktree are required");
712
712
 
713
- // #878. The truthiness check above is what made the CLI fail-open REACHABLE:
713
+ // The truthiness check above is what made the CLI fail-open REACHABLE:
714
714
  // `pr` is interpolated into `gh pr diff ${pr}`, `gh pr view ${pr}` and
715
715
  // `diff-stats.mjs --pr ${pr}` in the snapshot prompt below, and a branch name
716
716
  // passes all three — `gh` resolves a non-numeric ref as a BRANCH, so the
@@ -771,7 +771,7 @@ both hashes — in \`repoError\`. The init is what makes the snapshot MEASURABLE
771
771
  the review runs this repository's own suite in there, and a suite with tests
772
772
  that need a working tree reports fewer passes and more failures in a bare
773
773
  extraction than in a checkout at the same commit, with nothing in the payload
774
- saying the measurement happened somewhere else (#1056). The tree-hash compare is
774
+ saying the measurement happened somewhere else. The tree-hash compare is
775
775
  the verification: two commits whose trees hash the same hold byte-identical
776
776
  content, so a match settles that the snapshot IS the reviewed tree — a stronger
777
777
  check than reading a few files, and the reason the commit comes BEFORE the
@@ -785,7 +785,7 @@ every file in the tree rather than a couple of them. Do not modify ${worktree}.
785
785
  Every path in the block above is absolute or \`-C\`-anchored on purpose: this
786
786
  dispatch carries no working directory of its own either, so you start in the
787
787
  controller's own checkout, and a relative path — a \`tar -x\` with no \`-C\`, a
788
- bare \`git\` — reads or writes THERE (#1433). Add nothing relative to it, and
788
+ bare \`git\` — reads or writes THERE. Add nothing relative to it, and
789
789
  chain a \`cd\` into "$RUN" or "$SNAP" for anything you run beyond it.
790
790
 
791
791
  Then capture the PR's diff for the specialists, plus the three facts the caller
@@ -811,7 +811,7 @@ as before. A cross-repo PR (a fork) skips the branch-ref read entirely and goes
811
811
  straight to 'refs/pull/${pr}/head' — the base repo's own copy of the PR head —
812
812
  because a fork's branch NAME is not guaranteed unique against the base
813
813
  repository, and a same-named hit on 'origin' would silently answer for the
814
- wrong repository rather than for the fork (#1616). The fallback to
814
+ wrong repository rather than for the fork. The fallback to
815
815
  'refs/pull/${pr}/head' also still fires for a same-repo PR whose branch ref
816
816
  came back empty, unchanged from before. Omit \`refHead\` when every read this
817
817
  PR was entitled to came back empty or was skipped: an absent value is neither
@@ -886,7 +886,7 @@ a false repoVerified.`,
886
886
  );
887
887
  log(`agents dispatched ${dimensions.map((d) => `${d.key}=${d.agentType}`).join(" ")}`);
888
888
 
889
- // #2315. The review's ONE run of the test command, before any specialist is
889
+ // The review's ONE run of the test command, before any specialist is
890
890
  // dispatched: every dimension used to run the full suite itself, so one
891
891
  // review was up to six full sweeps of one immutable snapshot. NOT wrapped in
892
892
  // `retryCrashed`: a crashed dispatch may already have launched the command,
@@ -946,7 +946,7 @@ learns the run produced none.`,
946
946
  const failureOwner = dimensions[0].key;
947
947
 
948
948
  const dimensionsUnrun = [];
949
- // #1433. Per-dimension record of the specialist's own CWD-AUDIT line (see
949
+ // Per-dimension record of the specialist's own CWD-AUDIT line (see
950
950
  // `cwdAuditFrom` above) — `{dimension, state, line}`, `state` one of
951
951
  // "clean"/"dirty"/"unrepo"/"missing". Populated for every dispatched
952
952
  // review that returned at all (a crashed dispatch has nothing to audit,
@@ -955,10 +955,10 @@ learns the run produced none.`,
955
955
  // dead-ending inside `scope_searched`.
956
956
  const cwdAudit = [];
957
957
 
958
- // #1433. Both prompts below carry the inherited-cwd rule, and it is stated in
958
+ // Both prompts below carry the inherited-cwd rule, and it is stated in
959
959
  // each rather than shared: review-eval.mjs's own header holds the measurement
960
960
  // and the reason this is prompt prose at all (no dispatch primitive takes a
961
- // per-call cwd), and #496's brief rules the shared-source route out for
961
+ // per-call cwd), and the shared-source route is ruled out for
962
962
  // exactly these blocks. Three parts, in this order, because the last two are
963
963
  // inert without the first: the cwd the specialist starts in is NAMED as a
964
964
  // tree it must not write to, `pwd` fixes which directory that is, and the
@@ -968,7 +968,7 @@ learns the run produced none.`,
968
968
  phase("Review");
969
969
  const reviewed = await pipeline(
970
970
  dimensions,
971
- // #1802: a crashed specialist (null or thrown) is re-dispatched once
971
+ // A crashed specialist (null or thrown) is re-dispatched once
972
972
  // before it counts as unrun. A specialist that RETURNED is never re-run
973
973
  // here — the shared run, not the specialist, is what `unrunEntries` judges.
974
974
  (d) =>
@@ -1022,7 +1022,7 @@ beginning \`CWD-AUDIT:\` — \`CWD-AUDIT: clean <path>\` when it printed nothing
1022
1022
  every run, clean or not: a clean tree is the result this check exists to
1023
1023
  produce, and an omitted line reads exactly like a check never run. Three PRs
1024
1024
  reviewed from one cell left four files modified in that checkout with nothing in
1025
- any payload saying so (#1433), so a path you cannot account for is still yours
1025
+ any payload saying so, so a path you cannot account for is still yours
1026
1026
  to name.`,
1027
1027
  { label: `review:${d.key}${forPr}`, phase: "Review", agentType: d.agentType, schema: FINDINGS_SCHEMA },
1028
1028
  ),
@@ -1036,7 +1036,7 @@ to name.`,
1036
1036
  (review && review.findings ? review.findings : []).map((f, fi) => () => {
1037
1037
  const n = verifiersForRun(f.severity);
1038
1038
  if (n === 0) return Promise.resolve({ ...f, dimension: d.key, ...verdictFor(0, []) });
1039
- // #1802: a pair whose EVERY vote died (or whose dispatch threw) is
1039
+ // A pair whose EVERY vote died (or whose dispatch threw) is
1040
1040
  // re-dispatched once, as a pair, before `verdictFor` reads it — one
1041
1041
  // live vote means the pair did not crash and is ruled on that vote.
1042
1042
  return retryCrashed(
@@ -1113,8 +1113,7 @@ Report it in \`reason\` as one line beginning \`CWD-AUDIT:\` —
1113
1113
  <what it printed>\` when it printed anything, \`CWD-AUDIT: unrepo <path>\` when
1114
1114
  git answered \`fatal: not a git repository\` — every run, clean or not: an
1115
1115
  omitted line reads exactly like a check never run, and applying a mutation is
1116
- how three reviews from one cell left four files modified in that checkout
1117
- (#1433).`,
1116
+ how three reviews from one cell left four files modified in that checkout.`,
1118
1117
  { label: `verify:${d.key}${forPr}`, phase: "Verify", agentType: VERIFIER_AGENT_TYPE, schema: VERDICT_SCHEMA },
1119
1118
  ),
1120
1119
  ),
@@ -1122,7 +1121,7 @@ how three reviews from one cell left four files modified in that checkout
1122
1121
  (votes) => !(votes && votes.some(Boolean)),
1123
1122
  ).then(
1124
1123
  (votes) => ({ ...f, dimension: d.key, ...verdictFor(n, votes) }),
1125
- // #1813: a rejection here means retryCrashed's OWN final attempt
1124
+ // A rejection here means retryCrashed's OWN final attempt
1126
1125
  // rejected — both dispatches of this finding's refuter pair
1127
1126
  // crashed, not just returned no votes. Left unhandled, that
1128
1127
  // rejection propagates into the shared `parallel()` above (a bare
@@ -1147,7 +1146,7 @@ how three reviews from one cell left four files modified in that checkout
1147
1146
  const refuted = all.filter((f) => f.verdict === "refuted");
1148
1147
  const unverified = all.filter((f) => f.verdict === "unverified");
1149
1148
 
1150
- // #2315. One verdict on the shared run, for every dimension whose chain did
1149
+ // One verdict on the shared run, for every dimension whose chain did
1151
1150
  // not die — a crashed one is named below with its own reason instead, so no
1152
1151
  // key is listed twice. Read only once every dimension has been verified: the
1153
1152
  // failing-tests check reads the findings that reached the payload, across
@@ -1174,10 +1173,10 @@ how three reviews from one cell left four files modified in that checkout
1174
1173
  // `dimensionsRun` names what was DISPATCHED after the size trim: a trimmed
1175
1174
  // fan-out must say so, never read as full coverage. It is not a coverage claim
1176
1175
  // on its own and never was — a specialist can be dispatched and die, or the
1177
- // review's one shared test run can execute nothing (#2315) — so
1176
+ // review's one shared test run can execute nothing — so
1178
1177
  // `dimensionsUnrun` names which of those keys did not cover their ground,
1179
1178
  // and why. A key in the first and NOT in the second ran a suite — not that
1180
- // it is covered (#535). `unrunReason` reads the shared run's counts and
1179
+ // it is covered. `unrunReason` reads the shared run's counts and
1181
1180
  // quotes its command into its message; it never checks that the test-run
1182
1181
  // agent ran the command it was handed rather than a narrower one, so a
1183
1182
  // substituted runner is not classified unrun.
@@ -1187,7 +1186,7 @@ how three reviews from one cell left four files modified in that checkout
1187
1186
  // make a crashed dimension indistinguishable from one the size tier never
1188
1187
  // dispatched — this ticket set's own defect, moved one field over.
1189
1188
  //
1190
- // #1802. Digest first, in DIGEST_KEYS order, bulk last — see DIGEST_KEYS
1189
+ // Digest first, in DIGEST_KEYS order, bulk last — see DIGEST_KEYS
1191
1190
  // above for why the order is the contract.
1192
1191
  return {
1193
1192
  pr,
@@ -1195,13 +1194,13 @@ how three reviews from one cell left four files modified in that checkout
1195
1194
  // The recovery, next to the fields a controller reads first; null unless
1196
1195
  // a refuter pair crashed again after the in-run retry.
1197
1196
  resume,
1198
- // #1056. Always present, in both regimes: a reader of this payload can
1197
+ // Always present, in both regimes: a reader of this payload can
1199
1198
  // never be left unable to tell an environment artifact from a regression,
1200
1199
  // and that costs nothing when there is nothing wrong to report.
1201
1200
  testEnvironment: environmentNote(snap),
1202
1201
  dimensionsRun: dimensions.map((d) => d.key),
1203
1202
  dimensionsUnrun,
1204
- // #1433. `cwdAuditFrom`'s per-dimension read of the specialist's own
1203
+ // `cwdAuditFrom`'s per-dimension read of the specialist's own
1205
1204
  // CWD-AUDIT line — the fact a dirty or unrepo'd inherited checkout is
1206
1205
  // otherwise reported into `scope_searched` and read by nothing.
1207
1206
  cwdAudit,