@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,400 @@
1
+ // The heartbeat's shared state file, owned jointly by fleet-tick.mjs and
2
+ // fleet-heartbeat.mjs — so the path and the file's shape live here rather than
3
+ // in two spellings that drift. Same rule arg.mjs states for the digits guard:
4
+ // what travels between scripts is the rule, never a copy of it.
5
+ //
6
+ // KEY OWNERSHIP, which is the whole reason two scripts can share one file
7
+ // without a lock:
8
+ //
9
+ // quiet fleet-tick only. Consecutive ticks that asked the controller for
10
+ // nothing. Drives the back-off interval.
11
+ // digest fleet-tick only. The last tick's own output, so an unchanged
12
+ // quiet tick can fold to one line instead of three.
13
+ // elapsed fleet-heartbeat only. Seconds already held toward the current
14
+ // interval, because no harness lets one command block long enough
15
+ // to serve a twenty-minute interval in a single call.
16
+ // beat fleet-heartbeat only (#1597). The liveness mark: when the beat
17
+ // was last seen, the interval that was in effect when it was, and
18
+ // a deliberate stop's reason if one was recorded. Written by the
19
+ // heartbeat and by nothing else — fleet-tick READS it at the start
20
+ // of a run and the cockpit READS it every tick, and a key two
21
+ // scripts wrote would need the lock this file exists to avoid.
22
+ // ticked fleet-tick only. When fleet-tick itself last ran, no interval
23
+ // attached — fleet-tick fires on live edges, not a schedule, so it
24
+ // has no promise to be judged against the way `beat` does. Exists
25
+ // because `beat` is only written when the queue drains ("beat when
26
+ // there is nothing to do" — SKILL.md); a busy stretch can run for
27
+ // longer than `beat`'s own grace window while fleet-tick itself
28
+ // keeps firing on every completion, and without this key that
29
+ // healthy busy run reads as a dead one the moment the OLD beat
30
+ // ages past the interval it recorded before the stretch started.
31
+ //
32
+ // One writer per key. A key both scripts wrote would need locking to be
33
+ // correct, and neither script is in a position to hold one.
34
+
35
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
36
+ import { spawnSync } from "node:child_process";
37
+ import { dirname, join } from "node:path";
38
+ import { workspaceDirFromGitCommonDir } from "./git-env.mjs";
39
+
40
+ // The filename, in one place, because #1597 gave this file a SECOND resolver.
41
+ // board.mjs already resolves the run's workspace for itself — it has to, since
42
+ // its own `canonicalise` opt-in is what keeps a symlinked route from deriving
43
+ // a second port (#1582) — so it reaches the state file by joining onto the
44
+ // `.fleet` directory it already holds rather than re-running the probe below.
45
+ // What it must NOT do is spell `heartbeat.json` a second time: a filename in
46
+ // two places is the drift this module's header exists to prevent, and a
47
+ // cockpit reading a file the heartbeat does not write is a liveness panel
48
+ // that is permanently, silently empty.
49
+ export function stateFileIn(fleetDir) {
50
+ return join(fleetDir, "heartbeat.json");
51
+ }
52
+
53
+ // There is ONE heartbeat per run and its state lives in the main checkout.
54
+ // Members run from their own worktrees, where a cwd-relative `.fleet/` does not
55
+ // exist, so a cwd-relative path would give every worktree a private back-off
56
+ // streak and a private elapsed total — the run's beat would be whichever
57
+ // worktree happened to call last.
58
+ //
59
+ // This is ledger.mjs's defaultLedgerPath() resolution applied to a second file
60
+ // for the same reason (there, a cwd-local ledger silently degraded the
61
+ // duplicate-filing guard). The third file this comment used to predict arrived
62
+ // with #1656 — board.mjs's resolveCockpitInstance() — so the resolution itself
63
+ // moved, as promised, though into git-env.mjs beside gitEnv() rather than into
64
+ // this module: board.mjs and ledger.mjs both already import that one, and a
65
+ // cockpit reaching into the heartbeat's state module for a path rule would be
66
+ // a stranger dependency than either has now (#1658). Only the filename and the
67
+ // warning below are this caller's own.
68
+ export function statePath(name) {
69
+ // GIT_DIR and GIT_WORK_TREE scrubbed, never inherited: an ambient GIT_DIR
70
+ // answers `--git-common-dir` for a DIFFERENT repository, which relocates the
71
+ // ONE file this whole design rests on. It fails in exactly the direction the
72
+ // common-dir resolution exists to close — a private streak and a private
73
+ // elapsed total per environment — and it fails SILENTLY, because a resolved
74
+ // path inside another repo looks like any other resolved path. Same scrub
75
+ // run-merge-bot.md performs on the identical command in shell (`env -u
76
+ // GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir`); spelled as an
77
+ // env object here because there is no shell to spell it in.
78
+ // Migrating this inline scrub to gitEnv() — imported in this file since
79
+ // #1658 for the path rule above, not for the env — stays out of scope: it is
80
+ // recorded with its own measurement and its own behavioural fixture in
81
+ // ambient-git-vars-mjs-prose.test.mjs's MJS_LEGACY_INLINE list.
82
+ const env = { ...process.env };
83
+ delete env.GIT_DIR;
84
+ delete env.GIT_WORK_TREE;
85
+ const r = spawnSync("git", ["rev-parse", "--git-common-dir"], { encoding: "utf8", env });
86
+ // No separate `r.status === 0` gate: every failure mode reproducible here
87
+ // (no repository, an unresolvable GIT_DIR, a permission-denied `.git`, a
88
+ // corrupt worktree pointer, a missing `git` binary) leaves `r.stdout`
89
+ // empty, which workspaceDirFromGitCommonDir() already reads as `null` on
90
+ // its own — see its own docstring for that contract.
91
+ const workspace = workspaceDirFromGitCommonDir(r.stdout);
92
+ if (workspace === null) {
93
+ // Announced, never silent: a cwd-relative fallback re-opens exactly the
94
+ // per-worktree split this resolution exists to close.
95
+ console.error(`${name}: WARNING could not resolve --git-common-dir; using cwd-relative .fleet/heartbeat.json`);
96
+ return stateFileIn(".fleet");
97
+ }
98
+ return stateFileIn(join(workspace, ".fleet"));
99
+ }
100
+
101
+ // An unreadable or corrupt state file is NOT fatal, and the direction of the
102
+ // failure is the argument: a missing streak reads as quiet=0, which is the BASE
103
+ // interval — more frequent level checks, never fewer. Dying instead would stop
104
+ // the heartbeat, and a stopped heartbeat is the defect.
105
+ //
106
+ // Absent is the ONLY silent case, because it is the only one that is not a
107
+ // fault: a fresh run legitimately has no file yet. An unreadable file and a
108
+ // corrupt one are both announced — each discards real state, and silence about
109
+ // a degraded read is the failure class this whole ticket exists to close.
110
+ export function readState(path, name) {
111
+ // `beat: null` is the absent MARK, and it is not the same value as a mark
112
+ // whose fields are zero: nothing has been seen beating, so there is nothing
113
+ // to judge and nothing to report. A zeroed mark would date the beat to the
114
+ // epoch and read as decades overdue on a run that has simply not started
115
+ // one — the cry-wolf direction this key must never fail in.
116
+ const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, rest: {} };
117
+ let raw;
118
+ try {
119
+ raw = readFileSync(path, "utf8");
120
+ } catch (e) {
121
+ // ENOENT is the only silent one, because it is the only one that is not a
122
+ // fault: a fresh run legitimately has no file yet. Every other errno is a
123
+ // file that EXISTS and could not be read — EACCES on a chmod'ed state
124
+ // file, EISDIR on a path something else claimed, EIO on a bad disk — and
125
+ // each of those discards a real back-off streak and a real elapsed total.
126
+ // Swallowing them with the same bare catch the absent case uses is a
127
+ // degraded read reported as a fresh run, which is the failure class this
128
+ // whole ticket exists to close.
129
+ if (e.code !== "ENOENT") {
130
+ console.error(`${name}: WARNING could not read ${path} (${e.message}) — restarting at the base interval`);
131
+ }
132
+ return fresh;
133
+ }
134
+ let parsed;
135
+ try {
136
+ parsed = JSON.parse(raw);
137
+ } catch (e) {
138
+ console.error(`${name}: WARNING ${path} is not JSON (${e.message}) — restarting at the base interval`);
139
+ return fresh;
140
+ }
141
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
142
+ console.error(`${name}: WARNING ${path} is not an object — restarting at the base interval`);
143
+ return fresh;
144
+ }
145
+ // Per-field validation, not all-or-nothing: a file carrying a good `quiet`
146
+ // and a junk `elapsed` keeps the streak instead of losing both to one key.
147
+ const num = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : 0);
148
+ // `rest` is strictly what lies OUTSIDE the schema, which is what makes the
149
+ // patch write below a patch rather than a laundering step. A raw copy of
150
+ // quiet/elapsed/digest in here would be written straight back by whichever
151
+ // script does not own the key, so a junk value would survive every write
152
+ // that sanitized it in memory — validation that only ever holds inside one
153
+ // process is not validation of the file.
154
+ // The MARK is validated as a unit rather than per sub-field, which is the
155
+ // opposite of the rule above and for the reason the rule above gives. The
156
+ // three scalars fail independently because each one alone is still useful;
157
+ // a mark is a TIME judged against the INTERVAL it was promised at, so half
158
+ // of one is not a degraded mark, it is a verdict computed against a number
159
+ // nobody wrote. Both fields must be positive integers or the mark is absent
160
+ // — never "stale", which is the wolf, and never "beating", which is the
161
+ // silence. `stopped` is the exception: a mark with a junk reason is still a
162
+ // mark — dropping the whole mark over one corrupt field would blind
163
+ // readers to `at`/`interval`, which ARE still trustworthy. A junk reason
164
+ // degrades to `""`, the same value an ordinary beat carries; assessBeat()
165
+ // only reads it as "no reason recorded" once the mark ALSO goes stale by
166
+ // age — until then it is judged on freshness alone, same as any other
167
+ // beat. A hand-edited or corrupted `stopped` is therefore not announced as
168
+ // a stop AT ALL while the mark is still fresh; it is announced, correctly,
169
+ // once the silence itself earns a verdict.
170
+ const mark = (v) => {
171
+ if (!v || typeof v !== "object" || Array.isArray(v)) return null;
172
+ const at = num(v.at), interval = num(v.interval);
173
+ if (at === 0 || interval === 0) return null;
174
+ return { at, interval, stopped: typeof v.stopped === "string" ? v.stopped : "" };
175
+ };
176
+ // `ticked` carries no interval — fleet-tick has no promise to fail, only an
177
+ // occurrence — so it is a mark of one field, valid or absent, same "never
178
+ // zero" rule as `mark` above for the same cry-wolf reason.
179
+ const tick = (v) => {
180
+ if (!v || typeof v !== "object" || Array.isArray(v)) return null;
181
+ const at = num(v.at);
182
+ return at === 0 ? null : { at };
183
+ };
184
+ const { quiet, elapsed, digest, beat, ticked, ...rest } = parsed;
185
+ return {
186
+ quiet: num(quiet),
187
+ elapsed: num(elapsed),
188
+ digest: typeof digest === "string" ? digest : "",
189
+ beat: mark(beat),
190
+ ticked: tick(ticked),
191
+ rest,
192
+ };
193
+ }
194
+
195
+ // Patch, never replace. Each script writes only the keys it owns, and rewriting
196
+ // the whole object from one script's view would drop the other's — a dropped
197
+ // `digest` reads as "the output changed" on the next tick, which un-folds a
198
+ // quiet night and silently undoes the cheap-per-wake half of the design.
199
+ //
200
+ // A failed write is reported and SURVIVED, never fatal, for the same reason a
201
+ // failed read is. But survived is not the same as ignored: it returns whether
202
+ // the write landed, because the two cases call for different behaviour from
203
+ // the caller and only the caller can act. An unpersisted `elapsed` means the
204
+ // next invocation re-reads the same total, holds again and reports the same
205
+ // remainder — an interval that can never complete — so fleet-heartbeat treats
206
+ // a failed write as a fire instead of counting progress that nothing is
207
+ // keeping.
208
+ export function writeState(path, name, prev, patch) {
209
+ // Built from the VALIDATED view plus the fields outside the schema, never
210
+ // from the raw parse: see `rest` in readState above.
211
+ const next = {
212
+ ...(prev.rest ?? {}),
213
+ quiet: prev.quiet, elapsed: prev.elapsed, digest: prev.digest,
214
+ // Carried like the other three, and omitted rather than written as
215
+ // `null` when there is none: fleet-tick patches `quiet`/`digest` on every
216
+ // tick and would otherwise erase the heartbeat's mark on the first tick
217
+ // after it was written — one script deleting another's key, which is the
218
+ // failure the ownership rule exists to prevent and which no reader could
219
+ // tell from a run that never beat.
220
+ ...(prev.beat ? { beat: prev.beat } : {}),
221
+ // Same reason, same shape: fleet-heartbeat patches `elapsed`/`beat` on
222
+ // every hold and would otherwise erase fleet-tick's `ticked` the first
223
+ // time a heartbeat lands after a busy stretch.
224
+ ...(prev.ticked ? { ticked: prev.ticked } : {}),
225
+ ...patch,
226
+ };
227
+ try {
228
+ mkdirSync(dirname(path), { recursive: true });
229
+ writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
230
+ return true;
231
+ } catch (e) {
232
+ console.error(`${name}: WARNING could not write ${path} (${e.message}) — back-off progress will not persist`);
233
+ return false;
234
+ }
235
+ }
236
+
237
+ // --------------------------------------------------------------------------
238
+ // READING THE MARK — #1597. The rule, and the wording, in one place.
239
+ //
240
+ // Two readers consume this key and neither of them writes it: fleet-tick at
241
+ // the start of a run (so a run that died overnight announces itself even when
242
+ // no cockpit survived it) and board.mjs on every cockpit tick (the better
243
+ // surface, the weaker guarantee — whether a backgrounded cockpit outlives the
244
+ // session that spawned it is unmeasured and harness-dependent, so the mark is
245
+ // the artifact and the cockpit is one renderer of it).
246
+ //
247
+ // Both live here for the reason the module header already gives about the
248
+ // path and the shape: what travels between scripts is the rule, never a copy
249
+ // of it. Two staleness thresholds would be two different answers to "is this
250
+ // run dead" from one file, and two wordings would let a rewrite of the
251
+ // cockpit's banner leave the tick's line saying something else.
252
+
253
+ // Staleness is judged against the interval the mark RECORDS, never against a
254
+ // constant. The interval is not a constant — back-off stretches it from
255
+ // --base toward --ceiling — so a fixed threshold either cries wolf on a quiet
256
+ // night at the ceiling or misses a death during a busy one at the base.
257
+ //
258
+ // The grace multiplier is the only constant, and it is a multiplier ON the
259
+ // recorded interval rather than a duration added to it, so it scales with the
260
+ // promise instead of drowning it. One whole extra interval of silence: a beat
261
+ // is served by SEVERAL holds (see fleet-heartbeat.mjs's heldThisCall), the
262
+ // controller's own turn sits between the last hold and the next invocation,
263
+ // and neither is bounded tightly enough to call a run dead the second one
264
+ // interval lapses. It is the same shape board.html already uses to call its
265
+ // own data stale (`interval * 1000 * 2`), kept deliberately: an operator
266
+ // reading two "stale" verdicts on one page should not have to learn two rules.
267
+ export const BEAT_GRACE = 2;
268
+
269
+ // fleet-heartbeat.mjs's own --ceiling default (1200s = 20 minutes), mirrored
270
+ // here rather than the other way round: this module is the one both scripts
271
+ // and both READERS already import, and a magic "1200" typed twice is exactly
272
+ // the drift the module header's "never a copy of it" rule exists to close.
273
+ // It doubles as the freshness window for `ticked` below: fleet-tick's own
274
+ // invocations carry no promised interval, so they are judged against the
275
+ // worst-case gap this design ever tolerates when only the heartbeat is
276
+ // beating, times the same grace multiplier as `beat`.
277
+ export const DEFAULT_CEILING_S = 1200;
278
+
279
+ // What the mark says, as a value. `now` is a parameter so every caller's
280
+ // verdict is deterministic and testable — the same reason compute-board.mjs
281
+ // takes one.
282
+ //
283
+ // none no mark. A fresh run, or one whose heartbeat never ran. NOT a
284
+ // stall: there is no beat to have stopped, and reporting one here
285
+ // would fire on every first tick and train the reader to ignore
286
+ // the line.
287
+ // beating seen within the interval it promised, plus grace — OR a recent
288
+ // `ticked` covers for it. `beat` is only refreshed when the queue
289
+ // drains (SKILL.md: "beat when there is nothing to do"), so a
290
+ // busy stretch that outlasts `beat`'s own grace window is not a dead
291
+ // run; fleet-tick's own edge-triggered invocations are the other
292
+ // liveness signal for exactly that case (#1597 follow-up).
293
+ // stopped a reason was recorded. Reported whatever the age, because a
294
+ // recorded stop IS the end of the run and waiting for it to go
295
+ // stale first would sit on the one report that knows its cause.
296
+ // stale overdue with no reason recorded AND no recent tick either. The
297
+ // abrupt death: a crashed harness, a closed terminal, an OOM
298
+ // kill. Readers say exactly that rather than naming a cause they
299
+ // cannot know.
300
+ export function assessBeat({ beat, ticked, now }) {
301
+ if (!beat) return { kind: "none" };
302
+ // Clamped at zero rather than left signed: a mark from the future is a
303
+ // clock that moved, not a beat that is minus-five-minutes overdue, and a
304
+ // negative age formatted into the line reads as a defect in this code.
305
+ const ageMs = Math.max(0, now - beat.at);
306
+ const intervalMs = beat.interval * 1000;
307
+ const seen = { at: beat.at, ageMs, intervalMs, overdueMs: Math.max(0, ageMs - intervalMs) };
308
+ if (beat.stopped) return { ...seen, kind: "stopped", reason: beat.stopped };
309
+ const beatOverdue = ageMs > intervalMs * BEAT_GRACE;
310
+ // Absent `ticked` — every caller before #1597's follow-up, and any state
311
+ // file fleet-tick has not yet written to — reads as infinitely old, which
312
+ // is `beat` alone deciding it exactly as before. A present one only ever
313
+ // shortens the window to "beating"; it can never manufacture a stale verdict
314
+ // `beat` alone would not have reached.
315
+ const tickedAgeMs = ticked ? Math.max(0, now - ticked.at) : Infinity;
316
+ const tickedFresh = tickedAgeMs <= DEFAULT_CEILING_S * 1000 * BEAT_GRACE;
317
+ return { ...seen, kind: beatOverdue && !tickedFresh ? "stale" : "beating", reason: null };
318
+ }
319
+
320
+ // Whether this verdict is something to report. Exported because both readers
321
+ // have work to do BEFORE they can render one — the tick runs a gh query for
322
+ // the claimed count, the cockpit counts its own cards — and neither should
323
+ // pay for that on a healthy run.
324
+ export function isStalled(verdict) {
325
+ return verdict.kind === "stopped" || verdict.kind === "stale";
326
+ }
327
+
328
+ // Whole minutes, floored, because the numbers here are tens of minutes to
329
+ // hours and a seconds-precise age in a stall line is false precision: the
330
+ // mark is written once per hold, so its resolution is minutes anyway. That
331
+ // holds for production (--base 300, --ceiling 1200 — SKILL.md's only
332
+ // documented values) but not for every value the CLI guard actually accepts:
333
+ // fleet-heartbeat.mjs's own guard refuses `--ceiling < --base` the same way
334
+ // this file refuses other invalid shapes, and mirroring that refusal onto
335
+ // sub-60s `--base`/`--ceiling` was the first fix tried for #1735 — until
336
+ // fleet-heartbeat.test.mjs turned out to lean on 2s/3s/8s/9s/64s intervals
337
+ // throughout, deliberately, to keep its real `Atomics.wait` holds fast. A
338
+ // CLI-level refusal would force that whole suite onto minute-plus real
339
+ // holds for no behavioural gain, so the fix lives here instead: a value
340
+ // under a minute is still a real value, not an invalid one, and flooring it
341
+ // to "0m" is what read as a division-by-zero defect, not the sub-minute
342
+ // input itself.
343
+ //
344
+ // #1735 only moved the floor for values UNDER 60s. A 60-119s value still
345
+ // fell on the whole-minutes branch, so a 90-119s interval floors to "1m"
346
+ // while its own overdue remainder (usually still under 60s) prints in
347
+ // seconds — the line's three numbers stop reconciling the moment any of
348
+ // them lands in that band: age=100s, interval=90s reads "1m ago ... 10s
349
+ // past the 1m interval", and 1m minus 1m is 0, not 10s. The bug was never
350
+ // the floor itself, it was flooring each of the three numbers to its OWN
351
+ // unit independently — three independent floors of one piece of exact
352
+ // arithmetic (overdueMs = ageMs - intervalMs, held exactly by assessBeat)
353
+ // do not have to agree with each other once any one of them crosses a unit
354
+ // boundary the others did not. Reporting the full `Xm Ys` breakdown, and
355
+ // dropping whichever half is zero, fixes that: the same seconds total
356
+ // feeds every one of the three numbers, so minutes-times-60-plus-seconds
357
+ // inverts back to the exact millisecond figure every time, which is what
358
+ // makes it impossible for the three to imply two different remainders for
359
+ // the one subtraction that ties them together. It also happens to leave
360
+ // every value that is an exact multiple of a minute — the production case
361
+ // above, and every value already pinned byte-for-byte — rendering exactly
362
+ // as it did before, because the seconds half is zero and gets dropped.
363
+ function mins(ms) {
364
+ const totalSeconds = Math.floor(ms / 1000);
365
+ const m = Math.floor(totalSeconds / 60);
366
+ const s = totalSeconds % 60;
367
+ if (m === 0) return `${s}s`;
368
+ if (s === 0) return `${m}m`;
369
+ return `${m}m${s}s`;
370
+ }
371
+
372
+ // The report. Returns null for anything isStalled() rejects, so a caller that
373
+ // skipped the predicate cannot print a stall for a healthy run by accident.
374
+ //
375
+ // What it names is the acceptance criterion itself: a bare "stale" tells the
376
+ // maintainer nothing they can act on, so the line carries when the beat was
377
+ // last seen, how overdue that is against the interval it PROMISED, whether a
378
+ // reason was recorded, and — the part that makes it actionable — what is
379
+ // stranded. A dead run leaves its tickets labelled in-progress, and the
380
+ // candidate scan excludes that label, so those tickets are invisible to the
381
+ // next run's scans and to the maintainer's both.
382
+ //
383
+ // `claimed` and `supply` are `null` for UNKNOWN, never 0. The two readers
384
+ // count them from different sources (a gh query on the claim label; the
385
+ // cockpit's own cards) and either source can fail, and "0 claimed" off a
386
+ // failed read is the same lie as "supply 0" off one — it says the night cost
387
+ // nothing when it may have stranded the whole pool.
388
+ export function stallReport(verdict, { claimed, supply }) {
389
+ if (!isStalled(verdict)) return null;
390
+ const n = (v) => (v == null ? "unknown" : String(v));
391
+ // Present tense for the deliberate stop and past for the abrupt one, because
392
+ // that is the actual difference: one run said why it was going, the other
393
+ // was cut off mid-beat and left nothing behind to ask.
394
+ const why = verdict.kind === "stopped"
395
+ ? `stopped deliberately — recorded reason: ${verdict.reason}`
396
+ : "the beat stopped without a recorded reason";
397
+ return `heartbeat STALLED: last beat ${new Date(verdict.at).toISOString()}`
398
+ + ` (${mins(verdict.ageMs)} ago, ${mins(verdict.overdueMs)} past the ${mins(verdict.intervalMs)} interval it promised)`
399
+ + ` — ${why}; ${n(claimed)} ticket(s) claimed and in flight, pool supply ${n(supply)}`;
400
+ }