@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,579 @@
1
+ // Pure board-model builder. No I/O and no clock read — `now` is passed in, so
2
+ // dwell/staleness is deterministic and unit-testable. board.mjs does the gh/
3
+ // ledger I/O and calls computeBoard(); every stage-derivation and flag decision
4
+ // lives here and is exercised by compute-board.test.mjs (`node --test`).
5
+ //
6
+ // #1597, #1820, #1839: the THREE imports this module takes, all pure ones.
7
+ // fleet-state.mjs owns the heartbeat's `beat` key, and the rule for reading
8
+ // that key travels with it rather than being copied here. That module's own
9
+ // I/O (its path probe, its file read) is never called from this file; only
10
+ // assessBeat/isStalled/stallReport are, all of which are functions of their
11
+ // arguments. Importing the rule is what keeps the cockpit's stall wording and
12
+ // fleet-tick's identical — two spellings of "this run is dead" would be two
13
+ // answers the operator has to reconcile at 3am.
14
+ // ledger-grammar.mjs owns the member grammar (`<member>` live,
15
+ // `<member>=<outcome>` settled) and has no I/O at all; parseToken is read
16
+ // from it for the same reason — one grammar, one reader, so the cockpit and
17
+ // fleet-tick.mjs cannot disagree about which members are live.
18
+ // fleet-tick.mjs owns a row's PR reading, PR_MENTION, and a row with no impl
19
+ // token is read through it (#1820 amendment 2a, below) so both readers name
20
+ // the same PR for the same text, for a row that carries a PR-bound signal —
21
+ // an unsignaled row (no mention, no PR-bound member, no review=/reviewed=)
22
+ // still gets pr: null here while fleet-tick.mjs's own row-key fallback keys
23
+ // it to its ticket number regardless; see the amendment note below. The
24
+ // regex is all this file takes from it: the tick's I/O and main() never run
25
+ // here, main() being guarded on argv[1].
26
+ import { assessBeat, isStalled, stallReport } from "./fleet-state.mjs";
27
+ import { parseToken, HALT_CAUSES } from "./ledger-grammar.mjs";
28
+ import { PR_MENTION, REVIEWED } from "./fleet-tick.mjs";
29
+
30
+ // A ledger row is freeform, controller-authored text. Two real examples:
31
+ // #332 impl-332=PR#344 → PR#344 → MERGED 73b356de
32
+ // #324 impl-324=PR#346 → PR#346 · fix-pr-346 · ruled:6-applies · held-behind:#313
33
+ // Extract by token, never by position — the controller reorders and appends
34
+ // tokens freely. Unknown text is ignored, never fatal.
35
+ //
36
+ // Member tokens are ledger-grammar.mjs's (#1820). On a row that has one, the
37
+ // row's latest `impl` attempt decides the card — the greatest retry suffix,
38
+ // wherever it sits (#1843, laterAttempt below): live → IMPLEMENTING, `=PR#M`
39
+ // → that PR decides, `=released`/`=bailed` → no card of
40
+ // the row's own (the POOL loop shows the ticket if it is still
41
+ // `ready-for-agent`), `=killed`/`=tier-mismatch` → IMPLEMENTING with that
42
+ // outcome as a flag. There the `→ PR#M` arrow is human-readable only;
43
+ // parseRow reads only the settled impl token's outcome. PR_MENTION is a blind
44
+ // `PR#<n>` text scan that in practice also lands on the impl token's embedded
45
+ // value, because that precedes the arrow in every row this run writes — but
46
+ // nothing enforces that order, so on such a row the arrow is never a value
47
+ // either reader may rely on.
48
+ //
49
+ // #1820 amendment 2a: a row with no `impl` token at all has no outcome to
50
+ // read, so it takes the tick's reading. `ledger.mjs dispatch <pr> fix-pr-<pr>` /
51
+ // `finisher-pr-<pr>` appends `#<pr> <member>` for a PR this run's
52
+ // implementers did not open. Once such a row carries a PR-bound signal — a
53
+ // `PR#M` mention, a `fix-pr-`/`finisher-pr-` member, `review=` or `reviewed=`
54
+ // — its PR is PR_MENTION's, else the row key, and that PR decides the card as
55
+ // `=PR#M` does. An Exclusion never takes one.
56
+ //
57
+ // A member settled anywhere on the row is settled — a bare copy beside
58
+ // `<member>=<outcome>` is what a whole-line `row` rewrite leaves.
59
+ //
60
+ // #2083: a PR whose latest finisher attempt settled `halted:<cause>` carries
61
+ // that outcome as a severity-4 flag while the PR sits in REVIEW. The halt is
62
+ // the finisher working correctly — it refused to label — so the PR has no
63
+ // `ready-to-merge` until the controller resolves the cause; the flag is what
64
+ // puts it in front of a human. "Latest" is laterAttempt's reading, among the
65
+ // finisher tokens bound to the row's own PR: a live `-b` after the halt
66
+ // clears it.
67
+ //
68
+ // A PR's review is not a member (#1773 §7): `review=wf:<runId>` is a Workflow
69
+ // with nobody to name, while `review=member:<name>` and
70
+ // `review=fallback:<name>` name a runner member, live until the token is
71
+ // settled `=failed` or a later `reviewed=` records its result.
72
+ //
73
+ // #1820 amendment 5a: a `review=` token puts the PR under review only while
74
+ // it is live. A settled `review=…=failed` is a dead review and the PR is owed
75
+ // one again, as run-team SKILL.md defines review-due and as fleet-tick.mjs's
76
+ // `reviewedAny` reads the token: the PR is owed none while the row carries
77
+ // ANY live `review=` — wherever it sits, not only as the last one — or any
78
+ // `reviewed=`. A `review=` token outside the grammar is still read as live
79
+ // here; fleet-tick.mjs refuses that ledger outright, so there is no reading of
80
+ // it to agree with.
81
+ //
82
+ // `#N excluded · behind-pr:#M` / `behind-issue:#M` is an Exclusion — pool
83
+ // supply, not a claim — spelled exactly as shortlist.mjs and fleet-tick.mjs
84
+ // spell it. `#M` is an issue or PR number, or the branch name recorded before
85
+ // that PR existed.
86
+ const EXCLUDED_ROW = /^#[0-9]+[ \t]+excluded(?=[ \t]|$)([\s\S]*)$/;
87
+ const PREMISE = /\bbehind-(pr|issue):#?([^\s,;]+)/g;
88
+ // Captures the matched kind, so parseRow tells a Workflow from a runner by
89
+ // that capture instead of a second scan; see the review notes above for
90
+ // what each kind means and how `=failed` settles it.
91
+ const REVIEW = /^review=(wf|member|fallback):([^=\s]+?)(=failed)?$/;
92
+
93
+ // #1843: which of two well-formed impl tokens is the later attempt for THIS
94
+ // row's ticket. A token whose number matches the row's own ticket always
95
+ // outranks one that does not: a retry suffix only orders attempts on ONE
96
+ // number (ledger-grammar.mjs's MEMBER regex comment — "Attempts on one
97
+ // number order by it"), so comparing retry across a different ticket's
98
+ // number is meaningless and must never let a foreign token's suffix beat
99
+ // this ticket's own token (a dead-attempt-masks-a-live-implementer regression
100
+ // by a different mechanism than the one this ticket fixes). Within one
101
+ // ticket, read off ledger-grammar.mjs's parsed `retry` — no suffix first,
102
+ // then by letter — never off row position, so every ordering of one row's
103
+ // same-ticket impl tokens picks the same impl/outcome/pr. Between two
104
+ // distinct foreign numbers (a shape nothing writes), the greater number
105
+ // wins; two copies of one name tie, and its outcome is `implOutcomes`'
106
+ // latest settle.
107
+ const laterAttempt = (a, b, ticket) => {
108
+ const aOwn = a.number === ticket, bOwn = b.number === ticket;
109
+ if (aOwn !== bOwn) return aOwn;
110
+ return (a.retry ?? "") !== (b.retry ?? "") ? (a.retry ?? "") > (b.retry ?? "") : a.number > b.number;
111
+ };
112
+
113
+ export function parseRow(row) {
114
+ const issueM = row.match(/^#(\d+)\b/);
115
+ if (!issueM) return null;
116
+ const ticket = Number(issueM[1]);
117
+ const mergedM = row.match(/\bMERGED\s+([0-9a-f]{7,40})\b/i);
118
+ const heldM = row.match(/\bheld-behind[:\s]+#?(\d+)\b/i);
119
+ const causes = [];
120
+ for (const t of ["KILLED", "BLOCKED", "SHA-OFF-BRANCH"]) {
121
+ if (new RegExp(`\\b${t}\\b`).test(row)) causes.push(t.toLowerCase());
122
+ }
123
+ const ex = EXCLUDED_ROW.exec(row);
124
+
125
+ // `live` holds live entries in row order, each one of two kinds: a
126
+ // ledger-grammar member (`kind: "member"`, its parsed token as `token`) or
127
+ // a review runner a `review=member:`/`review=fallback:` token names
128
+ // (`kind: "runner"`, a name and nothing else — it is no ledger-grammar
129
+ // member, so it has none of a parsed token's fields). A runner carries no
130
+ // `token`, so reading a member field off one through `.token` throws
131
+ // rather than reading `undefined`. `implOutcomes` holds each impl name's
132
+ // latest well-formed outcome: only an impl outcome decides a card. A
133
+ // malformed outcome is still a settle — never counted live, never decides
134
+ // a card — but it is not silently dropped either: it earns the row a
135
+ // `ledger-error` flag (deriveFlags below), the same "refuse rather than
136
+ // guess" contract ledger-grammar.mjs's own docstring states `.error`
137
+ // exists for.
138
+ const live = [];
139
+ const implOutcomes = new Map();
140
+ const finisherOutcomes = new Map();
141
+ const settled = new Set();
142
+ let lastImpl = null; // the latest well-formed impl token (laterAttempt)
143
+ const finishers = []; // well-formed finisher tokens, for the row's PR below
144
+ let anyImpl = false;
145
+ let prMember = false;
146
+ let review = false; // any review= token: a PR-bound signal (amendment 2a)
147
+ let reviewLive = false; // one not settled `=failed` (amendment 5a)
148
+ let reviewed = false;
149
+ let reviewedHead = null;
150
+ let runners = [];
151
+ let malformed = false;
152
+ for (const tok of row.split(/\s+/).filter(Boolean)) {
153
+ const t = parseToken(tok);
154
+ if (t) {
155
+ if (t.error) malformed = true;
156
+ if (t.outcome === null) live.push({ kind: "member", name: t.name, token: t });
157
+ else settled.add(t.name);
158
+ if (t.family === "impl") {
159
+ anyImpl = true;
160
+ if (!t.error) {
161
+ if (t.outcome !== null) implOutcomes.set(t.name, t.outcome);
162
+ if (!lastImpl || laterAttempt(t, lastImpl, ticket)) lastImpl = t;
163
+ }
164
+ }
165
+ if (t.family === "finisher-pr" && !t.error) {
166
+ if (t.outcome !== null) finisherOutcomes.set(t.name, t.outcome);
167
+ finishers.push(t);
168
+ }
169
+ if (t.bound === "pr") prMember = true;
170
+ continue;
171
+ }
172
+ if (tok.startsWith("review=")) {
173
+ review = true;
174
+ const [, kind, name, failed] = REVIEW.exec(tok) ?? [];
175
+ if (!failed) reviewLive = true;
176
+ if (kind === "member" || kind === "fallback") {
177
+ if (failed) settled.add(name);
178
+ else { live.push({ kind: "runner", name }); runners.push(name); }
179
+ }
180
+ } else if (tok.startsWith("reviewed=")) {
181
+ reviewed = true;
182
+ // (#2083) The head that review actually read — the cockpit's own copy
183
+ // of fleet-tick.mjs's `reviewedHead`, needed below to tell a past-pin
184
+ // halt already answered by this review apart from one still owed a
185
+ // fresh one.
186
+ const m = REVIEWED.exec(tok);
187
+ if (m) reviewedHead = m[1].toLowerCase();
188
+ for (const r of runners) settled.add(r);
189
+ runners = [];
190
+ }
191
+ }
192
+ const alive = live.filter((e) => !settled.has(e.name));
193
+ const implOutcome = lastImpl ? (implOutcomes.get(lastImpl.name) ?? null) : null;
194
+ const prM = implOutcome && /^PR#(\d+)$/.exec(implOutcome);
195
+ let pr = prM ? Number(prM[1]) : null;
196
+ // #1820 amendment 2a: a row with NO impl token — a malformed one still
197
+ // counts, since that row's key is a ticket — is keyed, once THIS row
198
+ // carries a PR-bound signal, the way fleet-tick.mjs's PR_MENTION-then-
199
+ // row-key logic would: its first PR_MENTION (itself a signal), else the
200
+ // row key when the first word is exactly `#N`. fleet-tick.mjs's own
201
+ // row-key fallback (deriveRun) is NOT itself gated on a signal — this
202
+ // module's extra gate exists so an ordinary unclaimed ticket never
203
+ // borrows its own number as a phantom PR. An Exclusion is supply and
204
+ // never takes a PR, whatever text it carries.
205
+ if (!anyImpl && !ex) {
206
+ const mention = PR_MENTION.exec(row);
207
+ if (mention) pr = Number(mention[1]);
208
+ else if ((prMember || review || reviewed) && row.split(/\s/)[0] === issueM[0]) pr = Number(issueM[1]);
209
+ }
210
+ let lastFinisher = null;
211
+ for (const t of finishers) {
212
+ if (t.number === pr && (!lastFinisher || laterAttempt(t, lastFinisher, pr))) lastFinisher = t;
213
+ }
214
+ return {
215
+ issue: Number(issueM[1]),
216
+ excluded: ex ? [...ex[1].matchAll(PREMISE)].map(([, kind, target]) => ({ kind, target })) : null,
217
+ impl: lastImpl?.name ?? null,
218
+ implOutcome,
219
+ finisherOutcome: lastFinisher ? (finisherOutcomes.get(lastFinisher.name) ?? null) : null,
220
+ agent: alive.length ? alive[alive.length - 1].name : null,
221
+ pr,
222
+ merged: !!mergedM,
223
+ sha: mergedM ? mergedM[1] : null,
224
+ heldBehind: heldM ? Number(heldM[1]) : null,
225
+ causes,
226
+ malformed,
227
+ reviewed,
228
+ reviewedHead,
229
+ underReview: reviewLive || alive.some((e) => e.kind === "member" && (e.token.family === "fix-pr" || e.token.family === "finisher-pr")),
230
+ };
231
+ }
232
+
233
+ // A parsed row's column, or null when the row claims no card of its own (a
234
+ // released or bailed implementer: the ticket went back to the tracker, and the
235
+ // POOL loop shows it if it is still `ready-for-agent`). An Exclusion is POOL.
236
+ // MERGED is an explicit `MERGED <sha>` token or, failing one, `prState.merged`
237
+ // — gh's answer for a row PR absent from the open list, or (#1841) a
238
+ // carry-forward of the previous board's MERGED for that SAME PR on that
239
+ // ticket: MERGED is terminal, so a merged PR never reopens regardless of
240
+ // what this run's merged read says — but a ticket retried under a NEW PR
241
+ // after its earlier one merged gets no such carry-forward; that new PR's
242
+ // state is unknown, not MERGED. READY needs the live PR label; any other
243
+ // PR, closed-unmerged included, is in REVIEW.
244
+ export function deriveColumn(parsed, prState) {
245
+ if (parsed.excluded) return "POOL";
246
+ if (parsed.merged) return "MERGED";
247
+ if (parsed.pr != null) {
248
+ if (prState && prState.merged) return "MERGED";
249
+ if (prState && prState.labels.includes("ready-to-merge")) return "READY";
250
+ return "REVIEW";
251
+ }
252
+ if (parsed.implOutcome === "released" || parsed.implOutcome === "bailed") return null;
253
+ return "IMPLEMENTING";
254
+ }
255
+
256
+ // Dwell thresholds per column, ms. A ticket sitting longer than this in a
257
+ // non-terminal column earns `stale`. POOL and MERGED are absent → never stale.
258
+ export const STALE_MS = {
259
+ IMPLEMENTING: 20 * 60 * 1000,
260
+ REVIEW: 45 * 60 * 1000,
261
+ READY: 15 * 60 * 1000,
262
+ };
263
+
264
+ // An Exclusion's badges are its premises, `excluded:#880` for a number and
265
+ // `excluded:<branch>` for a branch name, and nothing else: it is supply, so no
266
+ // dwell clock and no cause applies. isBadge() keeps them out of `attention`.
267
+ export function deriveFlags(parsed, ctx) {
268
+ if (parsed.excluded) {
269
+ return parsed.excluded.length
270
+ ? parsed.excluded.map(({ target }) => `excluded:${target.length > 0 && !/[^0-9]/.test(target) ? "#" : ""}${target}`)
271
+ : ["excluded"];
272
+ }
273
+ const flags = [];
274
+ if (parsed.malformed) flags.push("ledger-error");
275
+ if (ctx.ci === "red") flags.push("red-ci");
276
+ if (parsed.heldBehind != null) flags.push(`held-behind:#${parsed.heldBehind}`);
277
+ for (const c of parsed.causes) flags.push(c); // killed | blocked | sha-off-branch
278
+ const o = parsed.implOutcome;
279
+ if ((o === "killed" || o === "tier-mismatch") && !flags.includes(o)) flags.push(o);
280
+ // Only while the halt still parks the PR: once a human resolves an
281
+ // escalated halt by labelling or merging it, the flag has nothing to ask.
282
+ // `past-pin`'s own automatic resolution (SKILL.md "Resolving a finisher
283
+ // halt") re-reviews the PR through fleet-tick.mjs, but a returned
284
+ // `reviewed=` does not itself clear `finisherOutcome` here — the halt is
285
+ // answered only once "its result reaches a fresh finisher through the
286
+ // same gate" (ibid.), so the card stays flagged, same as any other halt
287
+ // cause, until that finisher settles. reviewBacklog below reads the same
288
+ // gap the other way: still counted due for a fresh review while this flag
289
+ // is up and the head has not caught up to what was reviewed.
290
+ if (parsed.finisherOutcome?.startsWith("halted:") && ctx.column === "REVIEW") flags.push(parsed.finisherOutcome);
291
+ const limit = STALE_MS[ctx.column];
292
+ if (limit != null && ctx.sinceEnteredStage != null && ctx.now - ctx.sinceEnteredStage > limit) {
293
+ flags.push("stale");
294
+ }
295
+ return flags;
296
+ }
297
+
298
+ const isBadge = (flag) => flag === "excluded" || flag.startsWith("excluded:");
299
+
300
+ // Internal helpers — not exported; covered through computeBoard's tests.
301
+
302
+ // Carry the stage-entry timestamp forward while the column is unchanged, else
303
+ // reset to now. This is what makes dwell self-contained in board.json, needing
304
+ // no ledger timestamps and no controller involvement.
305
+ function stageEntry(prevTicket, column, now) {
306
+ if (prevTicket && prevTicket.column === column && prevTicket.sinceEnteredStage != null) {
307
+ return prevTicket.sinceEnteredStage;
308
+ }
309
+ return now;
310
+ }
311
+
312
+ function titleFor(issue, pr, issues) {
313
+ if (pr && pr.title) return pr.title;
314
+ const i = issues.find((x) => x.number === issue);
315
+ return i ? i.title : `#${issue}`;
316
+ }
317
+
318
+ const FLAG_SEVERITY = {
319
+ "red-ci": 5, "ledger-error": 5, killed: 4, "tier-mismatch": 4, blocked: 4, "sha-off-branch": 4,
320
+ ...Object.fromEntries(HALT_CAUSES.map((c) => [`halted:${c}`, 4])),
321
+ stale: 1,
322
+ };
323
+ function severity(flags) {
324
+ let s = 0;
325
+ for (const f of flags) {
326
+ if (f.startsWith("held-behind")) s = Math.max(s, 2);
327
+ else s = Math.max(s, FLAG_SEVERITY[f] ?? 0);
328
+ }
329
+ return s;
330
+ }
331
+
332
+ function splitNumbered(line) {
333
+ const m = line.match(/^#(\d+)\s+(.*)$/);
334
+ return m ? { issue: Number(m[1]), subject: m[2] } : { issue: null, subject: line };
335
+ }
336
+
337
+ // The stall surface, or null when there is nothing to say. #1597.
338
+ //
339
+ // The two facts the report needs beyond the mark itself — what is claimed and
340
+ // whether the pool still has supply — are read off THIS model rather than
341
+ // re-queried, which is the whole reason this lives here and not in gather().
342
+ // A ticket in flight is one the ledger placed past POOL and short of MERGED:
343
+ // a row exists for it, so it was claimed, and it has not landed, so the claim
344
+ // is still outstanding. That is the same population the `in-progress` label
345
+ // marks, arrived at from the ledger instead of from a label query the cockpit
346
+ // has no reason to run.
347
+ //
348
+ // `ledgerOk`/`poolOk` gate `claimed`/`supply` at `null`, never a computed
349
+ // zero, the moment either input did not actually read — the same "unknown is
350
+ // not zero" contract fleet-state.mjs's stallReport() states in its own words
351
+ // and fleet-tick.mjs's CLI side already honours. `tickets`/`pool` derive
352
+ // straight from `ledger.rows`/`issues`, which reduce to the empty array on
353
+ // either a genuinely empty read AND a failed one alike (gather()'s tryRun/
354
+ // tryParse fallback) — so without this gate, a `gh`/ledger outage prints the
355
+ // exact same "0 claimed, pool supply 0" a healthy drained run would, which is
356
+ // the one report an operator has no reason to distrust and every reason to.
357
+ //
358
+ // The verdict carries `text` — the rendered line — because board.html is
359
+ // served as one self-contained file with no imports: a page that formatted
360
+ // this itself would be a second wording of the same verdict, free to drift
361
+ // from fleet-tick's the moment either is edited. The page renders; the rule
362
+ // and its words stay here.
363
+ function stall(beat, ticked, tickets, pool, { ledgerOk, poolOk }, now) {
364
+ const verdict = assessBeat({ beat, ticked, now });
365
+ if (!isStalled(verdict)) return null;
366
+ const claimed = ledgerOk ? tickets.filter((t) => t.column !== "POOL" && t.column !== "MERGED").length : null;
367
+ const supply = poolOk ? pool : null;
368
+ return { ...verdict, claimed, supply, text: stallReport(verdict, { claimed, supply }) };
369
+ }
370
+
371
+ // #2108: which of gather()'s `gh ... list` reads came back exactly as long as
372
+ // its own `--limit` — and so may have been cut there, gh saying nothing — as
373
+ // one rendered line, or null when neither did. The pool's count carries its
374
+ // own `n+` besides (computeBoard below); this line is for what a count cannot
375
+ // say: a pool card that is not there at all, and an open PR past the cap,
376
+ // which reaches this model only through the ledger row and the merged read,
377
+ // so it renders REVIEW with CI unknown whatever its real label and run say.
378
+ // Rendered here, not on the page, for stall()'s reason just above.
379
+ function capNotice({ poolCapped, prsCapped }) {
380
+ const parts = [];
381
+ if (poolCapped) parts.push("the ready-for-agent read hit its --limit, so POOL may be missing tickets");
382
+ if (prsCapped) parts.push("the open-PR read hit its --limit, so a PR past it shows REVIEW with CI unknown");
383
+ return parts.length ? parts.join("; ") : null;
384
+ }
385
+
386
+ // #1841: the previous board already showed this SAME PR MERGED on this
387
+ // ticket. MERGED is terminal, so that verdict stands whatever this run's
388
+ // merged read says. Keyed on the PR, not just the ticket: a ticket retried
389
+ // under a NEW PR after its earlier one merged carries no MERGED verdict
390
+ // forward for that new, unrelated PR. One definition, because computeBoard()
391
+ // applies it and mergedReadPrs() skips what it covers — two copies could
392
+ // drift into a PR that neither is asked about nor carried.
393
+ function carriedMerged(prevTicket, p) {
394
+ return prevTicket?.column === "MERGED" && prevTicket.pr === p.pr;
395
+ }
396
+
397
+ // #1840: the row PRs whose merged status gather() has to ask gh about this
398
+ // tick — exactly those computeBoard() would consult `merged` for and cannot
399
+ // already place: a row PR absent from the open list `prs`, on a row that is
400
+ // not an Exclusion (always POOL), carries no `MERGED <sha>` token, has a PR
401
+ // at all, and is not carried forward as MERGED. Sorted and unique. Empty
402
+ // means no merged read is needed at all. `prev` is the previous board, as
403
+ // computeBoard() takes it.
404
+ //
405
+ // `Number.isSafeInteger(p.pr)` excludes a row whose PR mention is 22+ digits:
406
+ // `Number()` renders it in exponential form (`1e+21`), which is not a valid
407
+ // `pullRequest(number:)` argument/alias and fails gh's WHOLE batched query
408
+ // (measured: `p1e+21:pullRequest(number:1e+21)` gets GitHub's parser
409
+ // rejecting the query outright — no `data` at all, unlike a merely
410
+ // nonexistent PR number, which resolves to a per-alias NOT_FOUND beside a
411
+ // usable body). Leaving it out of `need` costs that one row the REVIEW it
412
+ // would get from a failed batch anyway, and keeps every other row PR's
413
+ // lookup intact.
414
+ export function mergedReadPrs({ ledger, prs, prev }) {
415
+ const open = new Set(prs.map((p) => p.number));
416
+ const prevByIssue = new Map((prev?.tickets || []).map((t) => [t.issue, t]));
417
+ const need = new Set();
418
+ for (const p of (ledger.rows || []).map(parseRow).filter(Boolean)) {
419
+ if (p.excluded || p.merged || p.pr == null || !Number.isSafeInteger(p.pr) || open.has(p.pr)) continue;
420
+ if (carriedMerged(prevByIssue.get(p.issue), p)) continue;
421
+ need.add(p.pr);
422
+ }
423
+ return [...need].sort((a, b) => a - b);
424
+ }
425
+
426
+ // `merged` (#1820) is gh's list of merged PR numbers, consulted only for a row
427
+ // PR absent from the open list `prs`; absent means none known, and a PR in
428
+ // neither list (closed unmerged, or a failed read) keeps REVIEW — unless
429
+ // (#1841) carriedMerged() holds for it, in which case it stays MERGED
430
+ // whether this run's merged read failed outright or simply succeeded
431
+ // without listing it. A PR that IS in the open list is never eligible for
432
+ // this carry-forward — only the "absent from both `prs` and (maybe)
433
+ // `merged`" branch below ever consults it. gather() asks gh only about
434
+ // mergedReadPrs()'s set (#1840), so `merged` never lists more than that.
435
+ export function computeBoard(inputs) {
436
+ const { ledger, issues, prs, ci, prev, now } = inputs;
437
+ const prByNum = new Map(prs.map((p) => [p.number, p]));
438
+ const mergedPrs = new Set(inputs.merged || []);
439
+ const prevByIssue = new Map((prev?.tickets || []).map((t) => [t.issue, t]));
440
+ const ruledByPr = new Map();
441
+ for (const r of ledger.ruled || []) {
442
+ const s = splitNumbered(r);
443
+ if (s.issue != null) ruledByPr.set(s.issue, s.subject);
444
+ }
445
+
446
+ const parsed = (ledger.rows || []).map(parseRow).filter(Boolean);
447
+ const rowIssues = new Set();
448
+ const tickets = [];
449
+
450
+ for (const p of parsed) {
451
+ const pr = p.pr != null ? prByNum.get(p.pr) : undefined;
452
+ const prevTicket = prevByIssue.get(p.issue);
453
+ const prState = p.pr == null ? null
454
+ : pr ? { open: pr.state === "OPEN", labels: pr.labels || [] }
455
+ : { open: false, labels: [], merged: mergedPrs.has(p.pr) || carriedMerged(prevTicket, p) };
456
+ const column = deriveColumn(p, prState);
457
+ if (column === null) continue; // released/bailed: the POOL loop below decides
458
+ rowIssues.add(p.issue);
459
+ const sinceEnteredStage = stageEntry(prevTicket, column, now);
460
+ const ciState = p.pr != null ? (ci[p.pr] ?? "unknown") : null;
461
+ const flags = deriveFlags(p, { ci: ciState, column, sinceEnteredStage, now });
462
+ tickets.push({
463
+ issue: p.issue,
464
+ title: titleFor(p.issue, pr, issues),
465
+ column,
466
+ agent: p.agent,
467
+ pr: p.pr,
468
+ ci: ciState,
469
+ sinceEnteredStage,
470
+ flags,
471
+ ruling: p.pr != null ? (ruledByPr.get(p.pr) ?? null) : null,
472
+ });
473
+ }
474
+
475
+ // A wayfinder:* ticket is documentation-only regardless of its triage role
476
+ // (#1331): candidates.mjs's dispatch scan never surfaces one even carrying
477
+ // `ready-for-agent`, so this POOL column must not either, or an
478
+ // undispatchable ticket inflates the operator's read of available work.
479
+ // Filtered HERE rather than out of gather()'s gh query: `issues` also feeds
480
+ // titleFor() above, and a query-level exclusion silently strips a
481
+ // wayfinder-labelled issue's title lookup too, turning an unrelated ledger
482
+ // row's card into a bare `#<number>` even though only the POOL card was
483
+ // ever supposed to change.
484
+ for (const iss of issues) {
485
+ if (rowIssues.has(iss.number)) continue;
486
+ if ((iss.labels || []).some((l) => l.startsWith("wayfinder:"))) continue;
487
+ const sinceEnteredStage = stageEntry(prevByIssue.get(iss.number), "POOL", now);
488
+ tickets.push({
489
+ issue: iss.number, title: iss.title, column: "POOL", agent: null,
490
+ pr: null, ci: null, sinceEnteredStage, flags: [], ruling: null,
491
+ });
492
+ }
493
+
494
+ const attention = tickets.filter((t) => t.flags.some((f) => !isBadge(f)))
495
+ .sort((a, b) => severity(b.flags) - severity(a.flags));
496
+
497
+ // Backlog is a PR nobody has reviewed and nobody is reviewing: no live
498
+ // `review=` (#1820 amendment 5a — a settled `=failed` one is no review), no
499
+ // `reviewed=`, and no live fix-applier or finisher on the row — or (#2083)
500
+ // a returned review whose finisher halted `past-pin` against a head it
501
+ // never read: owed again until the head catches up to what `reviewed=`
502
+ // recorded, the same rule fleet-tick.mjs's reviewDue reads off headRefOid
503
+ // (pastPinDue). A PR absent from the open list (closed, not yet MERGED)
504
+ // reads as an unmatched head, never as answered — silence is not review.
505
+ const parsedByIssue = new Map(parsed.map((p) => [p.issue, p]));
506
+ const pastPinBacklog = (p) => p.finisherOutcome === "halted:past-pin" && p.reviewedHead !== null
507
+ && !String(prByNum.get(p.pr)?.headRefOid ?? "").toLowerCase().startsWith(p.reviewedHead);
508
+ const reviewBacklog = tickets.filter((t) => {
509
+ const p = parsedByIssue.get(t.issue);
510
+ return t.column === "REVIEW" && !p.underReview && (!p.reviewed || pastPinBacklog(p));
511
+ }).length;
512
+ const cardsInPool = tickets.filter((t) => t.column === "POOL").length;
513
+ // #2108: a capped pool read makes this count a floor, and it says so the way
514
+ // fleet-tick.mjs's claimed count does — `"100+"`, never a bare 100 that
515
+ // reads as exact. stall() below receives the same value, so the stall line
516
+ // and the footer cannot disagree about it.
517
+ const pool = inputs.poolCapped ? `${cardsInPool}+` : cardsInPool;
518
+
519
+ return {
520
+ generatedAt: now,
521
+ interval: inputs.interval ?? 15,
522
+ repo: inputs.repo ?? null,
523
+ repoUrl: inputs.repoUrl ?? null,
524
+ // #1584: which workspace this board describes and which port served it.
525
+ // Pass-through, exactly like repo/repoUrl above and for the same reason —
526
+ // resolveCockpitInstance() answers both at the gather boundary, and this
527
+ // module reads no cwd, no git and no socket, so it cannot re-derive either
528
+ // and must not try. Defaulted to null rather than left undefined: a
529
+ // missing key and a null one are the same value to a reader in JS but not
530
+ // in the JSON on disk, and #1585's launch handshake reads `workspace` off
531
+ // that JSON — a dropped key would make every board anonymous to it.
532
+ workspace: inputs.workspace ?? null,
533
+ port: inputs.port ?? null,
534
+ queue: { pool, supply: pool, reviewBacklog },
535
+ capNotice: capNotice(inputs),
536
+ tickets,
537
+ filed: (ledger.filed || []).map(splitNumbered),
538
+ // Not derivable from anything else in this model: a ledger that was never
539
+ // read, one read empty, and one whose payload would not parse all reduce to
540
+ // the same empty lists, which is the collapse #816 names. gather() is the
541
+ // only caller that can tell them apart, so it says so and this carries the
542
+ // answer to the page. Defaulted rather than required — every other caller
543
+ // of computeBoard builds its inputs by hand and means a ledger it read.
544
+ ledgerState: ledger.state ?? "read",
545
+ // Telemetry, not pipeline state: null when this run has produced no
546
+ // transcripts yet, `{ ok: false, error }` when they cannot be read,
547
+ // `{ ok: true, ... }` when they can. Those are deliberately not the same
548
+ // value — the UI hides the panel on null rather than rendering zeroes,
549
+ // which would read as "this run was free", and shows the error, which is
550
+ // a bug the operator has to act on.
551
+ spend: inputs.spend ?? null,
552
+ // #1597. Telemetry beside `spend`, and under the same rule: a liveness
553
+ // input can only ever POPULATE or OMIT this field, and nothing above it
554
+ // reads `inputs.beat` — no column, no flag, no dwell clock, no attention
555
+ // row. A dead controller does not move a ticket; it means nobody is
556
+ // moving the tickets, which is a different statement and belongs in a
557
+ // different field.
558
+ //
559
+ // Null for "nothing to report", which covers both a run that has never
560
+ // beaten and one that is beating normally — the page hides the banner on
561
+ // either, because a banner that fires on every healthy tick is a banner
562
+ // the operator learns to read past.
563
+ // `beat`/`ticked` pass through bare, unlike `spend` two fields up: that
564
+ // coalesce is load-bearing because the value is serialised into
565
+ // board.json as-is, while these two are only ever fed to assessBeat(),
566
+ // which already treats `undefined` and `null` identically — a `?? null`
567
+ // here would cost a line to say nothing stall() does not already do.
568
+ //
569
+ // `ledgerOk`/`poolOk` default to true absent a signal, matching
570
+ // `ledgerState`'s own `?? "read"` default just above: every caller that
571
+ // builds inputs by hand (every test in this suite) means a read that
572
+ // succeeded, and only gather() — which now sets both — can say otherwise.
573
+ liveness: stall(inputs.beat, inputs.ticked, tickets, pool, {
574
+ ledgerOk: (ledger.state ?? "read") === "read",
575
+ poolOk: inputs.poolOk ?? true,
576
+ }, now),
577
+ attention,
578
+ };
579
+ }