@feigi/fleet-ctl 3.24.1 → 3.24.3

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/board.mjs CHANGED
@@ -13,12 +13,12 @@
13
13
  //
14
14
  // That transcript tree is keyed by PROJECT DIRECTORY, not by session, and one
15
15
  // directory can hold several sessions at once. `serve` therefore resolves ONE
16
- // session's transcript directory and keeps it for its whole life (#1583) — see
16
+ // session's transcript directory and keeps it for its whole life — see
17
17
  // spendDirPin() below — rather than re-picking the newest on every tick and
18
18
  // alternating between two live runs' numbers in silence.
19
19
  //
20
20
  // LIMITATION, stated rather than solved: the session it keeps is whichever
21
- // FIRST writes a transcript at or after the pin's own construction (#1679).
21
+ // FIRST writes a transcript at or after the pin's own construction.
22
22
  // Before that, a session that was already active when the pin was built —
23
23
  // this run's own, mid-EACCES-fault, or a genuinely previous run's — is never
24
24
  // latched; the pin keeps re-asking findSubagentsDir() every tick instead,
@@ -26,7 +26,7 @@
26
26
  // freezing the panel for the server's whole life. What is not solved: two
27
27
  // sessions that BOTH start writing after the pin exists, in the same project
28
28
  // directory, are still indistinguishable — the board is scoped to a
29
- // workspace and a workspace does not know that (#39) — so the first of them
29
+ // workspace and a workspace does not know that — so the first of them
30
30
  // to pass the newest-transcript check wins and keeps winning. `--spend-dir
31
31
  // <path>` is how an operator names the right one: it overrides the
32
32
  // heuristic outright.
@@ -40,13 +40,13 @@ import {
40
40
  import { makeDie, defineFlags } from "./arg.mjs";
41
41
  import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
42
42
  import { mergedReadPrs } from "./compute-board.mjs";
43
- // #1597: the heartbeat's liveness mark, read here and never written. The
43
+ // The heartbeat's liveness mark, read here and never written. The
44
44
  // cockpit is a READER of that key — the heartbeat is its only writer — and it
45
45
  // reaches the file through the module that owns the filename rather than
46
46
  // spelling `heartbeat.json` a second time. The PATH still comes from this
47
47
  // file's own resolveCockpitInstance(), not from statePath(): that probe is
48
48
  // already run once per launch here, with the `canonicalise` opt-in only this
49
- // caller takes (#1582), and a second probe could answer differently.
49
+ // caller takes, and a second probe could answer differently.
50
50
  import { readState, stateFileIn } from "./fleet-state.mjs";
51
51
  import { fileURLToPath } from "node:url";
52
52
  import { isCLI } from "./is-cli.mjs";
@@ -57,7 +57,7 @@ import { inspect } from "node:util";
57
57
  const NAME = "board";
58
58
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
59
59
  // die()/arg()/has() shared with the other fleet scripts — see arg.mjs for
60
- // the fail-open (#61/#169/#364) and pipe-safety (#176/#328/#363) rationale.
60
+ // the fail-open and pipe-safety rationale.
61
61
  const die = makeDie(NAME);
62
62
  const { arg, has, sweep, stray } = defineFlags(die, {
63
63
  flags: {
@@ -78,7 +78,7 @@ const { arg, has, sweep, stray } = defineFlags(die, {
78
78
  // nothing after it silently read the DEFAULT ledger file instead of the one
79
79
  // asked for.
80
80
  //
81
- // #468: a guard used to fire only where the flag was actually READ, and that
81
+ // A guard used to fire only where the flag was actually READ, and that
82
82
  // was not every subcommand — `port` and `open` are USED in serve() alone, so
83
83
  // `build --port` (trailing), `build --port abc` and `build --open=1` were all
84
84
  // IGNORED at exit 0 rather than refused. main() now calls argPort()/
@@ -89,14 +89,14 @@ const { arg, has, sweep, stray } = defineFlags(die, {
89
89
  // same as before this fix: the guard checks the flag's SHAPE, not whether
90
90
  // this subcommand has a use for it. `ledger`/`prev`/`spend-since`/`interval`
91
91
  // were already read on the build path and already refused there.
92
- // #1092: that last claim held for `ledger`/`spend-since`/`interval`, not for
92
+ // That last claim held for `ledger`/`spend-since`/`interval`, not for
93
93
  // `prev` — `prev` was read on `build` alone, and serve() never read it at
94
94
  // all. Hoisted in main() below, next to argPort()/has("open").
95
95
 
96
- // #1546: the "is this a plain JSON object" predicate and its kind word, one
96
+ // The "is this a plain JSON object" predicate and its kind word, one
97
97
  // copy for the reads in this file that reject a parsed-but-wrong payload
98
98
  // WHOLE — gather's `--prev` payload, gather's per-entry `tickets[i]` check,
99
- // and readMerged()'s `data.repository` (#1840). Each carried its own inline
99
+ // and readMerged()'s `data.repository`. Each carried its own inline
100
100
  // copy of both halves before, which is three places for one policy to drift in.
101
101
  //
102
102
  // TWO functions and not one, because `typeof` alone cannot name the fault the
@@ -118,10 +118,10 @@ function jsonKind(v) {
118
118
  return v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
119
119
  }
120
120
 
121
- // #366: `Number(x) || default` treated a garbage --port/--interval exactly
121
+ // `Number(x) || default` treated a garbage --port/--interval exactly
122
122
  // like an absent one — "abc" is NaN, NaN is falsy, so it silently became the
123
123
  // default with no refusal. Same silent-fallback class as arg()'s own comment
124
- // above and #361's --spend-since guard. `interval` is read from argv in two
124
+ // above and the --spend-since guard. `interval` is read from argv in two
125
125
  // places (serve(), and gather()'s build payload); both call argInterval() so
126
126
  // the check lives once, not as two copies that can drift apart. Neither
127
127
  // guard runs on an already-typed value a caller passed in-process — arg()
@@ -137,8 +137,8 @@ function argPort() {
137
137
  // millisecond delay: hand it more and Node clamps the delay to 1ms with only a
138
138
  // TimeoutOverflowWarning, so `--interval 3000000` (34 days) turns the rebuild
139
139
  // loop into a spin loop shelling out to gh hundreds of times a second — the
140
- // inverse of what was asked, announced by nothing the board prints (#435
141
- // review). 2147483647ms / 1000, floored, is the last WHOLE second that fits;
140
+ // inverse of what was asked, announced by nothing the board prints.
141
+ // 2147483647ms / 1000, floored, is the last WHOLE second that fits;
142
142
  // the ceiling is a hair under that in fractional seconds, which nobody types.
143
143
  function argInterval() {
144
144
  const raw = arg("interval");
@@ -164,15 +164,15 @@ function argInterval() {
164
164
  // `since`. 1e12 ms is 2001-09-09, below any real run; a future boundary
165
165
  // matches nothing at all.
166
166
  //
167
- // #1076: pulled out of gather() into its own function, like argPort()/
167
+ // Pulled out of gather() into its own function, like argPort()/
168
168
  // argInterval() above, so main() can call it too (below) ahead of the
169
169
  // build/serve dispatch and ahead of both branches' stray() call — before
170
170
  // this fix the read sat inline inside gather(), below every stray() call on
171
171
  // every path that reaches it, so a trailing `--spend-since` ahead of a stray
172
172
  // positional refused under stray()'s generic wording instead of this one.
173
173
  // gather() still calls this itself, in the same spot, so nothing about WHEN
174
- // it validates changes for a caller that skips main() (same reasoning #468
175
- // gives for argPort()/has("open") staying in serve() too).
174
+ // it validates changes for a caller that skips main() (same reasoning as
175
+ // for argPort()/has("open") staying in serve() too).
176
176
  function argSpendSince() {
177
177
  const sinceRaw = arg("spend-since");
178
178
  if (sinceRaw === null) return null;
@@ -183,7 +183,7 @@ function argSpendSince() {
183
183
  return sinceMs;
184
184
  }
185
185
 
186
- // #1583: the operator's override for the session heuristic (findSubagentsDir()
186
+ // The operator's override for the session heuristic (findSubagentsDir()
187
187
  // below). A PATH, so there is no range or magnitude to check the way
188
188
  // --spend-since and --interval have one — every malformed SHAPE this flag can
189
189
  // take is already arg()'s: a trailing `--spend-dir`, an empty or whitespace
@@ -191,7 +191,7 @@ function argSpendSince() {
191
191
  // What this read buys is that all four refuse under THIS flag's name instead
192
192
  // of stray()'s generic "unexpected argument", and they do so before gather()
193
193
  // shells out to anything — which is what declaring it in the flag table above
194
- // and calling it from main() below are for, exactly as #1076 did for
194
+ // and calling it from main() below are for, exactly as for
195
195
  // --spend-since. A named read rather than a bare arg() at each call site so
196
196
  // the flag is spelled in one place and this reasoning has a home.
197
197
  //
@@ -213,10 +213,11 @@ function argSpendDir() {
213
213
  }
214
214
 
215
215
  // Node's default stdout cap is 1 MiB and a capped child read FAILS past it
216
- // rather than truncating (#807). Here that failure is indistinguishable from an
216
+ // rather than truncating. Here that failure is indistinguishable from an
217
217
  // unreachable tool: the read degrades to the caller's empty default and the
218
218
  // cockpit is served a BLANK board at HTTP 200 with only a stderr line — the
219
- // #246 symptom, which #803 moved up from the pipe buffer rather than removed.
219
+ // same blank-board symptom the old pipe-buffer limit produced, which the raised
220
+ // ceiling moved up rather than removed.
220
221
  // The ledger is append-mostly and shared by every fleet script, so the ceiling
221
222
  // arms itself over the life of a run and gives no second warning. Bounded, not
222
223
  // Infinity: a runaway child should still be stopped rather than allowed to
@@ -227,22 +228,22 @@ function argSpendDir() {
227
228
  // tryRun discards — so a fix applied only here would leave that one uncapped.
228
229
  const READ_OPTS = { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 };
229
230
 
230
- // #1713: every child read in this file is ASYNCHRONOUS, and that is
231
+ // Every child read in this file is ASYNCHRONOUS, and that is
231
232
  // load-bearing rather than stylistic. serve() ticks on a timer inside the same
232
233
  // process that answers HTTP, so a SYNCHRONOUS read holds the event loop for as
233
234
  // long as the child runs — measured at 4.72–4.91s for one board — and during
234
235
  // that window this cockpit answers nothing at all. A relaunch's identity probe
235
236
  // (PROBE_TIMEOUT_MS, one retry, ~2s in total) landing inside it therefore got
236
237
  // no answer, read the port as foreign, and started a SECOND cockpit on this
237
- // workspace's state directory: the duplicate #1585/#1660 exist to prevent,
238
+ // workspace's state directory: the duplicate the launch handshake and the identity stub exist to prevent,
238
239
  // reached through timing rather than through a missing handshake. The browser
239
240
  // page stalled for the same reason and the same duration, every tick.
240
241
  //
241
242
  // One thing execFileSync did that this has to keep doing by hand: given no
242
243
  // `stdio` of its own it re-emits the child's captured stderr onto this
243
244
  // process's stderr (node's own `process.stderr.write(ret.stderr)`) BEFORE it
244
- // throws. That single oversized write is the subject of board-cli.test.mjs's
245
- // #807/#363 flood row, so it is spelled out below — and on both arms, because
245
+ // throws. That single oversized write is the subject of a flood row in the CLI tests,
246
+ // so it is spelled out below — and on both arms, because
246
247
  // the sync one wrote whether or not it went on to throw.
247
248
  //
248
249
  // This never throws; a failure is REPORTED in the record, in the field names
@@ -276,8 +277,8 @@ async function tryRun(cmd, args) {
276
277
  return r.stdout;
277
278
  }
278
279
 
279
- // #1714: `serve --open`'s browser launcher, one per supported platform (ADR
280
- // 0009). macOS ships `open`. Linux has no single program, but `xdg-open` is
280
+ // `serve --open`'s browser launcher, one per supported platform.
281
+ // macOS ships `open`. Linux has no single program, but `xdg-open` is
281
282
  // the freedesktop one every mainstream desktop provides; WSL usually lacks it
282
283
  // and has `wslview` (wslu) instead, which hands the URL to the Windows default
283
284
  // browser. Only a launcher that is NOT ON PATH passes the URL down the list:
@@ -322,7 +323,7 @@ async function openBrowser(url) {
322
323
  // that null is not it.
323
324
  //
324
325
  // Reported, and never as "parse failed": the parse succeeded, and keeping the
325
- // state a read reached apart from the state it failed at is what #816 was about.
326
+ // state a read reached apart from the state it failed at is what the ledger states are for.
326
327
  function tryParse(json, fallback, what) {
327
328
  if (json == null) return fallback;
328
329
  let parsed;
@@ -342,7 +343,7 @@ function tryParse(json, fallback, what) {
342
343
  // key. Drop it, loudly. candidates.mjs's row guard is a different shape —
343
344
  // comprehensive and hard-failing (die() on the first bad row) — this one is
344
345
  // narrower: it only checks `number`, the one field whose absence corrupts
345
- // OTHER rows, and degrades instead of dying (#786).
346
+ // OTHER rows, and degrades instead of dying.
346
347
  //
347
348
  // `rows` itself can be the wrong shape too: `tryParse` only checks that its
348
349
  // input is valid JSON, not that it is an array, so a syntactically-valid
@@ -363,7 +364,7 @@ function withNumber(rows, what) {
363
364
  return kept;
364
365
  }
365
366
 
366
- // #2108: gh stops a `list` read at its `--limit` with exit 0 and no warning, so
367
+ // gh stops a `list` read at its `--limit` with exit 0 and no warning, so
367
368
  // a read that came back exactly that long may have been cut there — "at least
368
369
  // this many", never "this many". candidates.mjs's refuseIfCapped() and
369
370
  // fleet-tick.mjs's PR_LIMIT/CLAIMED_LIMIT carry the same rule; this board is a
@@ -376,7 +377,7 @@ function hitLimit(parsed, limit) {
376
377
  return Array.isArray(parsed) && parsed.length >= limit;
377
378
  }
378
379
 
379
- // #1840: which of `prNums` gh calls MERGED, in ONE `gh api graphql` query —
380
+ // Which of `prNums` gh calls MERGED, in ONE `gh api graphql` query —
380
381
  // one aliased `pullRequest(number:)` field per PR, on the cwd's repository
381
382
  // (gh's own `{owner}`/`{repo}` placeholders, the repo every other read here
382
383
  // resolves) — so a PR merged at any age is found, and ten PRs cost what one
@@ -393,7 +394,7 @@ function hitLimit(parsed, limit) {
393
394
  // not a PR comes back null beside a NOT_FOUND error, and gh exits 1 with the
394
395
  // whole body on stdout (measured 2026-09-26, gh 2.101.0, which also names
395
396
  // the number on stderr). Refusing that body would let one such row — a
396
- // typo, or an amendment-2a row keyed by an issue number — put every other
397
+ // typo, or a row with no impl token keyed by an issue number — put every other
397
398
  // row PR back in REVIEW on every tick. A null alias reads as not merged,
398
399
  // which is what a failed read means for that one PR.
399
400
  //
@@ -402,7 +403,7 @@ function hitLimit(parsed, limit) {
402
403
  // shape the API produces, only a corrupted or truncated one; `isJsonObject`
403
404
  // alone cannot tell that apart from a genuine "checked, nothing merged"
404
405
  // answer, so it is checked for too. Anything else is a failed read: `[]`,
405
- // and computeBoard()'s #1841 rule takes it from there.
406
+ // and computeBoard()'s carry-forward rule takes it from there.
406
407
  async function readMerged(prNums) {
407
408
  if (!prNums.length) return [];
408
409
  const fields = prNums.map((n) => `p${n}:pullRequest(number:${n}){state}`).join(" ");
@@ -445,7 +446,7 @@ function labelsOf(row) {
445
446
  // strip, never fires.
446
447
  //
447
448
  // What separates a verdict from a failed read is the EXIT CODE. Emptiness of
448
- // stdout was only ever a proxy for it, and #262 retired the proxy: a quota
449
+ // stdout was only ever a proxy for it, and that proxy no longer holds: a quota
449
450
  // refusal now names its cause on stdout on the way out at exit 2, so "non-empty
450
451
  // stdout" began reading an outage as a reading. That payload carries no
451
452
  // `status`, so mapCi answered "unknown" and gather()'s prevCi carry-forward —
@@ -453,14 +454,14 @@ function labelsOf(row) {
453
454
  // last-known-good CI state during a blip that clears itself. Exit 2 means the
454
455
  // question could not be answered, whatever the script printed while saying so.
455
456
  //
456
- // The exit code is not sufficient on its own either (#875), for the symmetric
457
+ // The exit code is not sufficient on its own either, for the symmetric
457
458
  // reason: it reports that the child reached its own exit path, never that its
458
459
  // payload arrived whole. `e.status !== 2` is also true of a signal kill, where
459
460
  // `status` is null, and of a write cut mid-JSON at exit 1 — emit() over in
460
461
  // ci-state.mjs abandons a short write it cannot retry, which keeps the exit
461
462
  // code intact while losing the tail of the line. Those bytes were returned AS a
462
463
  // verdict, mapCi could not parse them, and the non-null return skipped the very
463
- // carry-forward #262 added: the #262 regression re-entering through the gate
464
+ // carry-forward added for the exit-2 case: that regression re-entering through the gate
464
465
  // built to stop it. So both halves have to hold — a non-2 exit AND bytes that
465
466
  // parse.
466
467
  //
@@ -523,13 +524,13 @@ async function runCiState(scriptDir, pr) {
523
524
  }
524
525
  return out;
525
526
  }
526
- // #1593: exit 0 was never covered by any of the checks above — they only run
527
+ // Exit 0 was never covered by any of the checks above — they only run
527
528
  // once the child read reports a failure, and a child that exits 0 reports
528
529
  // none. So the same write cut mid-JSON that the failure block above salvages
529
530
  // at exit 1 rode straight through here and into mapCi at exit 0, where an
530
531
  // unparseable string maps to "unknown" and gather()'s carry-forward — which
531
532
  // only a null return reaches — was skipped, discarding the PR's last-known
532
- // CI value exactly as #262 did before the exit-2 case was fixed. Same parse
533
+ // CI value exactly as the exit-2 case did before it was fixed. Same parse
533
534
  // check, same null return as the failure block above — but its OWN channel,
534
535
  // `ci-salvage-exit0`, not that block's `ci-salvage-nonzero`: a
535
536
  // zero-exit child does not get a looser contract than a non-zero one, and
@@ -584,7 +585,7 @@ function warnOnce(channel, key, msg) {
584
585
  export function mapCi(ciJson, pr) {
585
586
  // A NULL payload, which is a failed read runCiState() has already reported
586
587
  // on stderr. Warning again here would report one failure twice. Null
587
- // strictly, not falsiness: an EMPTY payload is not that case. Since #1593
588
+ // strictly, not falsiness: an EMPTY payload is not that case. Since
588
589
  // runCiState() parse-checks its exit-0 return too, so its own callers never
589
590
  // hand this an empty string any more — but mapCi() is exported and total
590
591
  // over any caller, not just this file's, so a `!ciJson` guard that swallowed
@@ -595,9 +596,9 @@ export function mapCi(ciJson, pr) {
595
596
  // A payload that will not parse is a THIRD state, and the return value cannot
596
597
  // carry it: "unknown" is what the regression gate pins, since a false red is
597
598
  // worse than no verdict. So the distinction leaves through stderr or not at
598
- // all. #875 closed this for runCiState()'s catch block (a payload that will
599
+ // all. That was closed for runCiState()'s catch block (a payload that will
599
600
  // not parse there is a failed read, reaching gather()'s carry-forward);
600
- // #1593 closed it for the exit-0 arm the same way (see runCiState() above),
601
+ // and for the exit-0 arm the same way (see runCiState() above),
601
602
  // so a write cut mid-JSON no longer reaches mapCi from gather() on EITHER
602
603
  // arm — a lost write now reads as a failed read there too, and that PR's
603
604
  // last-known CI value stands instead of reverting to "unknown". This catch
@@ -627,7 +628,7 @@ export function mapCi(ciJson, pr) {
627
628
 
628
629
  // Where this session's member transcripts live:
629
630
  // ~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>/
630
- // The encoder lives in member-record.mjs (#1342), shared with
631
+ // The encoder lives in member-record.mjs, shared with
631
632
  // member-outcomes.mjs; it is re-exported here under its original name so
632
633
  // nothing importing `encodeProjectDir` from this file needs to change.
633
634
  export { encodeProjectDir };
@@ -716,7 +717,7 @@ function newestTranscriptMs(dir) {
716
717
  return newest;
717
718
  }
718
719
 
719
- // #1583: the transcript directory a `serve` process is bound to, resolved
720
+ // The transcript directory a `serve` process is bound to, resolved
720
721
  // once it can be trusted and reused by every tick after it. findSubagentsDir()
721
722
  // above ranks sessions by newest transcript mtime and gather() reached it
722
723
  // through gatherSpend() on EVERY tick (~15s by default), so two sessions live
@@ -725,7 +726,7 @@ function newestTranscriptMs(dir) {
725
726
  // had switched.
726
727
  //
727
728
  // The pin holds the first answer that COULD BE THIS RUN'S, not the first
728
- // non-null answer and not the first call (#1679). findSubagentsDir() has
729
+ // non-null answer and not the first call. findSubagentsDir() has
729
730
  // three returns and none of them is safe to latch on sight: a directory
730
731
  // resolved at pin-construction time can be a PREVIOUS run's session — newer
731
732
  // than nothing else that exists yet, so it wins the ranking, but not this
@@ -734,7 +735,7 @@ function newestTranscriptMs(dir) {
734
735
  // as easily as it can be the truly unresolvable "bug that never fixes
735
736
  // itself" the ticket originally reasoned about. Latching either one turns
736
737
  // the self-correcting degradation this file's header describes into a
737
- // permanent one: measured (#1679), a chmod'd-then-restored session tree left
738
+ // permanent one: measured, a chmod'd-then-restored session tree left
738
739
  // the OLD `??=` pin stuck on `{ error }` forever while the unpinned lookup
739
740
  // recovered on its very next tick, and a prior run's session dir
740
741
  // present at launch left the old pin on yesterday's numbers for the whole of
@@ -819,7 +820,7 @@ export function spendDirPin(explicit, home = process.env.HOME, cwd = process.cwd
819
820
  //
820
821
  // `ok` is an explicit TAG, and it is what the page switches on — never the
821
822
  // presence or the truthiness of any other field. Reading the error case off
822
- // `error`'s truthiness is what #959 was: `e.message` is "" for an error thrown
823
+ // `error`'s truthiness was a bug: `e.message` is "" for an error thrown
823
824
  // without one and `undefined` for a thrown non-Error, so two shapes the catch
824
825
  // below can emit matched neither the error branch nor a success shape, and the
825
826
  // panel HID — a fault rendered as an idle run, the one conflation this panel
@@ -830,7 +831,7 @@ export function spendDirPin(explicit, home = process.env.HOME, cwd = process.cwd
830
831
  // success-only field is read.
831
832
  export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8, explicit = false } = {}) {
832
833
  try {
833
- // #1583: a caller-supplied `null` is a RESOLUTION from one that owns a pin
834
+ // A caller-supplied `null` is a RESOLUTION from one that owns a pin
834
835
  // (spendDirPin() above) — the project directory is there and holds no
835
836
  // session yet — and must not run the heuristic a second time; only an
836
837
  // omitted `dir` (every gatherSpend test driver, and `build`, which is one
@@ -839,7 +840,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
839
840
  // that distinction — the hand-rolled `if (dir === undefined) dir =
840
841
  // findSubagentsDir();` this used to spell out is redundant with it.
841
842
  //
842
- // `explicit` (#1679) is true only when `dir` came from the operator's
843
+ // `explicit` is true only when `dir` came from the operator's
843
844
  // own --spend-dir, never from the heuristic or an unresolved pin — see
844
845
  // its one use below, at the empty-directory branch.
845
846
  const dirError = dir?.error;
@@ -848,7 +849,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
848
849
  return { ok: false, error: dirError };
849
850
  }
850
851
  if (!dir) return null; // resolved, but this session has spawned no agents yet
851
- // #1679/#1302: only for an EXPLICIT --spend-dir — the heuristic's own
852
+ // Only for an EXPLICIT --spend-dir — the heuristic's own
852
853
  // findSubagentsDir() already dispatches on isOmpSessionDirName, so a
853
854
  // resolved-but-non-heuristic `dir` here only ever arrives from the
854
855
  // operator naming a directory directly. Without this check the
@@ -866,7 +867,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
866
867
 
867
868
  const { agents, toolTables, skipped, damaged } = readOmpSpend(dir, sinceMs);
868
869
  if (!agents.length) {
869
- // #1894: `damaged` belongs here beside `skipped`. An omp transcript with
870
+ // `damaged` belongs here beside `skipped`. An omp transcript with
870
871
  // no parseable assistant-with-usage line folds to no model, so
871
872
  // readOmpSpend drops it without a throw — `skipped` stays 0 — and its
872
873
  // non-last parse failures are the only trace that the directory held a
@@ -888,7 +889,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
888
889
  return { ok: false, error: `no agent turn readable: ${lost.join("; ")}` };
889
890
  }
890
891
  if (skipped) return { ok: false, error: `all ${skipped} transcripts unreadable` };
891
- // #1679: only for an EXPLICIT override — never the heuristic's own
892
+ // Only for an EXPLICIT override — never the heuristic's own
892
893
  // "resolved, no session yet" `null` case two arms up, which is the
893
894
  // normal state at launch and must stay silent. An operator who named
894
895
  // this exact directory has a panel that just went quiet with nothing
@@ -918,7 +919,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
918
919
  // `e.message` is carried as-is, including the "" and `undefined` a
919
920
  // message-less throw would give it: the tag above is what routes this to the
920
921
  // error panel, so an unhelpful message costs wording, never the panel.
921
- // #1679: an explicit --spend-dir naming a directory that does not exist
922
+ // An explicit --spend-dir naming a directory that does not exist
922
923
  // YET (the legitimate, tested case) throws ENOENT here on every tick
923
924
  // until it appears, and this catch used to print unconditionally — one
924
925
  // line per ~15s tick, forever. Routed through warnOnce, keyed on the
@@ -929,7 +930,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
929
930
  }
930
931
  }
931
932
 
932
- // omp's side (#1716): one agent per member transcript anywhere under the
933
+ // omp's side: one agent per member transcript anywhere under the
933
934
  // session dir — a nested member's too, at its own spawnDepth — read by
934
935
  // member-record.mjs's own omp reader over the walk readOmpSession uses:
935
936
  // foldOmpTranscript once per file, then ompMemberRecord on that fold, never
@@ -937,7 +938,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
937
938
  // are exactly the member record's: role from `session_init`'s agent
938
939
  // definition, task and AgentId, label the AgentId itself (the path-relative
939
940
  // stem, `review-pr-12/Security` for a nested one). The same fold's `entries`
940
- // are the tool stream (#1717), so the tool table goes through attributeTools.
941
+ // are the tool stream, so the tool table goes through attributeTools.
941
942
  //
942
943
  // Per-transcript tolerance is this file's, not readOmpSession's: readOmpSession
943
944
  // (used by the bulk scrape) lets a wrong-shape refusal propagate, and here
@@ -948,7 +949,7 @@ export function gatherSpend({ dir = findSubagentsDir(), sinceMs = null, topN = 8
948
949
  // dispatched this second) has spent nothing, so it is neither booked nor
949
950
  // skipped.
950
951
  //
951
- // `damaged` is real — the tool-attribution stream (#1717) is a join
952
+ // `damaged` is real — the tool-attribution stream is a join
952
953
  // across lines (a toolCall's id names its tool, a pending result batch bills
953
954
  // the next turn), so a dropped MIDDLE line can silently shift spend onto a
954
955
  // neighbouring tool instead of just costing its own turn's totals — the
@@ -985,17 +986,17 @@ function readOmpSpend(dir, sinceMs) {
985
986
  return { agents, toolTables, skipped, damaged };
986
987
  }
987
988
 
988
- // `workspace`/`port` are the caller's answers, never read in here (#1584):
989
+ // `workspace`/`port` are the caller's answers, never read in here:
989
990
  // resolveCockpitInstance() already decided both, and a second derivation in
990
991
  // this function could disagree with the one the server actually bound. They
991
992
  // join the payload HERE, alongside the repo fields above, because this is the
992
993
  // boundary where every impure input meets the pure model — computeBoard() only
993
994
  // echoes them. Defaulted to null, which is also the degrade arm's workspace
994
- // and the value #1585's handshake refuses to match on, so a caller with no
995
+ // and the value the launch handshake refuses to match on, so a caller with no
995
996
  // instance to name (every gather() test driver) says so rather than omitting
996
997
  // the fields.
997
998
  //
998
- // `spendDir` is the caller's PINNED transcript directory (#1583) and is the one
999
+ // `spendDir` is the caller's PINNED transcript directory and is the one
999
1000
  // parameter here whose ABSENCE is not a default to fill in: serve() hands the
1000
1001
  // same pin's answer to every tick, and its three shapes — a directory, `null`
1001
1002
  // for "resolved, no session yet", `{ error }` for unresolvable — all have to
@@ -1007,20 +1008,20 @@ function readOmpSpend(dir, sinceMs) {
1007
1008
  // nor the flag, gatherSpend() resolves for itself exactly as it did before
1008
1009
  // this ticket, which is what keeps `build`'s output unchanged by it.
1009
1010
  //
1010
- // `spendDirExplicit` (#1679) is read the same way, independently of
1011
+ // `spendDirExplicit` is read the same way, independently of
1011
1012
  // `spendDir` itself: serve() always passes a resolved `spendDir` (the pin's
1012
1013
  // answer), never leaving it to default, so `spendDir`'s own presence cannot
1013
1014
  // say whether an operator named it. Whether --spend-dir was given is a fact
1014
1015
  // about argv, unrelated to which of gatherSpend's three shapes the pin
1015
1016
  // currently holds.
1016
- // #1713: async, because every child read below is. The event loop this frees
1017
+ // Async, because every child read below is. The event loop this frees
1017
1018
  // belongs to serve()'s HTTP server, which shares this process — see execRead's
1018
1019
  // note above for what the synchronous version cost. `build` awaits it and is
1019
1020
  // otherwise unchanged: one gather per process, nothing else waiting on it.
1020
1021
  export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir = SCRIPT_DIR, interval, workspace = null, port = null, spendDir = argSpendDir(), spendDirExplicit = argSpendDir() != null }) {
1021
1022
  // The one read that must not crash the gather: a corrupt/partial board.json
1022
1023
  // (the fallback safety net itself) is ignored, not fatal. That holds for a
1023
- // SHAPE fault as much as a parse fault (#1192) — the guard below rejects the
1024
+ // SHAPE fault as much as a parse fault — the guard below rejects the
1024
1025
  // payload here so both leave through the one catch, which names the file the
1025
1026
  // operator passed. A wrong-typed `tickets` left to reach the prevCi map
1026
1027
  // instead throws `.filter is not a function` out of gather(), which made a
@@ -1043,7 +1044,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1043
1044
  // object, and `typeof null` alone would let it through. Same check and
1044
1045
  // same wording as readMerged()'s `data.repository` read, which is this
1045
1046
  // repo's precedent for rejecting a parsed-but-wrong payload at its own
1046
- // read — since #1546 literally the same, both calling the shared predicate.
1047
+ // read — literally the same, both calling the shared predicate.
1047
1048
  const p = JSON.parse(readFileSync(prevFile, "utf8"));
1048
1049
  if (!isJsonObject(p)) throw new TypeError(`expected a JSON object, got ${jsonKind(p)}`);
1049
1050
  // Nullish `tickets` is ABSENT and stays usable: `|| []` reads it as the
@@ -1071,7 +1072,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1071
1072
  }
1072
1073
 
1073
1074
  // `--require-file` turns an absent ledger into a refusal at exit 2 rather
1074
- // than the empty payload a real empty ledger returns (#816). Without it the
1075
+ // than the empty payload a real empty ledger returns. Without it the
1075
1076
  // two are byte-identical on stdout, and tryParse's fallback is that same
1076
1077
  // empty shape besides — so an unread ledger, one read empty, and a read whose
1077
1078
  // answer would not parse were three states with one rendering, on the one
@@ -1107,10 +1108,10 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1107
1108
  // POOL loop reads `iss.title` RAW, never through titleFor()'s fallback
1108
1109
  // chain — so this row genuinely needs a guaranteed string: an issue found
1109
1110
  // but unable to describe itself reads as its number rather than literal
1110
- // `undefined` on the operator's page (#786).
1111
+ // `undefined` on the operator's page.
1111
1112
  //
1112
- // Its null fallback, not the open-PR read's `[]` below, is deliberate
1113
- // (#1597 follow-up): this read is the pool's ONLY source, and
1113
+ // Its null fallback, not the open-PR read's `[]` below, is deliberate:
1114
+ // this read is the pool's ONLY source, and
1114
1115
  // compute-board.mjs's stall() needs to tell a genuinely empty pool from a
1115
1116
  // `gh` outage the same way it already tells an empty ledger from an unread
1116
1117
  // one — a `[]` fallback collapses both to the identical shape before a
@@ -1143,19 +1144,19 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1143
1144
  state: p.state,
1144
1145
  title: p.title,
1145
1146
  labels: labelsOf(p),
1146
- // (#2083) compute-board.mjs's reviewBacklog needs it to tell a
1147
+ // compute-board.mjs's reviewBacklog needs it to tell a
1147
1148
  // past-pin halt already answered by the automatic re-review apart from
1148
1149
  // one still owed a fresh one — the same field fleet-tick.mjs's
1149
1150
  // openPrs() already requires.
1150
1151
  headRefOid: p.headRefOid,
1151
1152
  }));
1152
1153
 
1153
- // #1820: MERGED is gh's answer, not a ledger token — no rule writes `MERGED
1154
- // <sha>`, and the open list above drops a PR the moment it merges. #1840:
1154
+ // MERGED is gh's answer, not a ledger token — no rule writes `MERGED
1155
+ // <sha>`, and the open list above drops a PR the moment it merges. It is
1155
1156
  // asked only about mergedReadPrs()'s set — row PRs absent from the open
1156
- // list, with no token, not carried forward (#1841) — in one batched read
1157
+ // list, with no token, not carried forward — in one batched read
1157
1158
  // that answers whatever their merge age; see readMerged(). A failed read
1158
- // is `[]`, and #1841's carry-forward in computeBoard() covers exactly the
1159
+ // is `[]`, and the carry-forward in computeBoard() covers exactly the
1159
1160
  // PRs this set leaves out, so a failure costs only a PR never yet seen
1160
1161
  // MERGED, which reads REVIEW.
1161
1162
  const merged = await readMerged(mergedReadPrs({ ledger, prs, prev }));
@@ -1168,7 +1169,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1168
1169
  // ci-state.mjs` per open PR and each of those hits the GitHub API, so a fan
1169
1170
  // of 40 at once is a rate-limit and a load spike where a queue of 40 is
1170
1171
  // neither. Nothing here waits on the loop any more — the server answers
1171
- // throughout it (#1713) — so the only thing concurrency would buy is a
1172
+ // throughout it — so the only thing concurrency would buy is a
1172
1173
  // shorter tick, against an interval measured in seconds. The warn-once
1173
1174
  // lines below also stay in PR order this way.
1174
1175
  for (const p of prs) {
@@ -1187,13 +1188,13 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1187
1188
  catch (e) { console.error(`${NAME}: gh repo view parse failed: ${e.message}`); }
1188
1189
  }
1189
1190
 
1190
- // #1076: guard's own rationale (fail loud, gate on presence and on range,
1191
+ // The guard's own rationale (fail loud, gate on presence and on range,
1191
1192
  // not just finiteness) now lives at argSpendSince()'s definition above,
1192
1193
  // alongside argPort()/argInterval() — this call is unchanged in when it
1193
1194
  // runs, only in where the check itself is written.
1194
1195
  const sinceMs = argSpendSince();
1195
1196
  const spend = gatherSpend({ dir: spendDir, sinceMs, explicit: spendDirExplicit });
1196
- // #1597: the heartbeat's mark, raw. readState() never throws — an absent
1197
+ // The heartbeat's mark, raw. readState() never throws — an absent
1197
1198
  // file is the ordinary state of a run whose heartbeat has not beaten yet,
1198
1199
  // and an unreadable or corrupt one announces itself on stderr and degrades
1199
1200
  // to no mark, which computeBoard() renders as no panel rather than as a
@@ -1207,7 +1208,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1207
1208
  // resolution could name a different workspace's beat.
1208
1209
  // `ticked` rides beside `beat`, same file same read, and under the same
1209
1210
  // "no try/catch, no tryRun shape" rule just above — fleet-tick.mjs's own
1210
- // liveness key (#1597 follow-up), for the busy-stretch case `beat` alone
1211
+ // liveness key, for the busy-stretch case `beat` alone
1211
1212
  // cannot see (fleet-state.mjs's assessBeat has the rule).
1212
1213
  const priorState = stateFile ? readState(stateFile, NAME) : null;
1213
1214
  const beat = priorState?.beat ?? null;
@@ -1218,9 +1219,9 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1218
1219
  }
1219
1220
 
1220
1221
  async function main() {
1221
- // #365: a misspelled flag was never looked for, so `serve --prot 9000`
1222
+ // A misspelled flag was never looked for, so `serve --prot 9000`
1222
1223
  // served on the default 8123 in silence. In main(), not at module scope:
1223
- // board.test.mjs and board-cli.test.mjs both import from this module, so a
1224
+ // the test files for this module import from it, so a
1224
1225
  // module-scope sweep would read the TEST RUNNER's argv.
1225
1226
  //
1226
1227
  // One set for both subcommands, deliberately. `--port`/`--open` are USED
@@ -1229,14 +1230,14 @@ async function main() {
1229
1230
  // subcommand would close that too, but that is a larger design question
1230
1231
  // (per-subcommand arg schemas) this ticket does not take; refusing a flag
1231
1232
  // this file does accept somewhere is not this ticket's business. What
1232
- // build no longer does is stay silent on a MALFORMED one — see #468 below.
1233
+ // build no longer does is stay silent on a MALFORMED one — see the argPort()/has("open") note below.
1233
1234
  //
1234
1235
  // Above `cmd`, so `board.mjs --prot 9000` names the stray rather than
1235
1236
  // printing the usage line for a missing subcommand. `build`/`serve` carry
1236
1237
  // no `--` and are never the sweep's business.
1237
1238
  sweep();
1238
1239
  const cmd = process.argv[2];
1239
- // #1656: no default applied here any more — `build` and `serve` now each
1240
+ // No default applied here any more — `build` and `serve` now each
1240
1241
  // apply their own. `build` has no workspace instance to default against
1241
1242
  // (no state directory, no board), so it keeps today's cwd-relative literal
1242
1243
  // below. `serve` defaults against `resolveCockpitInstance()`'s stateDir
@@ -1244,7 +1245,7 @@ async function main() {
1244
1245
  // served state directory does, rather than the caller's raw cwd.
1245
1246
  const ledgerFile = arg("ledger");
1246
1247
 
1247
- // #468: argPort()/has("open") used to run only inside serve(), so `build
1248
+ // argPort()/has("open") used to run only inside serve(), so `build
1248
1249
  // --port abc` and `build --open=1` were accepted and silently ignored — the
1249
1250
  // malformed spellings these guards exist to refuse never ran on that path.
1250
1251
  // Called here, once, ahead of the build/serve dispatch (and ahead of both
@@ -1252,9 +1253,9 @@ async function main() {
1252
1253
  // wording over stray()'s generic one, same ordering rule arg.mjs documents
1253
1254
  // for every other value guard in this file). Ahead of the `cmd` check too,
1254
1255
  // so `board.mjs --port abc` with NO subcommand names the flag rather than
1255
- // falling through to the usage die below — the same precedence the #365
1256
+ // falling through to the usage die below — the same precedence the
1256
1257
  // sweep note above claims for a stray, now true of these two guards as
1257
- // well. Both orderings are pinned in board.test.mjs; before this fix the
1258
+ // well. Both orderings are pinned in the board tests; before this fix the
1258
1259
  // no-subcommand shape printed the usage line (measured). The return values are
1259
1260
  // deliberately discarded on the build path: build has no server to bind or
1260
1261
  // browser to open, so a WELL-FORMED --port/--open still does nothing here,
@@ -1264,7 +1265,7 @@ async function main() {
1264
1265
  // its own argv for a caller that skips main(). Nothing in this repo is such
1265
1266
  // a caller today — every serve() test drives the real CLI, which enters
1266
1267
  // main() — but serve() is public surface, so the guard stays with it.
1267
- // #1092: unlike --port/--open (never read on `build` before #468) or
1268
+ // --prev: unlike --port/--open (never read on `build` before they were hoisted) or
1268
1269
  // --ledger/--spend-since/--interval (already read on `build`, per the
1269
1270
  // header comment above), --prev was read on exactly one subcommand and it
1270
1271
  // was the wrong one to skip: `arg("prev")` sat inside the `build` branch
@@ -1272,7 +1273,7 @@ async function main() {
1272
1273
  // so `serve --prev`, `serve --prev=x` and `serve --prev --port 9000` all
1273
1274
  // fell through with no guard ever firing (measured), the last one blaming
1274
1275
  // --port's innocent value once stray() reached it instead. Hoisted here
1275
- // for the same reason #468 hoisted argPort()/has("open") below it — ahead
1276
+ // for the same reason argPort()/has("open") were hoisted below it — ahead
1276
1277
  // of the dispatch and both branches' stray() calls — and ahead of argPort()
1277
1278
  // itself so a caller who gets BOTH flags wrong at once (`--port --prev`,
1278
1279
  // each trailing with no value) still hears about --prev specifically,
@@ -1284,8 +1285,8 @@ async function main() {
1284
1285
  argPort();
1285
1286
  has("open");
1286
1287
 
1287
- // #1076: same fail-open shape as --port/--open above (#468) — this closes
1288
- // the two flags PR #1090 (#468) left standing. `argInterval()`'s read had
1288
+ // Same fail-open shape as --port/--open above — this closes
1289
+ // the two flags that hoisting left standing. `argInterval()`'s read had
1289
1290
  // two call sites — inside serve() directly, and embedded in gather()'s
1290
1291
  // return (`interval ?? argInterval() ?? 15`), which build's dispatch below
1291
1292
  // reaches too — and the --spend-since read sat inside gather() (now
@@ -1303,10 +1304,10 @@ async function main() {
1303
1304
  // own argInterval() (via `interval ?? argInterval() ?? 15`) and gather()
1304
1305
  // still calls its own argSpendSince() — re-evaluating a pure read of argv
1305
1306
  // costs nothing, and keeps both validating their own argv for a caller
1306
- // that skips main(), same reasoning #468 gives for argPort()/has("open").
1307
+ // that skips main(), same reasoning as for argPort()/has("open").
1307
1308
  argInterval();
1308
1309
  argSpendSince();
1309
- // #1583: `--spend-dir` joins them for the same two reasons, from the day it
1310
+ // `--spend-dir` joins them for the same two reasons, from the day it
1310
1311
  // ships rather than one ticket later — it is read on both subcommands (in
1311
1312
  // gather()'s default, and through serve()'s pin), and a trailing
1312
1313
  // `--spend-dir` ahead of a stray positional has to name itself instead of
@@ -1314,7 +1315,7 @@ async function main() {
1314
1315
  // argPort()'s; gather() below does the read that reaches the panel.
1315
1316
  argSpendDir();
1316
1317
 
1317
- // #463: sweep() above only refuses a `--`-prefixed token; a bare or
1318
+ // sweep() above only refuses a `--`-prefixed token; a bare or
1318
1319
  // single-dash stray alongside a valid subcommand (`build --ledger x junk`)
1319
1320
  // rode along in silence the same way. Below the `cmd` check, deliberately
1320
1321
  // unlike sweep() above it: `board.mjs junk` is an unknown SUBCOMMAND, which
@@ -1329,20 +1330,20 @@ async function main() {
1329
1330
  if (cmd === "build") {
1330
1331
  stray();
1331
1332
  const { computeBoard } = await import("./compute-board.mjs");
1332
- // #1584: a snapshot printed here outlives the process that printed it —
1333
+ // A snapshot printed here outlives the process that printed it —
1333
1334
  // redirected to a file, pasted into a ticket, read back by the next
1334
1335
  // launch — so it says which workspace it describes and which port that
1335
1336
  // workspace's cockpit answers on. The same seam serve() uses, so the two
1336
1337
  // subcommands can never name different instances from one cwd.
1337
1338
  //
1338
1339
  // No `port:` argument, deliberately: --port is read and DISCARDED on this
1339
- // path (#468 above), and honouring it here would give the flag a meaning
1340
+ // path (see argPort()/has("open") above), and honouring it here would give the flag a meaning
1340
1341
  // on `build` it has never had. The DERIVED port is the identity anyway —
1341
1342
  // it is the port this workspace is reachable on, which is what a stray
1342
1343
  // snapshot needs to name; the port some one-shot invocation happened to
1343
1344
  // ask for is not.
1344
1345
  //
1345
- // The default ledger stays the cwd-relative literal #1656 left here. That
1346
+ // The default ledger stays the cwd-relative literal that serve() used to share. That
1346
1347
  // is not an oversight to fix in passing: `build` prints to stdout and
1347
1348
  // writes no state directory, so the argument that moved serve()'s default
1348
1349
  // onto the workspace does not reach it, and changing it would change what
@@ -1350,7 +1351,7 @@ async function main() {
1350
1351
  const instance = resolveCockpitInstance({ cwd: process.cwd(), gitCommonDir: gitCommonDir() });
1351
1352
  const model = computeBoard(await gather({
1352
1353
  ledgerFile: ledgerFile || ".fleet/ledger.md", prevFile,
1353
- // #1597: the heartbeat's file, from the SAME instance the identity
1354
+ // The heartbeat's file, from the SAME instance the identity
1354
1355
  // fields below come from — not the cwd-relative literal the ledger
1355
1356
  // default keeps. That literal is `build`'s own back-compatibility (see
1356
1357
  // the note above); the mark has no existing `build` behaviour to
@@ -1393,7 +1394,7 @@ export function createBoardServer(dir) {
1393
1394
  //
1394
1395
  // BASE is the port this file hardcoded before any of this existed;
1395
1396
  // resolveCockpitInstance()'s degrade arm, with no workspace to hash, still
1396
- // defaults to it. SPAN = 512 was kept deliberately (ruling on #39/#1657): a
1397
+ // defaults to it. SPAN = 512 was kept deliberately: a
1397
1398
  // collision between two DIFFERENT workspaces is not priced into the width but
1398
1399
  // carried by serve()'s launch loop, which probes whoever holds the derived
1399
1400
  // port, reuses that cockpit when it is this workspace's own, and otherwise
@@ -1422,7 +1423,7 @@ function workspaceHash(key) {
1422
1423
  }
1423
1424
 
1424
1425
  // The one spelling of "this value is a workspace identity", read by every
1425
- // side of the cockpit handshake (#1661). The invariant is that null and the
1426
+ // side of the cockpit handshake. The invariant is that null and the
1426
1427
  // empty string are never an identity to match on, and it used to be carried
1427
1428
  // by two independently-written guards — resolveCockpitInstance()'s
1428
1429
  // `workspace === null` below and probeCockpitWorkspace()'s
@@ -1447,7 +1448,7 @@ function workspaceHash(key) {
1447
1448
  // Not exported, for workspaceHash()'s reason above it: nothing outside this
1448
1449
  // file asks the question, and every widening of it is already pinned from
1449
1450
  // outside through the two call sites — mutation-verified for this extraction
1450
- // (#1661), each mutant killed by a test that was already in board.test.mjs:
1451
+ // and each mutant was killed by a test that already existed in the board tests:
1451
1452
  // `v != null && v !== ""` by the probe's not-a-string row, `typeof v ===
1452
1453
  // "string"` by its empty-workspace row, a degrade arm publishing `""` by
1453
1454
  // resolveCockpitInstance's three degrade rows, and dropping it from
@@ -1473,7 +1474,7 @@ function isWorkspaceId(v) {
1473
1474
  *
1474
1475
  * `--git-common-dir` answers with the MAIN checkout's git dir from inside a
1475
1476
  * linked worktree, so every worktree of one repo resolves to ONE state
1476
- * directory. That resolution is not spelled here: since #1658 it is
1477
+ * directory. That resolution is not spelled here: it is
1477
1478
  * git-env.mjs's workspaceDirFromGitCommonDir(), the same function
1478
1479
  * ledger.mjs's defaultLedgerPath() and fleet-state.mjs's statePath() resolve
1479
1480
  * the run's single ledger and single heartbeat with — so the board, the
@@ -1486,7 +1487,7 @@ function isWorkspaceId(v) {
1486
1487
  */
1487
1488
  export function resolveCockpitInstance({ cwd = process.cwd(), gitCommonDir, port } = {}) {
1488
1489
  // `port != null`, never truthiness: --port 0 is a real request (an
1489
- // ephemeral bind, #366/#435) and reading it as "absent" would derive a port
1490
+ // ephemeral bind) and reading it as "absent" would derive a port
1490
1491
  // straight over the top of one the caller explicitly asked for.
1491
1492
  const forced = port != null;
1492
1493
  const workspace = workspaceDirFromGitCommonDir(gitCommonDir, cwd, { canonicalise: true });
@@ -1523,9 +1524,9 @@ export function resolveCockpitInstance({ cwd = process.cwd(), gitCommonDir, port
1523
1524
  }
1524
1525
 
1525
1526
  // The impure half, deliberately outside the seam above. Bounded for the
1526
- // reason #1199 bounded the ledger's identical probe: an unbounded git that
1527
+ // reason the ledger's identical probe is bounded: an unbounded git that
1527
1528
  // never returns hangs serve() before it binds anything, with nothing on
1528
- // stderr to say why. Ambient GIT_DIR/GIT_WORK_TREE scrubbed (#1599) — either
1529
+ // stderr to say why. Ambient GIT_DIR/GIT_WORK_TREE scrubbed — either
1529
1530
  // one answers `--git-common-dir` for a DIFFERENT repository, which would
1530
1531
  // serve this cockpit out of someone else's workspace at exit 0, in silence.
1531
1532
  // A non-zero exit, a stall and git missing entirely all land on "" and take
@@ -1593,14 +1594,14 @@ function bindFailure(server, port) {
1593
1594
  // read tells a port nobody holds from one whose holder was busy for that
1594
1595
  // second, and a box under load, a process still between its bind and its
1595
1596
  // identity write, or a dropped SYN all produce the second shape. The probe
1596
- // retries once before it will call a silent port foreign (#1660).
1597
+ // retries once before it will call a silent port foreign.
1597
1598
  //
1598
- // Until #1713 the commonest producer of that shape was this cockpit itself —
1599
+ // Until the tick's reads became asynchronous the commonest producer of that shape was this cockpit itself —
1599
1600
  // a same-workspace holder blocked inside its own synchronous gather() when
1600
1601
  // the probe arrived, for the 4.72–4.91s a board took to build, which no
1601
1602
  // number of retries at this timeout would have covered. That one is gone at
1602
1603
  // the source: the tick's reads are asynchronous and the server answers
1603
- // throughout (cockpit-tick-nonblocking.test.mjs). Raising this timeout was
1604
+ // throughout. Raising this timeout was
1604
1605
  // ruled out as the fix for it — it would have to clear a gather(), which
1605
1606
  // charges every launch past a stranger-held port that much per candidate.
1606
1607
  const PROBE_TIMEOUT_MS = 1000;
@@ -1628,12 +1629,12 @@ const PROBE_BODY_CAP = 1024 * 1024;
1628
1629
  * same answer — foreign. A holder that IS this workspace's cockpit answers
1629
1630
  * with the board payload it already serves, so no endpoint is added for
1630
1631
  * this and the handshake reaches nothing a browser could not. The one
1631
- * consequence to know: a cockpit started from a build older than #1585
1632
+ * consequence to know: a cockpit started from a build older than the identity handshake
1632
1633
  * serves a payload with no `workspace` at all, so it reads as foreign and a
1633
1634
  * launch steps over it rather than reusing it — once, until that process is
1634
1635
  * restarted.
1635
1636
  *
1636
- * A bare timeout gets one retry (#1660) rather than folding straight into
1637
+ * A bare timeout gets one retry rather than folding straight into
1637
1638
  * "foreign": nothing in a socket read distinguishes "nobody is there" from
1638
1639
  * "busy for that second", and a loaded box produces the second shape. Only a
1639
1640
  * second silent window calls it, and says so on stderr distinctly from a
@@ -1671,7 +1672,7 @@ export function probeCockpitWorkspace(port, timeoutMs = PROBE_TIMEOUT_MS) {
1671
1672
  let w;
1672
1673
  try { w = JSON.parse(body)?.workspace; } catch { finish(null); return; }
1673
1674
  // Exactly the construction side's rule, because it is literally
1674
- // the same predicate (#1661): a non-string, or the empty string,
1675
+ // the same predicate: a non-string, or the empty string,
1675
1676
  // is no identity. `=== ours` would be false for the first anyway,
1676
1677
  // but an empty string could match an empty workspace and there
1677
1678
  // must be no such thing.
@@ -1694,27 +1695,27 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1694
1695
  //
1695
1696
  // A GIVEN-but-invalid --port is refused outright by argPort() and never
1696
1697
  // reaches here; an ABSENT one leaves `portGiven` nullish, which is how the
1697
- // seam is told to derive rather than obey. `??` and not `||`, for #366's
1698
- // reason: --port 0 is a legal ephemeral bind and `||` would discard it.
1698
+ // seam is told to derive rather than obey. `??` and not `||`:
1699
+ // --port 0 is a legal ephemeral bind and `||` would discard it.
1699
1700
  //
1700
1701
  // A bind failure no longer means one thing, so the two kinds of port part
1701
1702
  // company here. One this script DERIVED is negotiable: the loop below
1702
- // handshakes with whoever holds it and steps over a stranger (#1585). One
1703
+ // handshakes with whoever holds it and steps over a stranger. One
1703
1704
  // the caller CHOSE is not — the refusal names that port bare and dies,
1704
1705
  // because scanning off it would serve the board somewhere the operator did
1705
1706
  // not ask for and reusing it would hand them someone else's. What tells
1706
1707
  // them apart is `instance.derived` and not truthiness on `portGiven`: an
1707
- // explicit `--port 0` is falsy (#366's legal ephemeral bind), so the old
1708
+ // explicit `--port 0` is falsy (a legal ephemeral bind), so the old
1708
1709
  // spelling gave it the derived port's treatment, and nothing pinned that.
1709
1710
  const portGiven = port ?? argPort();
1710
1711
  interval = interval ?? argInterval() ?? 15;
1711
1712
  open = open ?? has("open");
1712
- // #1583: built HERE, once, and read by every tick below. Beside the other
1713
+ // Built HERE, once, and read by every tick below. Beside the other
1713
1714
  // argv reads rather than inside tick() for the obvious reason — a pin rebuilt
1714
1715
  // per tick is a pin in name only — and above the port loop because it costs
1715
1716
  // nothing to carry: spendDirPin() touches no filesystem until its first call,
1716
1717
  // so the reuse and degrade arms that exit before ticking pay nothing for it.
1717
- // `spendDir ?? argSpendDir()` (#1679), matching the `port ?? argPort()`
1718
+ // `spendDir ?? argSpendDir()`, matching the `port ?? argPort()`
1718
1719
  // shape above: every other argv-read option here takes an in-process
1719
1720
  // override, and this one hadn't, so the only way to drive --spend-dir
1720
1721
  // through `serve` at all was the real CLI — no test exercised it.
@@ -1723,7 +1724,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1723
1724
  const instance = resolveCockpitInstance({ cwd: process.cwd(), gitCommonDir: gitCommonDir(), port: portGiven });
1724
1725
  const stateDir = instance.stateDir;
1725
1726
  const jsonPath = join(stateDir, "board.json");
1726
- // #1656: the ledger's own default (ledger.mjs's defaultLedgerPath()) is
1727
+ // The ledger's own default (ledger.mjs's defaultLedgerPath()) is
1727
1728
  // never reached here — board.mjs always passes an explicit --file — so an
1728
1729
  // absent --ledger has to be defaulted against the SAME instance the state
1729
1730
  // directory came from, not a cwd-relative literal. A worktree or a
@@ -1731,18 +1732,18 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1731
1732
  // not exist there, while the state directory (above) had already moved to
1732
1733
  // the workspace: the board and the ledger could disagree about which run
1733
1734
  // they belonged to, exactly what resolveCockpitInstance() exists to rule
1734
- // out (#1656 review).
1735
+ // out.
1735
1736
  ledgerFile = ledgerFile || join(stateDir, "ledger.md");
1736
1737
  // `served` is the port this process actually BOUND, handed in rather than
1737
1738
  // closed over: it is not knowable until listen() returns (--port 0 is an
1738
- // ephemeral bind, #366/#435, and the loop below may also land past a
1739
+ // ephemeral bind, and the loop below may also land past a
1739
1740
  // candidate it could not take), and a tick that reached for `portGiven`
1740
1741
  // instead would stamp every board served on an ephemeral port with a
1741
1742
  // `port: 0` no browser could ever reach. A parameter makes that
1742
1743
  // unreachable rather than merely unlikely — there is no earlier value in
1743
1744
  // scope for it to pick up.
1744
1745
  // One tick at a time, and the flag is load-bearing rather than defensive.
1745
- // Before #1713 the timer's callback was synchronous, so node could not start
1746
+ // The timer's callback used to be synchronous, so node could not start
1746
1747
  // a second tick while the first was still inside gather() — it just fired
1747
1748
  // late. An async tick has no such floor: a gather that outruns `interval`
1748
1749
  // (a `gh` outage riding out its own timeouts, an operator's `--interval 1`)
@@ -1767,7 +1768,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1767
1768
  }
1768
1769
  ticking = true;
1769
1770
  try {
1770
- // #1585: the identity a second launch's handshake reads off this
1771
+ // The identity a second launch's handshake reads off this
1771
1772
  // cockpit. It rides the board payload deliberately, rather than a
1772
1773
  // lockfile or a second endpoint: a payload exists only while the
1773
1774
  // process serving it does, so nothing written here can outlive this
@@ -1775,13 +1776,13 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1775
1776
  // on the degrade arm — no workspace was established — which is exactly
1776
1777
  // the value no launch may ever match on.
1777
1778
  //
1778
- // #1584: joined at gather(), not stamped onto the finished model. The
1779
+ // Joined at gather(), not stamped onto the finished model. The
1779
1780
  // assignment that used to sit below this line wrote a field the pure
1780
1781
  // model did not declare, so `build` printed a board with no identity
1781
1782
  // at all and only the served copy carried one.
1782
1783
  const model = computeBoard(await gather({
1783
1784
  ledgerFile, prevFile: jsonPath, interval,
1784
- // #1597: beside the ledger and out of the same state directory, so
1785
+ // Beside the ledger and out of the same state directory, so
1785
1786
  // the board, the ledger and the heartbeat cannot disagree about which
1786
1787
  // run they belong to — the invariant resolveCockpitInstance() exists
1787
1788
  // for. Re-derived per tick rather than closed over, exactly like
@@ -1790,7 +1791,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1790
1791
  workspace: instance.workspace, port: served,
1791
1792
  // The pinned transcript directory, not a fresh lookup: every tick after
1792
1793
  // the first gets the SAME answer, which is what stops the panel
1793
- // alternating between two sessions under one project directory (#1583).
1794
+ // alternating between two sessions under one project directory.
1794
1795
  spendDir: spendPin(),
1795
1796
  }));
1796
1797
  const tmp = `${jsonPath}.tmp`;
@@ -1800,14 +1801,14 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1800
1801
  finally { ticking = false; }
1801
1802
  };
1802
1803
 
1803
- // #1660: a held port used to mean three different things this loop could
1804
+ // A held port used to mean three different things this loop could
1804
1805
  // only tell apart by binding first and probing whichever candidate
1805
1806
  // happened to refuse — so a live cockpit that landed past a squatter
1806
1807
  // which has since departed was invisible the moment that squatter's port
1807
1808
  // freed (this process would just bind it directly), and a workspace with
1808
1809
  // no identity established (the degrade arm) still scanned past a held
1809
1810
  // port with nothing a handshake could ever match, reopening the
1810
- // dual-cockpit hazard #1656 closed.
1811
+ // dual-cockpit hazard.
1811
1812
  //
1812
1813
  // Bind stays the FIRST thing tried per candidate: that is what lets two
1813
1814
  // launches racing at start settle on one winner quickly, the winner's
@@ -1821,7 +1822,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1821
1822
  // this workspace has no identity to match on: an explicit --port
1822
1823
  // (`!instance.derived`) and the degrade arm (no `isWorkspaceId` identity)
1823
1824
  // never had a handshake to reach in the first place, so a held port for
1824
- // either stays fatal, exactly as it was before #1585 existed.
1825
+ // either stays fatal, exactly as it was before the handshake existed.
1825
1826
  const candidates = cockpitPorts(instance);
1826
1827
  const scannable = instance.derived && isWorkspaceId(instance.workspace);
1827
1828
  let server = null;
@@ -1837,7 +1838,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1837
1838
  attempt.close();
1838
1839
  const url = `http://localhost:${rest[matchAt]}/`;
1839
1840
  console.error(`${NAME}: cockpit already running for this workspace on ${url}`);
1840
- // Nothing is opened here, --open or not (#1714). This cockpit was
1841
+ // Nothing is opened here, --open or not. This cockpit was
1841
1842
  // already running when this launch arrived, so its tab was the business
1842
1843
  // of the launch that started it; run-team's phase 0 relaunches on every
1843
1844
  // re-shortlist, and opening here stacked one more tab for the same
@@ -1871,7 +1872,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1871
1872
  // the state directory and board.html. Never for a launch either check
1872
1873
  // above already turned into a no-op: this shares the state directory
1873
1874
  // with whatever this workspace's live cockpit is doing, and touching it
1874
- // before reuse was settled is what #1660's review flagged in the reuse
1875
+ // before reuse was settled was a defect in the reuse
1875
1876
  // arm (mkdirSync/copyFileSync used to run before the candidate loop).
1876
1877
  mkdirSync(stateDir, { recursive: true });
1877
1878
  try { copyFileSync(join(SCRIPT_DIR, "board.html"), join(stateDir, "board.html")); }
@@ -1885,28 +1886,28 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1885
1886
  server.on("error", (e) => die(e.message));
1886
1887
 
1887
1888
  // Everything below is reached only by a process that HOLDS a port, which is
1888
- // what #1656's listen-callback gating bought and what this loop has to keep
1889
+ // what the listen-callback gating bought and what this loop has to keep
1889
1890
  // paying for by position: tick() writes into stateDir, SHARED by every cwd
1890
1891
  // that resolves to this workspace, so a process that never binds must not
1891
1892
  // reach it. A second cockpit that ticked first would overwrite the live
1892
1893
  // one's board.json and reset every ticket's dwell clock.
1893
1894
  //
1894
1895
  // Announce the port we GOT, not the one we asked for. They differ for the
1895
- // one value #366 newly permits: listen(0) binds an ephemeral port, so
1896
+ // one value `--port 0` newly permits: listen(0) binds an ephemeral port, so
1896
1897
  // echoing the request prints — and --opens — http://localhost:0, which
1897
- // reaches nothing while the board sits on a port nobody was told (#435
1898
- // review). address() is only populated once listening, hence only here.
1898
+ // reaches nothing while the board sits on a port nobody was told.
1899
+ // address() is only populated once listening, hence only here.
1899
1900
  const bound = server.address().port;
1900
1901
  console.error(`${NAME}: cockpit on http://localhost:${bound} (interval ${interval}s)`);
1901
1902
 
1902
- // #1660: publish identity the instant this port is ours — before the
1903
+ // Publish identity the instant this port is ours — before the
1903
1904
  // first tick, which is the one that can be slow (gather() shells out to
1904
1905
  // gh and ledger.mjs). A sibling launch races this one by sending its
1905
1906
  // probe as soon as ITS bind attempt refuses, which can be well before
1906
1907
  // this process's first gather() ever returns; the answer that probe needs
1907
1908
  // has to already be on disk, not waiting on a compute this process has
1908
1909
  // not started yet.
1909
- // #1584: `port` rides along. This stub is a board payload like any other
1910
+ // `port` rides along. This stub is a board payload like any other
1910
1911
  // for as long as the first gather() takes, and a reader that finds it —
1911
1912
  // the operator, a script, the page — gets the same two identity fields
1912
1913
  // from it that every later tick writes. The handshake above still reads
@@ -1915,7 +1916,7 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1915
1916
  renameSync(`${jsonPath}.tmp`, jsonPath);
1916
1917
  // Yield once so a connection already arriving — that same sibling's probe —
1917
1918
  // gets a chance to read the identity just written before this process starts
1918
- // the first tick. The tick no longer blocks the loop (#1713), but gather()
1919
+ // the first tick. The tick no longer blocks the loop, but gather()
1919
1920
  // still opens with a synchronous prev-board read before its first await, and
1920
1921
  // a turn of the loop costs nothing.
1921
1922
  await new Promise((resolve) => setImmediate(resolve));
@@ -1938,9 +1939,9 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1938
1939
  process.on("SIGTERM", stop);
1939
1940
 
1940
1941
  // --open, from this launch alone: it is the one that bound a port and
1941
- // started a server, and the reuse arms above open nothing (#1714). Only
1942
+ // started a server, and the reuse arms above open nothing. Only
1942
1943
  // once the identity is on disk — a launcher running BEFORE that write put a
1943
- // child squarely inside the window #1660 exists to keep empty, where a
1944
+ // child squarely inside the window the identity stub exists to keep empty, where a
1944
1945
  // racing launch's probe finds no payload and reads this port as foreign —
1945
1946
  // and only after the tick, the timer and both signal handlers are in
1946
1947
  // place: `xdg-open` can run the browser it starts in the foreground and
@@ -1951,13 +1952,13 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1951
1952
  await new Promise(() => {}); // run until signalled
1952
1953
  }
1953
1954
 
1954
- // #1093: an internal FAULT is not a refusal, and until this they were one
1955
+ // An internal FAULT is not a refusal, and until this they were one
1955
1956
  // line. Every guard in this file refuses through die(), which writes its own
1956
1957
  // line and calls process.exit(2) itself (arg.mjs) rather than throwing, so
1957
1958
  // nothing a caller can type unwinds as far as the catch below. Re-checked
1958
1959
  // against the tree rather than taken from the ticket: every `throw` in this
1959
1960
  // file — readOmpSpend's per-transcript catch, and the three prev-board shape guards
1960
- // gather() gained in #1192 — is caught by the try that raises it, so the whole
1961
+ // gather() gained — is caught by the try that raises it, so the whole
1961
1962
  // population reaching this handler is this script breaking. Handing that
1962
1963
  // to die() printed a bug under the wording and the exit code a typo gets — one
1963
1964
  // `board: <text>` line, exit 2, no stack — and an operator could not tell the
@@ -1968,14 +1969,12 @@ export async function serve({ ledgerFile, port, interval, open, spendDir } = {})
1968
1969
  // "an internal software error has been detected", and it spends nothing the
1969
1970
  // fleet's exit vocabulary already means: 0 is the answer, 1 is a verdict (this
1970
1971
  // script has none to give), 2 is every refusal here, 3 is candidates.mjs's
1971
- // minted verdict, and 126+ is the band a shell mints for itself. Stated in the
1972
- // script-surface table of docs/specs/2026-07-23-fleet-plugin-design.md, which
1973
- // board.mjs had no row in at all before this.
1972
+ // minted verdict, and 126+ is the band a shell mints for itself.
1974
1973
  const FAULT_EXIT = 70;
1975
1974
 
1976
1975
  // The diagnostic, and it can never come back empty. Read off `stack` rather
1977
1976
  // than `instanceof Error`: the stack is what a fault owes the operator, and
1978
- // asking for it directly needs no error TYPE — the hierarchy #1093 rules out.
1977
+ // asking for it directly needs no error TYPE — the hierarchy this rules out.
1979
1978
  // A thrown non-Error has no stack and used to arrive as `e.message ===
1980
1979
  // undefined`, so the CLI printed the literal `board: undefined`; inspect()
1981
1980
  // renders every value there is — `undefined`, `null`, `""`, a circular object
@@ -1991,11 +1990,10 @@ export function faultText(e) {
1991
1990
  //
1992
1991
  // A single writeSync call can also short-write — return the count it
1993
1992
  // managed and throw nothing at all — or throw EAGAIN outright, the same
1994
- // failure #889 gave die() (arg.mjs) a bounded retry loop for, and PR #1523
1995
- // then gave staleness.mjs's verdict() too. board.mjs has exactly one
1996
- // writeSync call site — this one — and #1549 moved arg.mjs's die() and
1997
- // staleness.mjs's verdict() onto the shared writeAll() and deleted
1998
- // ci-state.mjs's emit() outright, so fault() is now the only script-level
1993
+ // failure arg.mjs's writeAll() has a bounded retry loop for. board.mjs has
1994
+ // exactly one writeSync call site — this one — and arg.mjs's die() and
1995
+ // staleness.mjs's verdict() use the shared writeAll() while
1996
+ // ci-state.mjs has no emit() of its own, so fault() is now the only script-level
1999
1997
  // function left hand-rolling this loop directly: it carries the largest
2000
1998
  // single payload of any of them, a full stack, not a one-line refusal — so
2001
1999
  // it is the one most likely to collide with a saturated pipe and lose the