@feigi/fleet-ctl 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,694 @@
1
+ // The --spend-since and --spend-dir trust boundaries, driven through the real
2
+ // CLI.
3
+ //
4
+ // Separate from board.test.mjs because these need a heavier rig than the
5
+ // process-boundary tests already there. Before #1076, gather() reached the
6
+ // --spend-since guard only AFTER its gh reads, so even the malformed-value
7
+ // cases below needed a stub `gh` on PATH and a fake HOME holding a
8
+ // transcript, where the --ledger/--port cases (in board.test.mjs) died
9
+ // before any gh call and needed neither.
10
+ // #1076 hoisted the same read (now argSpendSince()) into
11
+ // main(), ahead of the build/serve dispatch and ahead of gh reads too — but
12
+ // the rig stays: the success-path cases below (a valid value reaching the
13
+ // payload, the #807/#363 pipe-race cases) still run gather() to completion
14
+ // and need the stub either way.
15
+ //
16
+ // gather() reads process.argv directly and die()s with process.exit(2), so it
17
+ // cannot be called in-process the way gatherSpend() is — which is why this
18
+ // validation shipped with no coverage at all.
19
+ import { test } from "node:test";
20
+ import assert from "node:assert/strict";
21
+ import { spawnSync, spawn, execFileSync } from "node:child_process";
22
+ import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, realpathSync } from "node:fs";
23
+ import { tmpdir } from "node:os";
24
+ import { join } from "node:path";
25
+ import { fileURLToPath } from "node:url";
26
+ import { encodeProjectDir } from "./board.mjs";
27
+
28
+ const BOARD = fileURLToPath(new URL("./board.mjs", import.meta.url));
29
+ const LEDGER = fileURLToPath(new URL("./ledger.mjs", import.meta.url));
30
+
31
+ // One assistant turn, enough for readOmpSpend to bill an agent — the omp
32
+ // envelope's own shape (member-record.mjs's foldOmpTranscript comment). The
33
+ // summation shapes are board.test.mjs's business, not this file's.
34
+ const ompTurn = (cacheWrite) => [
35
+ { type: "session", version: 3, id: "s1", timestamp: "2026-09-08T15:11:49.444Z", cwd: "/w" },
36
+ { type: "message", id: "m1", parentId: "s1", timestamp: "2026-09-08T15:12:00.000Z",
37
+ message: { role: "assistant", content: [{ type: "text", text: "ok" }], model: "claude-opus-5",
38
+ usage: { input: 1, output: 1, cacheRead: 0, cacheWrite, totalTokens: 0, cost: { total: 0 } } } },
39
+ ].map((l) => JSON.stringify(l)).join("\n") + "\n";
40
+
41
+ // The stub `gh` fails on every call: each gh read goes through tryRun, which
42
+ // catches and degrades, so the board still builds and nothing here touches the
43
+ // network or this repo's live issue list. Prepended to PATH rather than
44
+ // replacing it, because gather() also shells out to `node`.
45
+ // `ledgerFile` overrides the missing-ledger default the --spend-since and
46
+ // --interval cases want: those die before the read matters, while the #807
47
+ // case below needs a real one the read has to carry back whole. `seed` lays
48
+ // the transcript tree into the fake $HOME for the child's cwd.
49
+ function runBoard(sinceArgs, ledgerFile, seed = seedDefault) {
50
+ const home = mkdtempSync(join(tmpdir(), "since-home-"));
51
+ // realpath, not the bare mkdtemp path: on darwin $TMPDIR is under /var, which
52
+ // is a symlink to /private/var, and the child's process.cwd() reports the
53
+ // RESOLVED form. Encoding the unresolved one puts the fixture at a path
54
+ // findSubagentsDir never looks in, and the panel comes back { error }.
55
+ const cwd = realpathSync(mkdtempSync(join(tmpdir(), "since-cwd-")));
56
+ const bin = mkdtempSync(join(tmpdir(), "since-bin-"));
57
+ writeFileSync(join(bin, "gh"), "#!/bin/sh\nexit 1\n");
58
+ chmodSync(join(bin, "gh"), 0o755);
59
+ seed(home, cwd);
60
+ return spawnSync(process.execPath, [BOARD, "build", "--ledger", ledgerFile ?? join(cwd, "nope.md"), ...sinceArgs], {
61
+ cwd, encoding: "utf8",
62
+ // This harness's own ceiling, not the subject's: a board built over a big
63
+ // ledger prints a board.json past spawnSync's default, and the default
64
+ // kills the child and reports `status: null` — which reads exactly like
65
+ // the subject crashing. Measured: without this the #807 case fails on the
66
+ // READER, with the fix under test working correctly.
67
+ maxBuffer: 64 * 1024 * 1024,
68
+ env: { ...process.env, HOME: home, PATH: `${bin}:${process.env.PATH}` },
69
+ });
70
+ }
71
+
72
+ // findSubagentsDir() defaults to $HOME and cwd, so the fixture has to sit
73
+ // where the encoding puts it — encodeProjectDir is the real function, not a
74
+ // hand-rolled path, so this cannot drift from it. Named after an
75
+ // `<ISO>_<uuid>` directory so the heuristic's own directory-name filter
76
+ // finds it.
77
+ function seedDefault(home, cwd) {
78
+ const dir = join(home, ".omp", "agent", "sessions", encodeProjectDir(cwd, { home }),
79
+ "2026-08-25T09-00-00-000Z_01a08126-ee04-7095-a695-14e3249f1127");
80
+ mkdirSync(dir, { recursive: true });
81
+ writeFileSync(join(dir, "default-agent.jsonl"), ompTurn(1000));
82
+ }
83
+
84
+ test("--spend-since rejects a seconds-magnitude epoch — the mistake its own comment names", () => {
85
+ // The motivating bug, and the one a finiteness-only guard cannot see: a
86
+ // seconds value is perfectly finite, so it passed, filtered nothing out, and
87
+ // produced a whole-session panel that reported itself as scoped — shipping
88
+ // the bogus number into board.json's `since`, where nothing downstream could
89
+ // tell. 1e12 ms is 2001-09-09, so every seconds-magnitude epoch is below it.
90
+ const r = runBoard(["--spend-since", String(Math.floor(Date.now() / 1000))]);
91
+ assert.equal(r.status, 2, r.stderr);
92
+ assert.match(r.stderr, /--spend-since wants epoch milliseconds/);
93
+ });
94
+
95
+ test("--spend-since rejects garbage, zero, negative and a boundary in the future", () => {
96
+ // A future boundary matches nothing at all, which renders as an empty panel
97
+ // rather than as the operator error it is.
98
+ for (const v of ["yesterday", "0", "-1", String(Date.now() + 86_400_000)]) {
99
+ const r = runBoard(["--spend-since", v]);
100
+ assert.equal(r.status, 2, `expected exit 2 for ${v}: ${r.stderr}`);
101
+ assert.match(r.stderr, /--spend-since wants epoch milliseconds/);
102
+ }
103
+ });
104
+
105
+ test("--spend-since with the value omitted fails, rather than reading as 'no filter at all'", () => {
106
+ // The flag as the last argv: arg() yields undefined and the guard's old
107
+ // `sinceRaw == null` read that as "flag absent" — exit 0, whole session,
108
+ // no stderr. arg()'s own value guard is what closes it: argSpendSince()
109
+ // tests `=== null` only on what arg() already accepted.
110
+ const r = runBoard(["--spend-since"]);
111
+ assert.equal(r.status, 2, r.stderr);
112
+ assert.match(r.stderr, /--spend-since/);
113
+ });
114
+
115
+ // #364 gave has() a boolean-specific refusal, and gather() used to call has()
116
+ // on --spend-since — a flag that TAKES a value — so the wording stayed
117
+ // correct only while arg("spend-since") ran first. #1077 retired that has():
118
+ // the flag table declares --spend-since "value", so a has() read of it would
119
+ // now refuse as a bug. This pins the operator-facing wording either way.
120
+ test("--spend-since=123 is refused as a value flag, not misreported as a boolean one", () => {
121
+ const r = runBoard(["--spend-since=123"]);
122
+ assert.equal(r.status, 2, r.stderr);
123
+ assert.match(r.stderr, /--spend-since needs a space-separated value/);
124
+ });
125
+
126
+ test("a valid epoch-ms --spend-since survives the guard and reaches the payload", () => {
127
+ // The leg that stops the guard from being merely strict. `since` is also the
128
+ // only field downstream can read to tell a scoped panel from an unscoped one,
129
+ // so it has to arrive, not just be accepted.
130
+ const since = Date.now() - 3_600_000;
131
+ const r = runBoard(["--spend-since", String(since)]);
132
+ assert.equal(r.status, 0, r.stderr);
133
+ const body = JSON.parse(r.stdout);
134
+ assert.equal(body.spend.since, since);
135
+ // This case's default ledger file (nope.md) never exists — build() must
136
+ // still exit 0 and say so via ledgerState, not go silent about the refusal.
137
+ assert.equal(body.ledgerState, "unread");
138
+ });
139
+
140
+ test("no --spend-since at all is not an error — the panel is simply unscoped", () => {
141
+ const r = runBoard([]);
142
+ assert.equal(r.status, 0, r.stderr);
143
+ const body = JSON.parse(r.stdout);
144
+ assert.equal(body.spend.since, null);
145
+ assert.equal(body.ledgerState, "unread");
146
+ });
147
+
148
+ // ── #1583: --spend-dir on the one-shot path ──────────────────────────────────
149
+ //
150
+ // `build` is one gather per process, so it takes the OVERRIDE without needing
151
+ // the pin serve() carries — the same split --spend-since already has, and the
152
+ // reason the read sits in gather()'s default rather than only in serve().
153
+ //
154
+ // This rig is what makes "overrode" observable: runBoard()'s $HOME always holds
155
+ // a resolvable session at the encoded cwd, so the heuristic has a real answer
156
+ // of its own and a flag that did nothing would still produce a panel.
157
+ test("build: --spend-dir reads the named directory instead of the session the heuristic picks", () => {
158
+ const root = mkdtempSync(join(tmpdir(), "since-named-"));
159
+ const dir = join(root, "2026-08-25T09-00-00-000Z_abcdef12-3456-7890-abcd-ef1234567890");
160
+ mkdirSync(dir, { recursive: true });
161
+ writeFileSync(join(dir, "named.jsonl"), ompTurn(2000));
162
+ const r = runBoard(["--spend-dir", dir]);
163
+ assert.equal(r.status, 0, r.stderr);
164
+ const spend = JSON.parse(r.stdout).spend;
165
+ assert.equal(spend.ok, true, r.stderr);
166
+ assert.equal(spend.totals.cacheWrite, 2000, "the panel came from the heuristic's session, not the named one");
167
+ assert.equal(spend.top[0].label, "named");
168
+ });
169
+
170
+ test("build: with no --spend-dir the panel still comes from the heuristic, unchanged by this flag existing", () => {
171
+ // The other half of the same guard, and the one that catches the plausible
172
+ // wiring slip: a `spendDir` defaulted to `null` rather than left absent
173
+ // reads as "resolved, no session yet" and blanks this panel on every
174
+ // subcommand at once, with nothing on stderr to say so.
175
+ const r = runBoard([]);
176
+ assert.equal(r.status, 0, r.stderr);
177
+ const spend = JSON.parse(r.stdout).spend;
178
+ assert.equal(spend.ok, true, r.stderr);
179
+ assert.equal(spend.totals.cacheWrite, 1000);
180
+ });
181
+
182
+ test("build: --spend-dir naming a directory that does not exist yet is accepted, not refused", () => {
183
+ // The invocation this flag exists for, and the one an existence check at the
184
+ // guard would refuse: a session directory is not created until its own
185
+ // launch, and the cockpit launches in run-team phase 0, before that. The
186
+ // operator names the directory; it appears seconds later. Until then the
187
+ // panel hides — never zeroes, and never a refusal.
188
+ const r = runBoard(["--spend-dir", join(mkdtempSync(join(tmpdir(), "since-absent-")), "2026-08-26T09-00-00-000Z_01a08126-ee04-7095-a695-14e3249f1128")]);
189
+ assert.equal(r.status, 0, r.stderr);
190
+ const spend = JSON.parse(r.stdout).spend;
191
+ assert.equal(spend.ok, false, "an unreadable named directory must not report spend");
192
+ assert.equal(spend.totals, undefined, "and must not render a zeroed total in its place");
193
+ // The override really did override: the heuristic's session is still sitting
194
+ // there readable, and a fallback to it would have produced a panel.
195
+ assert.doesNotMatch(r.stdout, /"cacheWrite":1000/);
196
+ });
197
+
198
+ // One omp member transcript in the measured line shape (member-record.mjs's
199
+ // foldOmpTranscript comment). #1717: a toolCall/toolResult pair ahead of the
200
+ // billing turn, so this fixture is the one place the merged tool table's
201
+ // numbers survive the real CLI subprocess + JSON.stringify/JSON.parse
202
+ // boundary — every other assertion on this shape calls gatherSpend()/
203
+ // attributeTools() in-process. The call turn itself bills 0, so `cacheWrite`
204
+ // below still lands whole on the total AND (via the pending result batch)
205
+ // wholly attributed to "read".
206
+ const OMP_SESSION = "2026-09-08T13-13-27-300Z_01a08126-ee04-7095-a695-14e3249f1127";
207
+ const ompMember = (cacheWrite) => [
208
+ { type: "session", version: 3, id: "s1", timestamp: "2026-09-08T15:11:49.444Z", cwd: "/w" },
209
+ { type: "session_init", id: "i1", parentId: null, timestamp: "2026-09-08T15:11:49.495Z", task: "Implement ticket 7", agent: "fleet-implementer" },
210
+ { type: "message", id: "m1", parentId: "i1", timestamp: "2026-09-08T15:11:59.000Z",
211
+ message: { role: "assistant", stopReason: "toolUse", content: [{ type: "toolCall", id: "t1", name: "read", arguments: {}, intent: "x" }],
212
+ model: "claude-opus-5", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { total: 0 } } } },
213
+ { type: "message", id: "m2", parentId: "m1", timestamp: "2026-09-08T15:11:59.500Z",
214
+ message: { role: "toolResult", toolCallId: "t1", toolName: "read", content: [{ type: "text", text: "x".repeat(100) }], details: {}, isError: false, timestamp: 0 } },
215
+ { type: "message", id: "m3", parentId: "m2", timestamp: "2026-09-08T15:12:00.000Z",
216
+ message: { role: "assistant", content: [{ type: "text", text: "ok" }], model: "claude-opus-5", usage: { input: 1, output: 3, cacheRead: 40, cacheWrite, totalTokens: 0, cost: { total: 0.01 } } } },
217
+ ].map((l) => JSON.stringify(l)).join("\n") + "\n";
218
+
219
+ // The session dir as omp lays it out, with its main-session FILE beside it
220
+ // carrying a number that only a wrong read could put on the panel.
221
+ function ompSessionAt(proj) {
222
+ const dir = join(proj, OMP_SESSION);
223
+ mkdirSync(dir, { recursive: true });
224
+ writeFileSync(join(dir, "impl-7.jsonl"), ompMember(3000));
225
+ writeFileSync(join(proj, `${OMP_SESSION}.jsonl`), ompMember(999_999));
226
+ return dir;
227
+ }
228
+
229
+ test("build: the panel comes from this workspace's own omp session, with its tool table intact", () => {
230
+ // The default path, no flag: the child's cwd sits OUTSIDE HOME, so this
231
+ // also drives encodeProjectDir's realpath-wrapped form through the real
232
+ // process.cwd().
233
+ const r = runBoard([], undefined, (home, cwd) => {
234
+ ompSessionAt(join(home, ".omp", "agent", "sessions", encodeProjectDir(cwd, { home })));
235
+ });
236
+ assert.equal(r.status, 0, r.stderr);
237
+ const spend = JSON.parse(r.stdout).spend;
238
+ assert.equal(spend.ok, true, r.stderr);
239
+ assert.equal(spend.totals.cacheWrite, 3000);
240
+ assert.deepEqual(spend.top.map((t) => [t.label, t.role, t.model]), [["impl-7", "implementer", "claude-opus-5"]]);
241
+ assert.deepEqual(spend.tools.map((t) => [t.tool, t.calls, t.resultChars, t.cacheWrite]), [["read", 1, 100, 3000]]);
242
+ assert.equal(spend.attributedPct, 100);
243
+ });
244
+
245
+ test("build: --spend-dir accepts a session directory over a heuristic that resolves elsewhere", () => {
246
+ // runBoard's default seed gives the heuristic a session of its own (1000),
247
+ // so these numbers can only arrive through the named directory.
248
+ const dir = ompSessionAt(mkdtempSync(join(tmpdir(), "since-omp-")));
249
+ const r = runBoard(["--spend-dir", dir]);
250
+ assert.equal(r.status, 0, r.stderr);
251
+ const spend = JSON.parse(r.stdout).spend;
252
+ assert.equal(spend.ok, true, r.stderr);
253
+ assert.equal(spend.totals.cacheWrite, 3000);
254
+ assert.equal(spend.top[0].label, "impl-7");
255
+ });
256
+
257
+
258
+ // #366: the SECOND --interval read site. gather()'s own argInterval() fallback
259
+ // — reached only through `build`, after the same gh reads as --spend-since
260
+ // above — is distinct from serve()'s (pinned in board.test.mjs) and a fix
261
+ // there alone would leave this one still silently defaulting.
262
+ test("build: --interval abc is refused, not silently read as the 15s default", () => {
263
+ const r = runBoard(["--interval", "abc"]);
264
+ assert.equal(r.status, 2, r.stderr);
265
+ assert.match(r.stderr, /--interval wants seconds > 0 and <= 2147483, got abc/);
266
+ });
267
+
268
+ test("build: --interval 0, a negative value and an over-range value are all refused", () => {
269
+ for (const v of ["0", "-5", "3000000"]) {
270
+ const r = runBoard(["--interval", v]);
271
+ assert.equal(r.status, 2, `expected exit 2 for ${v}: ${r.stderr}`);
272
+ assert.match(r.stderr, /--interval wants seconds > 0 and <= 2147483/);
273
+ }
274
+ });
275
+
276
+ test("build: a valid --interval survives the guard and reaches the payload", () => {
277
+ const r = runBoard(["--interval", "42"]);
278
+ assert.equal(r.status, 0, r.stderr);
279
+ const body = JSON.parse(r.stdout);
280
+ assert.equal(body.interval, 42);
281
+ // This case's default ledger file (nope.md) never exists — build() must
282
+ // still exit 0 and say so via ledgerState, not go silent about the refusal.
283
+ assert.equal(body.ledgerState, "unread");
284
+ });
285
+
286
+ // ── #363: the pipe-race that motivated this file's --spend-since rig ──────────
287
+ //
288
+ // Same reason this file exists at all (see header): the --spend-since guard
289
+ // fires only AFTER gather()'s gh reads, and tryRun() (board.mjs) runs each
290
+ // one through execRead's async `execFile`, passing no `stdio` option. That
291
+ // CAPTURES the child's stderr rather than inheriting it, and re-emits it
292
+ // through board.mjs's OWN process.stderr — the child never touches an
293
+ // inherited fd 2. So the write that has to clear the pipe before die() can
294
+ // land is board.mjs's own, and on a pipe that is an async stream write:
295
+ // whatever is still queued when process.exit() runs is discarded. Going
296
+ // through execFile rather than execFileSync does not change this: the read
297
+ // side moved from sync to async, but the re-emitting write itself was always
298
+ // `process.stderr.write`, a non-blocking pipe write either way.
299
+ //
300
+ // Measured, both shapes, each parent flooding 200,000 B and then exiting,
301
+ // read by a spawn() reader identical to runBoardFlooded's — tryRun's
302
+ // no-stdio form delivers 65,536 B, while stdio [..., "inherit"], which is
303
+ // what actually inherits fd 2, delivers all 200,000.
304
+ //
305
+ // #367 fixed the write itself (writeSync, not console.error — see arg.mjs),
306
+ // but nothing drove the race that motivated it. This does, and it is the
307
+ // non-flaky shape the ticket asks for — deliberately NOT candidates.test.mjs's
308
+ // EAGAIN test, which pins a different failure (the exit CODE inverting to 1,
309
+ // not the message vanishing), is racy by its own account (its comment: "7/15
310
+ // unfixed runs inverted"), and says darwin never fires it at all.
311
+ //
312
+ // Driven through this test's own rig, against a die() reverted to
313
+ // console.error: the refusal is dropped every run and delivered stderr caps
314
+ // at exactly 65,536 B, at 66,000 / 200,000 / 2,000,000 alike. The shipped
315
+ // writeSync die() delivers 65,599 B at every one of those sizes — the same
316
+ // cap plus the refusal.
317
+ //
318
+ // This ran darwin-only until #951, behind "the loss was measured on darwin and
319
+ // nowhere else". That was true of the measurement, not of the loss — nobody had
320
+ // driven this scenario on Linux, and the gate's own wording is what stopped
321
+ // anyone re-checking. Driven on it now, 100 runs per arm, ubuntu-24.04 /
322
+ // node 26.5.0 (this repo's CI runner and its .nvmrc), same rig as below:
323
+ //
324
+ // build refusal LOST stderr bytes distinct
325
+ // die() = writeSync (PIPE) 0/100 146239-182783 2
326
+ // die() = console.error (PIPE) 100/100 146176 1
327
+ // die() = console.error (FILE) 0/100 600187 1
328
+ //
329
+ // The mutant drops the refusal on every Linux run, at one byte count, so the
330
+ // platform gate was hiding real coverage rather than protecting a vacuous
331
+ // green. It is gone, and this file no longer reads process.platform at all.
332
+ //
333
+ // It was the last one: no test in this suite is now gated on the platform, so
334
+ // nothing here is unexercised on CI by construction the way #337 found. The
335
+ // conditional skips that remain — candidates.test.mjs's gojq gate and the
336
+ // SKIP_WITHOUT_REPO sweeps — are runtime-capability gates that CI provisions
337
+ // for and does execute. A non-zero `skipped` on CI is therefore a real signal
338
+ // again rather than the permanent floor it used to be, which is the residue
339
+ // #337 left and #951 closes.
340
+ //
341
+ // The FILE row is the control that removal rests on, and it is why the stdio
342
+ // below must stay a pipe: on a file fd the same mutant keeps the refusal 100/100
343
+ // and delivers all 600,187 bytes, so a harness capturing to a file would pass
344
+ // whether or not die() was ever fixed.
345
+ //
346
+ // Two sampling notes, both recorded because each misleads on its own:
347
+ //
348
+ // - A SINGLE Linux run of the mutant delivered all 600,187 bytes with the
349
+ // refusal intact. The loss is deterministic under the back-to-back load of
350
+ // a repeated run and absent in one isolated shot, so n=1 is not evidence
351
+ // here in either direction, including a single green run of this test.
352
+ // - One 25-run sample of the FIXED build lost the refusal 1/25, with a
353
+ // 546,301-byte outlier. That was #889 — die()'s writeSync used to be
354
+ // unlooped, so a non-blocking pipe could short-write it — not this gate's
355
+ // subject. It did not recur over 100 further runs, and the whole test
356
+ // flaked 0/30 end to end. #889 landed die()'s bounded EAGAIN-retry loop
357
+ // (arg.mjs); if this test ever goes red on a correct build now, the
358
+ // cause is elsewhere.
359
+ //
360
+ // Nothing about the EAGAIN exit-code inversion (#299/#328) is claimed here.
361
+ // That is the other half of this file family — probabilistic, and genuinely
362
+ // darwin-immune. This is the truncation half (#176/#246/#328/#363), which is
363
+ // deterministic on both platforms. Do not merge the two.
364
+
365
+ // The stub has one job: make board.mjs's re-emission of this output a single
366
+ // write bigger than the pipe can hold. `head -c` rather than a hand-rolled
367
+ // Node writer so the bytes come off an ordinary child, as gh's do. Any size
368
+ // past the 65,536 B capacity does it, and they all behave identically —
369
+ // measured on the fixed build, 66,000 / 200,000 / 2,000,000 each deliver
370
+ // 65,599 B — so the headroom above the cap buys nothing and costs nothing.
371
+ // Named, because the guard below is tied to it: de-tune one and the other
372
+ // goes red instead of quietly vacuous.
373
+ const FLOOD_BYTES = 200_000;
374
+ const FLOOD_GH_STUB = `#!/bin/sh\nyes F | head -c ${FLOOD_BYTES} >&2\nexit 0\n`;
375
+
376
+ // One pipe buffer — the cap every measurement above lands on. The fixture has
377
+ // to clear it or this test proves nothing: shrink FLOOD_BYTES under the cap and
378
+ // the flood arrives whole, the refusal is never at risk, and all three
379
+ // assertions below pass green under the very bug they exist to pin. Asserted
380
+ // rather than trusted to the comment, because that is the failure a later
381
+ // de-tuning would introduce silently.
382
+ const PIPE_BUF = 65_536;
383
+ assert.ok(
384
+ FLOOD_BYTES > PIPE_BUF * 2,
385
+ `flood fixture must outgrow the pipe buffer with headroom: ${FLOOD_BYTES} <= ${PIPE_BUF * 2}`,
386
+ );
387
+
388
+ // Async spawn + immediate drain: `close` rather than `exit`, so every byte
389
+ // the stream ever receives is captured before assertions run, not just
390
+ // whatever arrived by the time the process exited. stdout is discarded
391
+ // rather than piped — nothing here asserts on it, and an unread pipe is one
392
+ // more thing that can stall the child.
393
+ function runBoardFlooded() {
394
+ const cwd = mkdtempSync(join(tmpdir(), "since-flood-cwd-"));
395
+ const bin = mkdtempSync(join(tmpdir(), "since-flood-bin-"));
396
+ writeFileSync(join(bin, "gh"), FLOOD_GH_STUB);
397
+ chmodSync(join(bin, "gh"), 0o755);
398
+ return new Promise((resolve) => {
399
+ const child = spawn(
400
+ process.execPath,
401
+ [BOARD, "build", "--ledger", join(cwd, "nope.md"), "--spend-since", "notanumber"],
402
+ { cwd, env: { ...process.env, PATH: `${bin}:${process.env.PATH}` }, stdio: ["ignore", "ignore", "pipe"] },
403
+ );
404
+ let stderr = "";
405
+ child.stderr.on("data", (d) => (stderr += d));
406
+ child.on("close", (status) => resolve({ status, stderr }));
407
+ });
408
+ }
409
+
410
+ test(
411
+ "build: --spend-since's refusal survives a gh child that has already pushed past the pipe buffer, unread",
412
+ async () => {
413
+ const r = await runBoardFlooded();
414
+ // The flood must have OVERRUN the pipe, not arrived whole — and tied to
415
+ // FLOOD_BYTES this is exact rather than a heuristic: gather() re-emits
416
+ // three of these, so delivering even the FIRST one intact already puts
417
+ // r.stderr at >= FLOOD_BYTES. Landing below it means the first re-write
418
+ // was cut short, which is the loss this test exists for.
419
+ //
420
+ // A literal 65,536 floor fails open instead, because r.stderr sums all
421
+ // three calls: three sub-cap floods total past it while every one of
422
+ // them arrives complete, refusal included. Measured against a
423
+ // console.error die() at 22,000 B — 66,188 delivered, refusal PRESENT,
424
+ // all three assertions here green under the very bug they pin. That
425
+ // darwin-era (65,536 mutant, 65,599 fixed) pair reads as headroom this
426
+ // gate no longer has: the 100-run Linux measurement above puts the real
427
+ // outcomes at 146,176 (mutant) and 146,239-182,783 (fixed) — within
428
+ // ~17,217 B of FLOOD_BYTES, not far below it. The #889 outlier
429
+ // (546,301 B) clears FLOOD_BYTES outright, so it would fail this
430
+ // overrun assertion too, not only the refusal-match below.
431
+ assert.ok(
432
+ r.stderr.length < FLOOD_BYTES,
433
+ `gh's flood must overrun the pipe, not arrive whole: got ${r.stderr.length} of ${FLOOD_BYTES}`,
434
+ );
435
+ assert.match(r.stderr, /board: --spend-since wants epoch milliseconds, got notanumber/);
436
+ assert.equal(r.status, 2, r.stderr.slice(-300));
437
+ },
438
+ );
439
+
440
+ // #365: board.mjs's known set is the UNION over both subcommands, so every
441
+ // name in it has to survive a run of either one. Driven on `build` because
442
+ // runBoard already has the rig; --port/--open are read only by serve() and are
443
+ // accepted-and-ignored here, which is the pre-existing gap board.mjs's own
444
+ // comment names and #365 does not close.
445
+ //
446
+ // A name dropped from that set refuses an invocation board.mjs accepts. Other
447
+ // tests pass most of these names too and redden alongside — measured, all six
448
+ // do, so this is NOT the only row that would go red. What it adds is the WHOLE
449
+ // set in a single run: `--prev` appears elsewhere only as the value placeholder
450
+ // in board.test.mjs's `--ledger followed by another flag` case, incidental
451
+ // cover a rename would remove, and a name added to the set later has exactly
452
+ // one row obliged to carry it.
453
+
454
+ // #468 AC-4: build now validates --port/--open's SHAPE (moved in board.mjs's
455
+ // main(), tested malformed in board.test.mjs, which can drive that case
456
+ // without this file's gh-stub rig because the guard dies before gather()'s
457
+ // first gh read) — but never reads either VALUE. build has no server to bind
458
+ // or browser to open, so a well-formed --port/--open behaves exactly as
459
+ // before this fix: accepted, unused, board built and printed at exit 0. This
460
+ // is the ruling's other half and the one a malformed-only suite cannot see —
461
+ // it must NOT newly refuse a caller who typed the flag correctly.
462
+ test("build: a well-formed --port/--open is accepted and simply unused, per the #468 ruling", () => {
463
+ const r = runBoard(["--port", "9999", "--open"]);
464
+ assert.equal(r.status, 0, r.stderr);
465
+ assert.equal(JSON.parse(r.stdout).spend.since, null);
466
+ });
467
+
468
+ test("every flag board.mjs accepts survives the unknown-flag sweep in one build", () => {
469
+ const r = runBoard([
470
+ "--prev", "nope.json",
471
+ "--spend-since", String(Date.now() - 3_600_000),
472
+ "--interval", "42",
473
+ "--port", "0",
474
+ "--open",
475
+ ]);
476
+ assert.equal(r.status, 0, `a working invocation was refused: ${r.stderr}`);
477
+ // NOT subsumed by the status assertion above: gather() reaches ledger.mjs
478
+ // through tryRun(), which forwards the child's stderr and then swallows its
479
+ // failure, so a fleet sibling refusing a flag board.mjs passed it lands on
480
+ // this stderr at exit 0 (measured). ledger.mjs still parses --file by hand,
481
+ // so that skew is live, not hypothetical. ci-state.test.mjs's sibling test
482
+ // carried this same line and there it WAS subsumed — dropped, not forgotten.
483
+ assert.doesNotMatch(r.stderr, /unknown flag/);
484
+ assert.equal(JSON.parse(r.stdout).interval, 42);
485
+ });
486
+
487
+ // ── #807: a ledger read big enough to hit node's default stdout cap ──────────
488
+ //
489
+ // `tryRun` runs every board read through `execFileSync`, and with no
490
+ // `maxBuffer` node applies its default stdout cap and KILLS the child past it
491
+ // rather than truncating. In `tryRun` that throw is indistinguishable from an
492
+ // unreachable tool: the read degrades to `tryParse`'s empty ledger and the
493
+ // cockpit renders a board with nothing on it at HTTP 200, one stderr line the
494
+ // only trace. That is #246's own symptom — #803 moved the cliff up from the
495
+ // pipe buffer rather than removing it.
496
+ //
497
+ // Pinned on the ACCEPT side, deliberately. Asserting the failure shape instead
498
+ // would stay green on a board.mjs that refused the oversized read outright,
499
+ // and a refusal is not the fix: the ledger grows for the life of a run, so the
500
+ // read has to keep working, not fail more legibly.
501
+ //
502
+ // This file rather than board.test.mjs for the reason in the header: the read
503
+ // happens inside gather(), which cannot be driven in-process, and the rig that
504
+ // stubs `gh` out of the way already lives here.
505
+ const OVERSIZED_ROWS = 4000;
506
+
507
+ // The row shape `ledger.mjs row` actually writes, padded so the JSON payload
508
+ // clears the cap. Padding rather than more rows keeps the fixture's cost in
509
+ // bytes instead of in parse work. Every row gets its own key, so a read that
510
+ // arrived short cannot satisfy the count assertions by coincidence.
511
+ function oversizedLedger() {
512
+ const section = (kind) => Array.from(
513
+ { length: OVERSIZED_ROWS },
514
+ (_, i) => `- #${i} ${kind}-${i} · class=routine · ${"pad".padEnd(120, "x")}`,
515
+ ).join("\n");
516
+ return `# Fleet run ledger\n\n## Rows\n\n${section("impl")}\n\n## Filed\n\n${section("finding")}\n\n## Ruled\n\n${section("pr")}\n`;
517
+ }
518
+
519
+ test("build: a ledger read past node's default stdout cap arrives whole, not as an empty board", () => {
520
+ const dir = mkdtempSync(join(tmpdir(), "board-big-ledger-"));
521
+ const ledger = join(dir, "ledger.md");
522
+ writeFileSync(ledger, oversizedLedger());
523
+
524
+ // Calibration, not decoration. It proves THIS fixture still exercises the
525
+ // capped mode on the node running the suite, using the exact call shape
526
+ // board.mjs had before the fix. Without it, a fixture that drifted under the
527
+ // cap — or a node whose default rose above it — leaves everything below
528
+ // passing over a read that was never at risk, which is the vacuous green
529
+ // this test exists to refuse.
530
+ assert.throws(
531
+ () => execFileSync(process.execPath, [LEDGER, "--file", ledger, "read"], { encoding: "utf8" }),
532
+ (e) => e.code === "ENOBUFS",
533
+ "fixture no longer clears node's default stdout cap — enlarge it; the assertions below prove nothing without this",
534
+ );
535
+
536
+ const r = runBoard([], ledger);
537
+ assert.equal(r.status, 0, r.stderr);
538
+ const board = JSON.parse(r.stdout);
539
+ // Counts, not emptiness: `tickets: 0` is what the bug produced, but so is a
540
+ // read that came back with some rows and lost the rest.
541
+ assert.equal(board.tickets.length, OVERSIZED_ROWS, `tickets lost: ${r.stderr.slice(-300)}`);
542
+ assert.equal(board.filed.length, OVERSIZED_ROWS, `filed rows lost: ${r.stderr.slice(-300)}`);
543
+ // The read must not have been reported as failed either — the stub `gh`
544
+ // failures on the same stderr are expected and are not this read.
545
+ assert.doesNotMatch(r.stderr, /ledger\.mjs[^\n]*failed/);
546
+ });
547
+
548
+ // ── #1093: a fault is not a refusal ──────────────────────────────────────────
549
+ //
550
+ // `main().catch()` used to hand every rejection to die(), the REFUSAL helper,
551
+ // so a bug in this script printed what a typo prints: one `board: <text>` line
552
+ // at exit 2, stack dropped.
553
+ //
554
+ // The fault driven here is the gap gather()'s own comment names and accepts:
555
+ // `tryParse` checks the ledger read is JSON, never that it is the
556
+ // `{rows,filed,ruled}` shape, because ledger.mjs is this repo's own tested
557
+ // producer of it. That read is `tryRun("node", [ledger.mjs, ...])`, backed by
558
+ // async `execFile` (see execRead in board.mjs), so a
559
+ // `node` earlier on PATH is the entire fixture, and a wrong-typed `rows`
560
+ // reaches compute-board.mjs's `(ledger.rows || []).map` with nothing between
561
+ // the TypeError and main()'s catch.
562
+ //
563
+ // Deliberately NOT the `--prev` route the ticket used to reach the handler: a
564
+ // previous board that parses but carries a wrong-typed `tickets` is a SEPARATE
565
+ // defect (a corrupt prev board is meant to be ignored, not fatal), and a test
566
+ // riding on it would turn green-and-vacuous the day that one is fixed. This
567
+ // route rests on a documented non-guard instead of a broken one.
568
+ // Split from the spawn itself so the timing test below can drive the same
569
+ // fixture through python3's saturated-pipe rig instead of spawnSync.
570
+ function boardFaultFixture() {
571
+ const cwd = realpathSync(mkdtempSync(join(tmpdir(), "board-fault-cwd-")));
572
+ const bin = mkdtempSync(join(tmpdir(), "board-fault-bin-"));
573
+ writeFileSync(join(bin, "gh"), "#!/bin/sh\nexit 1\n");
574
+ chmodSync(join(bin, "gh"), 0o755);
575
+ // Valid JSON, wrong shape: `rows` is an object where every consumer wants an
576
+ // array. Answers any argv, which is all gather()'s single `node` read needs.
577
+ writeFileSync(join(bin, "node"), `#!/bin/sh\necho '{"rows":{},"filed":[],"ruled":[]}'\n`);
578
+ chmodSync(join(bin, "node"), 0o755);
579
+ return {
580
+ cwd,
581
+ argv: [BOARD, "build", "--ledger", join(cwd, "nope.md")],
582
+ env: { ...process.env, HOME: cwd, PATH: `${bin}:${process.env.PATH}` },
583
+ };
584
+ }
585
+
586
+ function runBoardFaulted() {
587
+ const { cwd, argv, env } = boardFaultFixture();
588
+ return spawnSync(process.execPath, argv, { cwd, encoding: "utf8", env });
589
+ }
590
+
591
+ test("build: an internal fault exits 70 with a stack, where a refusal exits 2 with one line", () => {
592
+ const r = runBoardFaulted();
593
+ // Exit 0 here means the ledger shape got guarded somewhere and this fixture
594
+ // no longer reaches the handler at all — pick another reachable fault rather
595
+ // than deleting the pin.
596
+ assert.equal(r.status, 70, `expected the fault exit, got ${r.status}: ${r.stderr.slice(-400)}`);
597
+ assert.match(r.stderr, /internal fault/, "the fault must say it is one, not read as a refusal");
598
+ // A real stack, not a message: at least one frame naming the file that threw.
599
+ // This is the assertion the old `die(e.message)` handler cannot satisfy.
600
+ assert.match(r.stderr, /\n\s+at .*compute-board\.mjs:\d+/, `no stack frame on stderr: ${r.stderr.slice(-400)}`);
601
+ assert.equal(r.stdout, "", "a fault must not also print a board");
602
+
603
+ // The other half of the distinction, measured in the same run rather than
604
+ // inferred from the refusal cases above: a genuine refusal is still one line
605
+ // at exit 2 with no stack and no stdout. `--port abc` dies in main() ahead of
606
+ // every read, so it needs none of the rig above.
607
+ const refusal = spawnSync(process.execPath, [BOARD, "build", "--port", "abc"], { encoding: "utf8" });
608
+ assert.equal(refusal.stderr, "\nboard: --port wants an integer 0-65535, got abc\n");
609
+ assert.equal(refusal.status, 2);
610
+ assert.equal(refusal.stdout, "");
611
+ assert.notEqual(refusal.status, r.status, "a fault and a refusal must not share an exit code");
612
+ });
613
+
614
+ // #1547: fault()'s EAGAIN retry loop, executed rather than pinned only as
615
+ // source shape (board.test.mjs's companion pin covers the shape; this drives
616
+ // the real writeSync(2, ...) call through the fixture above). The rig mirrors
617
+ // staleness.test.mjs's verdict() test and arg.test.mjs's die() test: a real
618
+ // non-blocking stderr pipe, filled to capacity with fcntl's O_NONBLOCK before
619
+ // the child ever touches it, held open with its read end never drained.
620
+ //
621
+ // Those two tests only bound the WORST case — the loop must still give up
622
+ // and call process.exit() rather than hang — and that alone cannot tell a
623
+ // retry loop from a bare `try { writeSync(2, buf) } catch {}`: against a pipe
624
+ // that never drains, a doomed single call and a 200-retry loop both write
625
+ // nothing and both reach process.exit(FAULT_EXIT) well inside any generous
626
+ // bound. What the loop spends that a bare call does not is TIME: every
627
+ // EAGAIN costs a real syscall plus a 1ms Atomics.wait, so
628
+ // MAX_EAGAIN_RETRIES iterations measurably outlast one failed call.
629
+ //
630
+ // Isolating that from this fixture's own cost is the rest of the rig: a cold
631
+ // `build` invocation here spawns two subprocesses (the stub `node` for the
632
+ // ledger read, then `gh`) and can take single-digit SECONDS on a loaded
633
+ // machine, against ~50ms once the OS/file caches are warm (measured on this
634
+ // machine) — noise far larger than the retry loop's own cost. A discarded
635
+ // warm-up run of the IDENTICAL fixture before both timed runs cancels that
636
+ // noise; what is left is the loop's own cost. Measured on this machine: the
637
+ // real loop adds ~300-360ms over a from-/dev/null baseline of the same
638
+ // fixture; a body that calls writeSync once and swallows the exception adds
639
+ // ~20-30ms. FAULT_RETRY_FLOOR_MS sits an order of magnitude above the
640
+ // bare-call ceiling and well under the real loop's floor.
641
+ const FAULT_RETRY_FLOOR_MS = 150;
642
+
643
+ test("fault()'s writeSync loop spends real time retrying a saturated stderr, not the ~30ms a bare call would take", (t) => {
644
+ if (spawnSync("python3", ["-c", ""]).status !== 0) return t.skip("needs python3");
645
+ const { cwd, argv, env } = boardFaultFixture();
646
+
647
+ const harness = [
648
+ "import fcntl, os, subprocess, sys, time",
649
+ "argv = sys.argv[1:]",
650
+ "def run_baseline():",
651
+ " t0 = time.time()",
652
+ " r = subprocess.run(argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=60)",
653
+ " return time.time() - t0, r.returncode",
654
+ "def run_saturated():",
655
+ " r, w = os.pipe()",
656
+ " fcntl.fcntl(w, fcntl.F_SETFL, fcntl.fcntl(w, fcntl.F_GETFL) | os.O_NONBLOCK)",
657
+ " try:",
658
+ " while True:",
659
+ " os.write(w, b'x' * 65536)",
660
+ " except BlockingIOError:",
661
+ " pass",
662
+ " t0 = time.time()",
663
+ " proc = subprocess.Popen(argv, stderr=w, stdout=subprocess.DEVNULL)",
664
+ " os.close(w)",
665
+ " proc.wait(timeout=60)",
666
+ " elapsed = time.time() - t0",
667
+ " os.close(r)",
668
+ " return elapsed, proc.returncode",
669
+ "run_baseline()",
670
+ "base_t, base_code = run_baseline()",
671
+ "sat_t, sat_code = run_saturated()",
672
+ "print(f'BASE={base_t:.3f} BASE_EXIT={base_code} SAT={sat_t:.3f} SAT_EXIT={sat_code}')",
673
+ ].join("\n");
674
+
675
+ const r = spawnSync("python3", ["-c", harness, process.execPath, ...argv], { cwd, env, encoding: "utf8", timeout: 120_000 });
676
+ assert.equal(r.status, 0, `harness itself failed: ${r.stderr}`);
677
+ const m = r.stdout.match(/^BASE=(\d+\.\d+) BASE_EXIT=(-?\d+) SAT=(\d+\.\d+) SAT_EXIT=(-?\d+)$/m);
678
+ assert.ok(m, `harness printed no timing line: stdout=${r.stdout} stderr=${r.stderr}`);
679
+ const [, baseS, baseExit, satS, satExit] = m;
680
+ assert.equal(Number(baseExit), 70, `baseline run did not reach the fault exit: ${r.stdout}`);
681
+ assert.equal(Number(satExit), 70, `saturated run did not reach the fault exit: ${r.stdout}`);
682
+ const deltaMs = (Number(satS) - Number(baseS)) * 1000;
683
+ assert.ok(
684
+ deltaMs > FAULT_RETRY_FLOOR_MS,
685
+ `fault() against a saturated stderr took only ${deltaMs.toFixed(0)}ms more than baseline — the retry ` +
686
+ `loop must spend real time on EAGAIN, not return almost immediately like a bare call: ${r.stdout}`,
687
+ );
688
+ // No upper bound here: MAX_EAGAIN_RETRIES capping the loop rather than
689
+ // spinning forever against a reader that never drains is board.test.mjs's
690
+ // job (the regex pin anchors the cap and the break condition) — this test's
691
+ // job is only the floor above. An upper bound here would also be the first
692
+ // thing to false-positive under real scheduling contention, since each
693
+ // Atomics.wait(…, 1) is a 1ms TARGET, not a guarantee, under load.
694
+ });