@feigi/fleet-ctl 3.24.2 → 3.24.4
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/package.json +1 -1
- package/scripts/board.html +22 -22
- package/scripts/board.mjs +143 -145
- package/scripts/compute-board.mjs +39 -38
- package/scripts/derive-testcmd.sh +1 -1
- package/scripts/drop-merged-label.sh +10 -11
- package/scripts/fleet-bootstrap +8 -8
- package/scripts/fleet-provenance +8 -8
- package/scripts/fleet-run +3 -3
- package/scripts/frontmatter-allowlist.json +6 -6
- package/scripts/instruments.sh +30 -31
- package/scripts/json.sh +12 -13
- package/scripts/net.sh +23 -21
- package/scripts/prove-merge.sh +7 -7
- package/scripts/review-core.mjs +57 -58
- package/scripts/review-eval.mjs +14 -15
- package/scripts/verify-sha.sh +4 -4
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
141
|
-
//
|
|
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
|
-
//
|
|
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
|
|
175
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
245
|
-
//
|
|
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
|
-
//
|
|
280
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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`
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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
|
-
//
|
|
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
|
|
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 —
|
|
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
|
|
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
|
|
1111
|
+
// `undefined` on the operator's page.
|
|
1111
1112
|
//
|
|
1112
|
-
// Its null fallback, not the open-PR read's `[]` below, is deliberate
|
|
1113
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
1154
|
-
// <sha>`, and the open list above drops a PR the moment it merges.
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
1288
|
-
// the two flags
|
|
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
|
|
1307
|
+
// that skips main(), same reasoning as for argPort()/has("open").
|
|
1307
1308
|
argInterval();
|
|
1308
1309
|
argSpendSince();
|
|
1309
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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 (
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1597
|
+
// retries once before it will call a silent port foreign.
|
|
1597
1598
|
//
|
|
1598
|
-
// Until
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1698
|
-
//
|
|
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
|
|
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 (
|
|
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
|
-
//
|
|
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()
|
|
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
|
-
//
|
|
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
|
|
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,
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1898
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
1995
|
-
//
|
|
1996
|
-
//
|
|
1997
|
-
//
|
|
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
|