@feigi/fleet-ctl 3.24.7 → 3.24.9

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.
Files changed (35) hide show
  1. package/agents/fleet-implementer-slow-high.agent.md +2 -2
  2. package/agents/fleet-implementer-slow-medium.agent.md +2 -2
  3. package/agents/fleet-implementer-smol-high.agent.md +2 -2
  4. package/agents/fleet-implementer-task-high.agent.md +2 -2
  5. package/agents/fleet-implementer-task-max.agent.md +2 -2
  6. package/agents/fleet-review-comments.agent.md +1 -1
  7. package/agents/fleet-review-correctness.agent.md +1 -1
  8. package/agents/fleet-review-runner.agent.md +2 -2
  9. package/agents/fleet-review-silent-failure.agent.md +1 -1
  10. package/agents/fleet-review-simplify.agent.md +1 -1
  11. package/agents/fleet-review-snapshot.agent.md +1 -2
  12. package/agents/fleet-review-test-run.agent.md +2 -3
  13. package/agents/fleet-review-tests.agent.md +2 -2
  14. package/agents/fleet-review-types.agent.md +1 -1
  15. package/agents/fleet-review-verifier.agent.md +1 -1
  16. package/commands/review-and-fix.md +9 -9
  17. package/commands/run-merge-bot.md +14 -14
  18. package/commands/run-team-help.md +1 -1
  19. package/package.json +1 -1
  20. package/scripts/ci-state.mjs +25 -26
  21. package/scripts/compute-spend.mjs +22 -22
  22. package/scripts/diff-stats.mjs +12 -12
  23. package/scripts/fleet-heartbeat.mjs +9 -9
  24. package/scripts/fleet-state.mjs +15 -15
  25. package/scripts/fleet-tick.mjs +63 -63
  26. package/scripts/frontmatter-check.mjs +10 -11
  27. package/scripts/ledger-grammar.mjs +12 -13
  28. package/scripts/member-outcomes.mjs +8 -9
  29. package/scripts/merge-gate.mjs +2 -4
  30. package/scripts/pr-overlap.mjs +31 -30
  31. package/scripts/shortlist.mjs +6 -8
  32. package/scripts/staleness.mjs +21 -21
  33. package/scripts/tier-check.mjs +14 -14
  34. package/scripts/tier-roles.mjs +12 -12
  35. package/skills/next-ticket/SKILL.md +5 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.24.7",
3
+ "version": "3.24.9",
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": {
@@ -18,8 +18,7 @@ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
18
18
  const NAME = "ci-state";
19
19
 
20
20
  // die()/arg()/numArg()/has() shared with the other fleet scripts — see
21
- // arg.mjs for the fail-open (#61/#169/#364/#878) and pipe-safety
22
- // (#176/#328/#363) rationale.
21
+ // arg.mjs for the fail-open and pipe-safety rationale.
23
22
  // `base`/`workflow`/`workflow-file` below all fall back with `||`, so a
24
23
  // trailing `--base` (nothing after it) used to read as omitted and silently
25
24
  // compare against the DEFAULT base — `ci-state.mjs --pr 5 --base` gave a
@@ -49,7 +48,7 @@ const vlog = (...a) => {
49
48
  if (!quiet) console.error(...a);
50
49
  };
51
50
 
52
- // #262. A refusal from an exhausted REST quota reached the same arm as every
51
+ // A refusal from an exhausted REST quota reached the same arm as every
53
52
  // other gh read failure, so a caller could not tell an outage that clears on
54
53
  // its own from a repo or token that will still be unreadable after any wait.
55
54
  // The cause is only ever in gh's own stderr, which execFileSync BOTH forwards
@@ -73,7 +72,7 @@ const RATE_LIMITED = /rate limit|abuse detection/i;
73
72
  // printed nothing at all. A caller reading only the exit code is unaffected;
74
73
  // one parsing stdout gets a named cause instead of the empty capture
75
74
  // `merge-gate.mjs` reads as `ci-unreadable` there: a probe that could not
76
- // look, never a reading about the PR (ADR 0012 Decision 3).
75
+ // look, never a reading about the PR.
77
76
  //
78
77
  // It reports the refused query and nothing else. A quota refusal is a probe
79
78
  // that could not look, so every field this script would otherwise observe is
@@ -98,9 +97,9 @@ const RATE_LIMITED = /rate limit|abuse detection/i;
98
97
  // survives process.exit(). It also takes no newline of its own, which is why
99
98
  // every call site below embeds its own trailing newline in the string it passes to writeAll().
100
99
  //
101
- // #1549: this file used to carry its own copy of that write loop, called
100
+ // This file used to carry its own copy of that write loop, called
102
101
  // emit(), and the copy had DRIFTED — of the three hand-mirrored copies it was
103
- // the only one that never grew #889's retry cap, so a reader that stayed open
102
+ // the only one that never grew the retry cap, so a reader that stayed open
104
103
  // but never drained left it spinning forever. That is what a comment reading
105
104
  // "mirrors emit()" buys and what shared code buys instead. The loop, its cap
106
105
  // and its 1ms Atomics.wait are arg.mjs's now.
@@ -140,7 +139,7 @@ function spawn(cmd, args, { maxBuffer, capture = false } = {}) {
140
139
  return execFileSync(cmd, args, { encoding: "utf8", env: gitEnv(), ...(maxBuffer ? { maxBuffer } : {}), ...(capture ? { stdio: "pipe" } : {}) });
141
140
  }
142
141
 
143
- // Three disjoint shapes — Node-aborted (ENOENT/ENOBUFS), signal, exit (#176).
142
+ // Three disjoint shapes — Node-aborted (ENOENT/ENOBUFS), signal, exit.
144
143
  const failureOf = (e) => e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`);
145
144
 
146
145
  // `recover(e)`, given, is handed a failed child and returns the stdout to use
@@ -158,7 +157,7 @@ function run(cmd, args, { maxBuffer, recover, why } = {}) {
158
157
  // failure stands. `e.message` is the same string, not a fallback: Node
159
158
  // builds it as `Command failed: <cmd>\n<stderr>`.
160
159
  if (recover && e.stderr) writeAll(2, e.stderr);
161
- // A quota refusal names itself first (#262); every other cause reports
160
+ // A quota refusal names itself first; every other cause reports
162
161
  // exactly as it always has, on this same line and this same exit code.
163
162
  // `?? ""` stays — RegExp.test would coerce an absent stderr to the string
164
163
  // "undefined", which a future looser pattern could match. String() around
@@ -185,7 +184,7 @@ const cut = (s, n = 120) => (s.length > n ? `${s.slice(0, n)}… (truncated)` :
185
184
  // The parse succeeding is not the shape succeeding: an error object where an
186
185
  // array of runs is expected, a run view missing its jobs, parse cleanly and
187
186
  // flow on unchecked until the first dereference throws — same exit-1-as-
188
- // verdict failure, one layer further in (#269). `shape`, given, is
187
+ // verdict failure, one layer further in. `shape`, given, is
189
188
  // `(parsed) => string | null` — a reason the payload isn't what the caller
190
189
  // is about to read, or null when it's fine — checked here so each call site
191
190
  // declares what it expects instead of hand-rolling its own, the way the two
@@ -224,7 +223,7 @@ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
224
223
  // guards below each cover three faults at once — the key absent, the value an
225
224
  // empty string, the value not a string — and the `jobs` guard two of the same
226
225
  // kind, and every one of them printed a single identical "missing" line
227
- // (#926, measured), so a reader went hunting for a key gh had in fact
226
+ // (measured), so a reader went hunting for a key gh had in fact
228
227
  // returned as `""`, `42` or `null`. `saw` reports the value instead, and
229
228
  // claims absence only when the key really is absent.
230
229
  //
@@ -233,7 +232,7 @@ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
233
232
  // 'in' operator"). Every call site refuses a non-object ahead of any field
234
233
  // check, so `in` would work there today — but a field guard reordered past
235
234
  // that refusal would turn this diagnostic into the very exit-1-as-verdict
236
- // crash the shape checks exist to prevent (#269), where `hasOwn` just answers
235
+ // crash the shape checks exist to prevent, where `hasOwn` just answers
237
236
  // `false`.
238
237
  //
239
238
  // JSON.stringify, not the raw value: it is what makes `""` visible at all and
@@ -248,7 +247,7 @@ const saw = (obj, key) => {
248
247
  return `got ${cut(shown)}`;
249
248
  };
250
249
 
251
- // #840: `pr` was validated for truthiness alone, so `--pr abc` survived to
250
+ // `pr` was once validated for truthiness alone, so `--pr abc` survived to
252
251
  // every payload site — each built `pr: Number(pr)`, and `JSON.stringify(NaN)`
253
252
  // is `null`. The normal path is the worse of them: an unidentifiable payload
254
253
  // at exit 0 with `verdict: "green"`, which is the verdict the fleet gates on.
@@ -259,7 +258,7 @@ const saw = (obj, key) => {
259
258
  // so `--pr abc` could return a genuine verdict for whatever PR that branch
260
259
  // belongs to.
261
260
  //
262
- // #878 moved the rule itself into arg.mjs's numArg(), because the identical
261
+ // The rule itself lives in arg.mjs's numArg(), because the identical
263
262
  // shape was still live in diff-stats.mjs and pr-overlap.mjs and a fourth
264
263
  // spelling of it here is what the fix had to stop. What stays this file's own
265
264
  // is the usage line below — absent and malformed are different mistakes, and
@@ -268,7 +267,7 @@ const saw = (obj, key) => {
268
267
  // `=== null`, not `!pr`: numArg() returns a NUMBER, so `--pr 0` — a value the
269
268
  // caller did give — would otherwise be answered with a usage line claiming
270
269
  // `--pr` is required. `gh` answers it truthfully instead, as no such PR.
271
- // numArg() also no longer needs the placement #840's regex did: that one had
270
+ // numArg() also no longer needs the placement the old regex check did: that one had
272
271
  // to sit below this die because test() coerces `null` to the string "null",
273
272
  // and numArg() never tests a value it did not read. It still lands above
274
273
  // sweep(), per arg.mjs — where both would refuse, the more specific wording
@@ -284,17 +283,17 @@ if (pr === null) {
284
283
  const base = arg("base") || "main";
285
284
  const workflow = arg("workflow") || "CI";
286
285
  // --declare-no-ci is the caller's opt-out, never inferred: without it, a repo
287
- // with no workflow file yields verdict=no-ci but still exits non-zero (#111),
286
+ // with no workflow file yields verdict=no-ci but still exits non-zero,
288
287
  // so absence never silently reads as pass. Fits the argv-flag surface every
289
288
  // other option here already uses, rather than a repo-committed marker file
290
289
  // that would sit uncommitted or drift stale.
291
290
  const declareNoCi = has("declare-no-ci");
292
291
 
293
- // #365: every flag above is read by looking for its own name, so a name
292
+ // Every flag above is read by looking for its own name, so a name
294
293
  // nothing reads was never looked for — `--basee main` left `base` on its
295
294
  // default and this file returned a real, wrong verdict at exit 0/1. That is
296
295
  // the verdict the fleet gates PR-green on. Placed below the reads, per
297
- // arg.mjs, so `--base --quiet` keeps #169's "--base needs a value"; still
296
+ // arg.mjs, so `--base --quiet` keeps "--base needs a value"; still
298
297
  // above the first gh call, which is the next statement.
299
298
  //
300
299
  // `--workflow-file` is read here rather than where its value is first needed,
@@ -308,10 +307,10 @@ const workflowFileArg = arg("workflow-file");
308
307
 
309
308
  sweep();
310
309
 
311
- // #463: sweep() above only ever refuses a `--`-prefixed token, so a bare or
310
+ // sweep() above only ever refuses a `--`-prefixed token, so a bare or
312
311
  // single-dash stray rode along in silence — `--pr 42 basee main` ignored
313
312
  // `basee`/`main` and still compared against the default base, the same
314
- // fail-open harm #365 closed for a misspelled FLAG name. This file takes no
313
+ // fail-open harm sweep() closes for a misspelled FLAG name. This file takes no
315
314
  // positional of its own, so any leftover token is one.
316
315
  stray();
317
316
 
@@ -711,7 +710,7 @@ function requiredContexts(branchName) {
711
710
  // match the head, then take the newest survivor.
712
711
  //
713
712
  // Skipped entirely under no-ci: there is no workflow to bind a run to, and
714
- // asking anyway would spend the REST budget #262 is already tight on for a
713
+ // asking anyway would spend the already-tight REST budget on a
715
714
  // question this repo cannot answer either way.
716
715
  const reasons = [];
717
716
  let jobs = [];
@@ -758,12 +757,12 @@ if (noCi) {
758
757
  };
759
758
  // Recency is the primary key — a newer run always outranks an older one,
760
759
  // tied or not. The tie-break below fires ONLY when createdAt is equal to
761
- // the second: two runs GitHub started in the same instant (measured on PR
762
- // #1402, both 6 jobs green — one `cancelled`, one `completed`, and the
760
+ // the second: two runs GitHub started in the same instant (measured: both
761
+ // 6 jobs green — one `cancelled`, one `completed`, and the
763
762
  // stable sort below previously let API order pick the loser). Ranking
764
763
  // conclusion ahead of createdAt here would let an older completed run beat
765
764
  // a newer in-progress one on an unrelated, untied pair — a fresh
766
- // regression, not a fix (#1410 review) — so conclusion only ever compares
765
+ // regression, not a fix — so conclusion only ever compares
767
766
  // within a tie.
768
767
  const compareRuns = (x, y) => {
769
768
  const byCreatedAt = bySecond(y.createdAt).localeCompare(bySecond(x.createdAt));
@@ -783,7 +782,7 @@ if (noCi) {
783
782
  // done yet" — checked alone, not paired with a conclusion check.
784
783
  // An earlier version additionally required `r.conclusion === null`,
785
784
  // but live `gh run list --json conclusion` reports an empty string
786
- // `""` for a non-completed run, never `null` (#1566) — that extra
785
+ // `""` for a non-completed run, never `null` — that extra
787
786
  // check silently never matched, so a still-running run fell through
788
787
  // to the bottom tier below, indistinguishable from a failed/
789
788
  // cancelled one. `status !== "completed"` alone is both sufficient
@@ -873,7 +872,7 @@ if (noCi) {
873
872
  for (const j of jobs) {
874
873
  // `??` only falls through on null/undefined; gh reports an empty
875
874
  // string `""` for an in-progress job's conclusion (same shape as the
876
- // rank() tie-break bug this file fixed for #1566), so `??` alone
875
+ // rank() tie-break bug above), so `??` alone
877
876
  // would print the unreadable "job check is , not success". `||`
878
877
  // treats the empty string as absent too and falls through to status.
879
878
  if (j.conclusion !== "success") reasons.push(`job ${j.name} is ${j.conclusion || j.status}, not success`);
@@ -897,7 +896,7 @@ try {
897
896
  const cmpJson = tryRun("gh", ["api", "--hostname", host, `repos/${repoView.nameWithOwner}/compare/${base}...${prHead}`]);
898
897
  if (cmpJson !== null) {
899
898
  const cmp = JSON.parse(cmpJson);
900
- // Shaped like every other gh read here (#269), but fail-SOFT: a compare
899
+ // Shaped like every other gh read here, but fail-SOFT: a compare
901
900
  // reply without a numeric `behind_by` — a 404 body from the wrong host
902
901
  // or base is the live case — leaves `behind` null, this block's
903
902
  // documented unknown, instead of `undefined`, which JSON.stringify drops
@@ -1,6 +1,6 @@
1
1
  // Pure spend-model builder. No I/O and no clock read — board.mjs reads the
2
2
  // session's subagent transcripts and calls computeSpend(); every classification
3
- // and rollup lives here and is exercised by compute-spend.test.mjs (`node --test`).
3
+ // and rollup lives here.
4
4
  //
5
5
  // WHY cache_creation is the headline and cache_read is not: a fleet run reads
6
6
  // its cache an order of magnitude more than it writes it (one measured run:
@@ -11,7 +11,7 @@
11
11
 
12
12
  import { CELL_DEF } from "./ledger-grammar.mjs";
13
13
 
14
- // The implementer definitions #2129 retired — see classifyRole's `def` branch.
14
+ // The retired pre-cell implementer definitions — see classifyRole's `def` branch.
15
15
  const RETIRED_IMPLEMENTER_DEF = /^fleet-implementer(-alt)?$/;
16
16
 
17
17
  // A fleet agent's role is not recorded anywhere as a field — it has to be
@@ -21,7 +21,7 @@ const RETIRED_IMPLEMENTER_DEF = /^fleet-implementer(-alt)?$/;
21
21
  // run-team fixes them (`impl-<n>`, `fix-pr-<n>`, `review-pr-<n>`,
22
22
  // `finisher-pr-<n>`, `merge-bot-<n>`).
23
23
  //
24
- // TWO IDENTITY SIGNALS, NEVER ONE (#1505). `agentDefinition` is the agent
24
+ // TWO IDENTITY SIGNALS, NEVER ONE. `agentDefinition` is the agent
25
25
  // DEFINITION the dispatch recorded — `memory-housekeeper`,
26
26
  // `fleet-implementer-slow-high`, `fleet-review-verifier` — and `""` when it
27
27
  // recorded none. `memberName` is what the member was CALLED (`impl-387`,
@@ -33,7 +33,7 @@ const RETIRED_IMPLEMENTER_DEF = /^fleet-implementer(-alt)?$/;
33
33
  // happened to be supplied, and no rule could state which it meant.
34
34
  // That ambiguity is what booked a memory-system member dispatched as
35
35
  // `memory-housekeeper` but NAMED `brain-housekeeping` into the specialist
36
- // bucket, moving its session's review-spend headline by 22 points (#1505).
36
+ // bucket, moving its session's review-spend headline by 22 points.
37
37
  // Each rule now names the signal it actually means and both readers fill both
38
38
  // parameters from the same kind of value, so the asymmetry cannot come back by
39
39
  // one reader being taught something the other was not.
@@ -46,7 +46,7 @@ const RETIRED_IMPLEMENTER_DEF = /^fleet-implementer(-alt)?$/;
46
46
  // that way books as "other" whenever its description does not happen to say
47
47
  // "finish pr" too, moving the headline for runs already recorded.
48
48
  // member-record.mjs matches the same four names, and its comment carries the
49
- // measurement (#326).
49
+ // measurement.
50
50
  export function classifyRole(signals) {
51
51
  const def = String(signals?.agentDefinition ?? "");
52
52
  const name = canonicalMemberName(signals?.memberName);
@@ -57,7 +57,7 @@ export function classifyRole(signals) {
57
57
  //
58
58
  // Reads the member's IDENTITY — the recorded definition and the name — and
59
59
  // never `hay`. The definition is the authoritative half and the whole of
60
- // #1505: a dispatch that recorded `memory-housekeeper` books memory whatever
60
+ // the fix: a dispatch that recorded `memory-housekeeper` books memory whatever
61
61
  // it called the member, so the eleven rows that shared one definition across
62
62
  // three buckets collapse to one. The NAME stays a signal beside it because a
63
63
  // definition that says nothing about the role is a real category here rather
@@ -82,7 +82,7 @@ export function classifyRole(signals) {
82
82
  if (/^size (candidate|ticket)/.test(desc.toLowerCase())) return "sizing";
83
83
 
84
84
  // Everything else at depth ≥ 1 is a reviewer's fan-out. This must stay AHEAD of
85
- // the member patterns below: specialists are named things like "Review PR 539
85
+ // the member patterns below: specialists are named things like "Review PR <n>
86
86
  // correctness", which would otherwise book half the fan-out as reviewer spend.
87
87
  if (Number(signals?.spawnDepth ?? 0) >= 1) return "specialist";
88
88
 
@@ -92,16 +92,16 @@ export function classifyRole(signals) {
92
92
  // nested review host, so its fan-out arrives at depth 0 — measured 2026-09-16
93
93
  // on the live corpus, 466 of 477 `fleet-review-*` rows — and falls straight
94
94
  // through to the description patterns below, which is precisely the
95
- // "Review PR 539 correctness" misread the depth check above exists to
95
+ // "Review PR <n> correctness" misread the depth check above exists to
96
96
  // prevent. Before this branch one definition, `fleet-review-verifier`, was
97
97
  // split across four buckets on nothing but prompt wording: 211 other, 172
98
- // reviewer, 20 finisher, 2 merge-bot (#1486).
98
+ // reviewer, 20 finisher, 2 merge-bot.
99
99
  //
100
100
  // Matched against `def` ALONE — never the member's name, and never the `hay`
101
101
  // blend the patterns below use. A fleet member's own dispatch prompt says what
102
102
  // it is, so these names occur in description prose constantly, and a member
103
103
  // that merely mentions a definition was not dispatched as one. `^`-anchored:
104
- // omp's own registry is bare-name/unnamespaced (ADR 0014), so the recorded
104
+ // omp's own registry is bare-name/unnamespaced, so the recorded
105
105
  // definition is always the bare form.
106
106
  //
107
107
  // The review side is a PREFIX and the implementer side is EXACT, deliberately:
@@ -111,16 +111,16 @@ export function classifyRole(signals) {
111
111
  // (`fleet-implementer-<role>-<level>`, ledger-grammar.mjs): a name outside
112
112
  // it is no implementer definition, however it starts.
113
113
  //
114
- // Except the pre-cell pair #2129 deleted, `fleet-implementer` and
114
+ // Except the retired pre-cell pair, `fleet-implementer` and
115
115
  // `fleet-implementer-alt`, matched for the same reason the finisher branch
116
116
  // keeps old spellings: deliberate compatibility with recorded history.
117
- // Measured on docs/metrics/member-outcomes.tsv at #2129: 20 of the 303 rows
117
+ // Measured on docs/metrics/member-outcomes.tsv at their retirement: 20 of the 303 rows
118
118
  // under those two definitions carried no `impl-` name (`Impl1133`,
119
119
  // `FixPr1568`, …) and booked `implementer` off the definition alone — a
120
120
  // re-scrape of their sessions would have moved them to "other".
121
121
  //
122
122
  // One definition under that prefix is NOT fan-out: `fleet-review-runner`
123
- // (#1802) is the member that HOLDS an omp review — dispatched as
123
+ // is the member that HOLDS an omp review — dispatched as
124
124
  // `review-pr-<n>`, the reviewer the name branch below would book — so it is
125
125
  // matched EXACTLY, ahead of the prefix. Its own fan-out arrives at depth ≥ 1
126
126
  // and is booked "specialist" by the depth check above.
@@ -129,14 +129,14 @@ export function classifyRole(signals) {
129
129
  if (CELL_DEF.test(def) || RETIRED_IMPLEMENTER_DEF.test(def)) return "implementer";
130
130
 
131
131
  // The dispatch NAME is checked alone, in this same fixed order, before the
132
- // prose blend below ever runs (#1506). Both readers now hand a canonical
132
+ // prose blend below ever runs. Both readers now hand a canonical
133
133
  // omp/run-team name (`impl-<n>`, `fix-pr-<n>`, `finisher-<n>`, `finish-<n>`,
134
134
  // `review-pr-<n>`, `merge-bot-<n>`) straight through as `memberName`, and
135
135
  // that name is a MORE PRECISE signal than the member's own free-text
136
136
  // description — concatenating them into one `hay` before matching let a
137
137
  // description's prose out-rank the name whenever the fixed branch order
138
138
  // happened to check an earlier pattern the prose satisfied first. Measured
139
- // live: `finisher-1380` described as "Fix PR 1380 review findings." matched
139
+ // live: `finisher-<n>` described as "Fix PR <n> review findings." matched
140
140
  // the reviewer branch on "review" in the prose before the finisher branch
141
141
  // ever saw the name that actually says what the member is; `merge-bot-12`
142
142
  // described with "...review findings" misread the same way as finisher.
@@ -163,10 +163,10 @@ function roleFromNamePatterns(hay) {
163
163
  // one and its cache writes fall through to "other", moving the review-side
164
164
  // headline — the one number anyone acts on — by several points.
165
165
  //
166
- // `resolve-pr-<n>` joins the same bucket (#1250): it is a controller
166
+ // `resolve-pr-<n>` joins the same bucket: it is a controller
167
167
  // dispatch against an ALREADY-OPEN PR, not new ticket work — measured
168
- // meta.json descriptions "Resolve conflict on PR 1232" and "Rebase and
169
- // resolve conflicts for PR #1310", the same rebase/conflict-resolver shape
168
+ // meta.json descriptions "Resolve conflict on PR <n>" and "Rebase and
169
+ // resolve conflicts for PR #<n>", the same rebase/conflict-resolver shape
170
170
  // `run-team/SKILL.md` calls "a rebase-resolver" sent into an open PR's
171
171
  // worktree. It carries no ticket, no dispatch counter and no new-work verb —
172
172
  // only a PR number — so it is remediation on that PR's path to merge,
@@ -176,8 +176,8 @@ function roleFromNamePatterns(hay) {
176
176
  //
177
177
  // Only the NAME form `resolve-pr-` joins the alternation, deliberately
178
178
  // narrower than the `review pr`/`fix pr` prose forms beside it: the two
179
- // real meta.json descriptions above ("Resolve conflict on PR 1232",
180
- // "Rebase and resolve conflicts for PR #1310") never contain the bare
179
+ // real meta.json descriptions above ("Resolve conflict on PR <n>",
180
+ // "Rebase and resolve conflicts for PR #<n>") never contain the bare
181
181
  // words "resolve pr" adjacently, so a `resolve pr` prose alternative would
182
182
  // be untested reach rather than a measured pattern — and "resolve" is
183
183
  // common enough in unrelated prose (a finisher applying reviewer
@@ -205,7 +205,7 @@ export const CANONICAL_MEMBER_NAME_PREFIXES = "impl|fix-pr|finish(?:er)?|review-
205
205
  // `Review-pr-1449`, `ReviewPR77`, `FinisherPr1567b`, all in
206
206
  // docs/metrics/member-outcomes.tsv) — rewritten to the lower-kebab form every
207
207
  // name pattern in this file and in member-record.mjs's parseMemberName is
208
- // written against (#2396). omp task names are free-form, so nothing upstream
208
+ // written against. omp task names are free-form, so nothing upstream
209
209
  // guarantees the kebab spelling, and an unmatched spelling lost both its role
210
210
  // and its tier-outcomes.tsv join key.
211
211
  //
@@ -264,7 +264,7 @@ export function computeSpend({ agents = [], topN = 8 } = {}) {
264
264
  .sort((a, b) => b.cacheWrite - a.cacheWrite);
265
265
 
266
266
  // `model` rides along only where the caller's agent object supplied one
267
- // (#1716) — an agent with no `model` key keeps its payload exactly as it
267
+ // — an agent with no `model` key keeps its payload exactly as it
268
268
  // was rather than gaining a null column.
269
269
  const top = [...agents]
270
270
  .sort((a, b) => (b.cacheWrite ?? 0) - (a.cacheWrite ?? 0))
@@ -13,7 +13,7 @@
13
13
  // are chosen so the caller's selection is a clean expression over them.
14
14
  //
15
15
  // `classify` and `computeStats` are pure and exported so the classifier is
16
- // unit-tested (diff-stats.test.mjs) without a live `gh`; the CLI runs only when
16
+ // unit-tested without a live `gh`; the CLI runs only when
17
17
  // this file is executed directly.
18
18
 
19
19
  import { execFileSync } from "node:child_process";
@@ -60,7 +60,7 @@ export function classify(p) {
60
60
  //
61
61
  // `changedFiles` is the PR's UNCAPPED file count, and it is a second argument
62
62
  // because `files` is capped: `gh pr view --json files` pages at 100 and exits 0
63
- // with no warning (measured on microsoft/vscode#329568 — `files` 100 against
63
+ // with no warning (measured on a 124-file PR — `files` 100 against
64
64
  // `changedFiles` 124). Every fact below is then computed off a short list with
65
65
  // nothing in the blob contradicting it: `loc` under-counts, `docsOnly` can flip
66
66
  // because the src files fell off the end, and `paths` is what `review-core.mjs`
@@ -100,9 +100,9 @@ export function computeStats(files, changedFiles) {
100
100
  // --- CLI (runs only when executed directly, never on import) ---------------
101
101
 
102
102
  // die()/numArg() shared with the other fleet scripts — see arg.mjs for the
103
- // fail-open (#61/#169/#878) and pipe-safety (#176/#328) rationale. `--pr` is
103
+ // fail-open and pipe-safety rationale. `--pr` is
104
104
  // the only flag read here, and numArg() rather than arg() because this file
105
- // was the live half of #840's defect: the `if (!pr)` below caught a trailing
105
+ // was the live half of a defect: the `if (!pr)` below caught a trailing
106
106
  // `--pr` — `undefined` is falsy — but never a non-numeric one, so `--pr abc`
107
107
  // reached `gh pr view abc` and printed `{"pr":null,…}` at exit 0. Measured
108
108
  // against a stub gh that answers, which is what a real one does for `abc`:
@@ -111,7 +111,7 @@ export function computeStats(files, changedFiles) {
111
111
  const die = makeDie(NAME);
112
112
  const { numArg, sweep, stray } = defineFlags(die, { flags: { pr: "value" } });
113
113
 
114
- // #932. The one truncation rule for the raw gh value this script quotes into a
114
+ // The one truncation rule for the raw gh value this script quotes into a
115
115
  // refusal: clip behind a visible marker, and only when the value was really
116
116
  // clipped. Unmarked — `raw.trim().slice(0, 120)`, what the die below used to do
117
117
  // — the length quoted is gh's, not this script's, so a 269 KB portal page and a
@@ -119,7 +119,7 @@ const { numArg, sweep, stray } = defineFlags(die, { flags: { pr: "value" } });
119
119
  // diagnostic from a cut one.
120
120
  //
121
121
  // HEAD, not tail, measured on this site's own payload rather than imported from
122
- // #638/PR #931's fix for the same unmarked clip in ledger.mjs. Those sites clip
122
+ // the fix for the same unmarked clip in ledger.mjs. Those sites clip
123
123
  // STDERR, where warnings lead and the cause lands last; `run()` above passes no
124
124
  // `stdio`, so execFileSync forwards the child's stderr and returns stdout ALONE
125
125
  // — this clips stdout. Real gh (2.100.0) never puts non-JSON there: a missing
@@ -139,7 +139,7 @@ const { numArg, sweep, stray } = defineFlags(die, { flags: { pr: "value" } });
139
139
  // The marker counts against `n`, so `cut(s).length <= n` for every `n >=
140
140
  // MARKER.length` — the only regime the one call site below exercises, since
141
141
  // `cut` is module-private and always called with the default `n = 120`. This
142
- // is the one place it differs from ci-state.mjs's `cut` (#1479), whose marker
142
+ // is the one place it differs from ci-state.mjs's `cut`, whose marker
143
143
  // sits past its `n`: `s.slice(0, n)` there appends the marker unconditionally,
144
144
  // measuring 133 characters against ci-state.mjs's own 120-char cap — and this
145
145
  // script's stderr is read by review-core.mjs's snapshot agent, markdown fed to a
@@ -167,7 +167,7 @@ function run(cmd, args) {
167
167
  // measured 7,700 B becoming 15,454 B, into review-core.mjs's snapshot agent,
168
168
  // which is markdown read by a model. `e.message` is the same string, not a
169
169
  // fallback — Node builds it as `Command failed: <cmd>\n<stderr>`. Three
170
- // disjoint shapes: Node-aborted (ENOENT/ENOBUFS), signal, exit (#176).
170
+ // disjoint shapes: Node-aborted (ENOENT/ENOBUFS), signal, exit.
171
171
  die(
172
172
  `${cmd} failed: ${e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)}`,
173
173
  );
@@ -181,18 +181,18 @@ function main() {
181
181
  // file's own refusal and malformed is numArg()'s, per arg.mjs.
182
182
  const pr = numArg("pr");
183
183
  if (pr === null) die("usage: diff-stats.mjs --pr <number>");
184
- // #365, weaker here for the same reason as pr-overlap.mjs: `--pr` is
184
+ // The misspelled-flag sweep, weaker here for the same reason as pr-overlap.mjs: `--pr` is
185
185
  // required, so a misspelled `--prr 5` already fell through to the usage die
186
186
  // above. What was silently ignored at exit 0 is a stray riding along with a
187
187
  // good `--pr` (`--pr 5 --base main`), and that is what this closes.
188
188
  //
189
189
  // Inside main(), never at module scope: computeStats() is imported by
190
- // diff-stats.test.mjs and select-dimensions.test.mjs, and a module-scope
190
+ // the test suite, and a module-scope
191
191
  // sweep would read the IMPORTER's argv. (review-pr runs this script as a
192
192
  // CLI subprocess with its own argv, so it is not one of those importers.)
193
- // Below the guard above, so `--pr --json` keeps #169's "--pr needs a value".
193
+ // Below the guard above, so `--pr --json` keeps "--pr needs a value".
194
194
  sweep();
195
- // #463: sweep() only refuses a `--`-prefixed token; a bare or single-dash
195
+ // sweep() only refuses a `--`-prefixed token; a bare or single-dash
196
196
  // one (`--pr 42 basee`) rode along in silence the same way. This file
197
197
  // takes no positional, so any leftover token is a stray.
198
198
  stray();
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env node
2
- // The heartbeat. #3's item 2, filed as #357: the ONE fleet-tick trigger that
2
+ // The heartbeat: the ONE fleet-tick trigger that
3
3
  // survives a fully drained queue.
4
4
  //
5
5
  // fleet-tick.mjs computes the deficit but only when something invokes it, and
6
6
  // every other invocation is a wake: a member report, a label, a CI run ending.
7
7
  // A drained fleet emits no wakes at all — no implementer completions, no merge
8
- // activity — so nothing calls the tick and the stall is silent again, which is
9
- // the state #3 was filed about. This script is the level-check that needs no
8
+ // activity — so nothing calls the tick and the stall is silent again. This
9
+ // script is the level-check that needs no
10
10
  // event: it holds the controller's turn for an interval and then tells it to
11
11
  // run the tick.
12
12
  //
@@ -22,7 +22,7 @@
22
22
  //
23
23
  // So the heartbeat is not a Monitor, not a cron entry and not a paragraph of
24
24
  // prose. A cron entry that ran the reconcile would print its rows to nobody:
25
- // the tick reads the run for itself (#1803), but only the controller can act
25
+ // the tick reads the run for itself, but only the controller can act
26
26
  // on what it prints. An external scheduler can only WAKE the controller,
27
27
  // which is the one thing the measurement above says it cannot be trusted to
28
28
  // do.
@@ -91,7 +91,7 @@ const OPTIONS = {
91
91
  base: { type: "string", default: "300" },
92
92
  // Single source of truth in fleet-state.mjs — assessBeat's own fallback
93
93
  // freshness window for a busy run's `ticked` mark is this same number
94
- // (#1597 follow-up), and a duplicated "1200" here is the drift the module
94
+ // too, and a duplicated "1200" here is the drift the module
95
95
  // header's "never a copy of it" rule exists to close.
96
96
  ceiling: { type: "string", default: String(DEFAULT_CEILING_S) },
97
97
  multiplier: { type: "string", default: "2" },
@@ -100,7 +100,7 @@ const OPTIONS = {
100
100
  // the 5-6 minute CI cycle run-merge-bot.md's CI wait rule states. Raise
101
101
  // it only together with the tool call's own timeout.
102
102
  hold: { type: "string", default: "240" },
103
- // The deliberate stop, #1597. No default and no boolean spelling: the flag
103
+ // The deliberate stop. No default and no boolean spelling: the flag
104
104
  // IS the reason, and a `--stop` that recorded an empty string would be the
105
105
  // abrupt-death case wearing a deliberate stop's clothes — a reader would
106
106
  // report a recorded reason and then print nothing for it.
@@ -170,7 +170,7 @@ function args() {
170
170
  return { base, ceiling, multiplier, hold, stop: values.stop?.trim(), state: values.state || statePath(NAME) };
171
171
  }
172
172
 
173
- // The mark, #1597: when this beat was seen and the interval that was in effect
173
+ // The mark: when this beat was seen and the interval that was in effect
174
174
  // when it was. Built here rather than inline at each write so the two writes
175
175
  // below cannot disagree about the shape of a key only this script owns.
176
176
  //
@@ -241,7 +241,7 @@ function main() {
241
241
  // A failed write is itself a fire. With nothing persisting the remainder,
242
242
  // every invocation reads the same elapsed total, holds the same seconds and
243
243
  // prints the same remainder: the interval can never complete, so fleet-tick
244
- // is never run at all — #357's own defect, reached through a line that reads
244
+ // is never run at all — the drained-queue stall itself, reached through a line that reads
245
245
  // like a working heartbeat. Beating too often is the harmless direction;
246
246
  // never beating is the one this script exists to prevent.
247
247
  //
@@ -249,7 +249,7 @@ function main() {
249
249
  // so on stderr, this process keeps beating, and a reader that never sees a
250
250
  // mark reports a stall it cannot explain — loud and wrong in the safe
251
251
  // direction — rather than this script dying to protect its own telemetry.
252
- // A liveness mark that killed the beat it measures would be #357's defect
252
+ // A liveness mark that killed the beat it measures would be that same stall
253
253
  // wearing a new hat.
254
254
  const done = reached || !persisted;
255
255
 
@@ -13,7 +13,7 @@
13
13
  // elapsed fleet-heartbeat only. Seconds already held toward the current
14
14
  // interval, because no harness lets one command block long enough
15
15
  // to serve a twenty-minute interval in a single call.
16
- // beat fleet-heartbeat only (#1597). The liveness mark: when the beat
16
+ // beat fleet-heartbeat only. The liveness mark: when the beat
17
17
  // was last seen, the interval that was in effect when it was, and
18
18
  // a deliberate stop's reason if one was recorded. Written by the
19
19
  // heartbeat and by nothing else — fleet-tick READS it at the start
@@ -37,10 +37,10 @@ import { spawnSync } from "node:child_process";
37
37
  import { dirname, join } from "node:path";
38
38
  import { workspaceDirFromGitCommonDir } from "./git-env.mjs";
39
39
 
40
- // The filename, in one place, because #1597 gave this file a SECOND resolver.
40
+ // The filename, in one place, because the liveness mark gave this file a SECOND resolver.
41
41
  // board.mjs already resolves the run's workspace for itself — it has to, since
42
42
  // its own `canonicalise` opt-in is what keeps a symlinked route from deriving
43
- // a second port (#1582) — so it reaches the state file by joining onto the
43
+ // a second port — so it reaches the state file by joining onto the
44
44
  // `.fleet` directory it already holds rather than re-running the probe below.
45
45
  // What it must NOT do is spell `heartbeat.json` a second time: a filename in
46
46
  // two places is the drift this module's header exists to prevent, and a
@@ -59,11 +59,11 @@ export function stateFileIn(fleetDir) {
59
59
  // This is ledger.mjs's defaultLedgerPath() resolution applied to a second file
60
60
  // for the same reason (there, a cwd-local ledger silently degraded the
61
61
  // duplicate-filing guard). The third file this comment used to predict arrived
62
- // with #1656 — board.mjs's resolveCockpitInstance() — so the resolution itself
62
+ // as board.mjs's resolveCockpitInstance(), so the resolution itself
63
63
  // moved, as promised, though into git-env.mjs beside gitEnv() rather than into
64
64
  // this module: board.mjs and ledger.mjs both already import that one, and a
65
65
  // cockpit reaching into the heartbeat's state module for a path rule would be
66
- // a stranger dependency than either has now (#1658). Only the filename and the
66
+ // a stranger dependency than either has now. Only the filename and the
67
67
  // warning below are this caller's own.
68
68
  export function statePath(name) {
69
69
  // GIT_DIR and GIT_WORK_TREE scrubbed, never inherited: an ambient GIT_DIR
@@ -75,10 +75,10 @@ export function statePath(name) {
75
75
  // run-merge-bot.md performs on the identical command in shell (`env -u
76
76
  // GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir`); spelled as an
77
77
  // env object here because there is no shell to spell it in.
78
- // Migrating this inline scrub to gitEnv() — imported in this file since
79
- // #1658 for the path rule above, not for the env — stays out of scope: it is
78
+ // Migrating this inline scrub to gitEnv() — imported in this file
79
+ // for the path rule above, not for the env — stays out of scope: it is
80
80
  // recorded with its own measurement and its own behavioural fixture in
81
- // ambient-git-vars-mjs-prose.test.mjs's MJS_LEGACY_INLINE list.
81
+ // the test suite's MJS_LEGACY_INLINE list.
82
82
  const env = { ...process.env };
83
83
  delete env.GIT_DIR;
84
84
  delete env.GIT_WORK_TREE;
@@ -207,14 +207,14 @@ export function readState(path, name) {
207
207
  // keeping.
208
208
  //
209
209
  // The write is a sibling temp file renamed over the target, ledger.mjs save()'s
210
- // convention, because the readers do not hold still for it (#2349). A plain
210
+ // convention, because the readers do not hold still for it. A plain
211
211
  // writeFileSync truncates and then writes, and readState() maps the empty or
212
212
  // half-written file a reader can land on to the fresh, no-mark state on
213
213
  // purpose — so a reader racing a live beat read "no mark", and ledger.mjs
214
214
  // rotate, which refuses only while a mark is beating, moved a live
215
215
  // controller's ledger. rename is atomic on POSIX: a reader sees the whole old
216
216
  // file or the whole new one. The temp name carries the pid for the reason
217
- // ledger.mjs gives (#531): two scripts write this file, and a shared temp name
217
+ // ledger.mjs gives: two scripts write this file, and a shared temp name
218
218
  // lets one rename the other's out from under it. A temp that never made it
219
219
  // into place is removed rather than left to accumulate, one per failed
220
220
  // invocation, beside the file it failed to replace.
@@ -253,7 +253,7 @@ export function writeState(path, name, prev, patch) {
253
253
  }
254
254
 
255
255
  // --------------------------------------------------------------------------
256
- // READING THE MARK — #1597. The rule, and the wording, in one place.
256
+ // READING THE MARK. The rule, and the wording, in one place.
257
257
  //
258
258
  // Two readers consume this key and neither of them writes it: fleet-tick at
259
259
  // the start of a run (so a run that died overnight announces itself even when
@@ -307,7 +307,7 @@ export const DEFAULT_CEILING_S = 1200;
307
307
  // drains (SKILL.md: "beat when there is nothing to do"), so a
308
308
  // busy stretch that outlasts `beat`'s own grace window is not a dead
309
309
  // run; fleet-tick's own edge-triggered invocations are the other
310
- // liveness signal for exactly that case (#1597 follow-up).
310
+ // liveness signal for exactly that case.
311
311
  // stopped a reason was recorded. Reported whatever the age, because a
312
312
  // recorded stop IS the end of the run and waiting for it to go
313
313
  // stale first would sit on the one report that knows its cause.
@@ -354,8 +354,8 @@ export function isStalled(verdict) {
354
354
  // documented values) but not for every value the CLI guard actually accepts:
355
355
  // fleet-heartbeat.mjs's own guard refuses `--ceiling < --base` the same way
356
356
  // this file refuses other invalid shapes, and mirroring that refusal onto
357
- // sub-60s `--base`/`--ceiling` was the first fix tried for #1735 — until
358
- // fleet-heartbeat.test.mjs turned out to lean on 2s/3s/8s/9s/64s intervals
357
+ // sub-60s `--base`/`--ceiling` was the first fix tried for the "0m" floor —
358
+ // until the heartbeat's own test suite turned out to lean on 2s/3s/8s/9s/64s intervals
359
359
  // throughout, deliberately, to keep its real `Atomics.wait` holds fast. A
360
360
  // CLI-level refusal would force that whole suite onto minute-plus real
361
361
  // holds for no behavioural gain, so the fix lives here instead: a value
@@ -363,7 +363,7 @@ export function isStalled(verdict) {
363
363
  // to "0m" is what read as a division-by-zero defect, not the sub-minute
364
364
  // input itself.
365
365
  //
366
- // #1735 only moved the floor for values UNDER 60s. A 60-119s value still
366
+ // That fix only moved the floor for values UNDER 60s. A 60-119s value still
367
367
  // fell on the whole-minutes branch, so a 90-119s interval floors to "1m"
368
368
  // while its own overdue remainder (usually still under 60s) prints in
369
369
  // seconds — the line's three numbers stop reconciling the moment any of