@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,272 @@
1
+ #!/usr/bin/env node
2
+ // The heartbeat. #3's item 2, filed as #357: the ONE fleet-tick trigger that
3
+ // survives a fully drained queue.
4
+ //
5
+ // fleet-tick.mjs computes the deficit but only when something invokes it, and
6
+ // every other invocation is a wake: a member report, a label, a CI run ending.
7
+ // A drained fleet emits no wakes at all — no implementer completions, no merge
8
+ // activity — so nothing calls the tick and the stall is silent again, which is
9
+ // the state #3 was filed about. This script is the level-check that needs no
10
+ // event: it holds the controller's turn for an interval and then tells it to
11
+ // run the tick.
12
+ //
13
+ // WHY A HOLD AND NOT A WATCHER — the ruling, measured before it was made:
14
+ //
15
+ // A backgrounded watcher does not wake an idle agent. Measured twice in one
16
+ // run (run-team/SKILL.md, "A member runs its test suite in the foreground"):
17
+ // `fix-pr-1184` backgrounded its suite plus a Monitor and sat idle for
18
+ // roughly two hours; neither ever woke it. run-merge-bot.md's CI gate states
19
+ // the same rule as a rule — "whatever wakes you is external and may never
20
+ // come" — and cures it the same way this file does, by holding the wait
21
+ // inside one blocking command and re-issuing it.
22
+ //
23
+ // So the heartbeat is not a Monitor, not a cron entry and not a paragraph of
24
+ // prose. A cron entry that ran the reconcile would print its rows to nobody:
25
+ // the tick reads the run for itself (#1803), but only the controller can act
26
+ // on what it prints. An external scheduler can only WAKE the controller,
27
+ // which is the one thing the measurement above says it cannot be trusted to
28
+ // do.
29
+ //
30
+ // WHY IT TAKES NO CONTROLLER STATE — every flag below has a default. A monitor
31
+ // event is a wake-up, never a verdict (SKILL.md's Monitor rules), so this
32
+ // script never reads or reports fleet state: counts captured before a
33
+ // twenty-minute hold and printed after it are a stale verdict, and a stale
34
+ // verdict is how a reconcile prints an ACTION nobody can take. The controller
35
+ // runs fleet-tick itself at wake time, which reads the run as it stands then.
36
+ // It also makes a late hold harmless: if a member reports at minute two and
37
+ // the controller acts, the hold that fires afterwards is a free extra tick.
38
+ //
39
+ // The pure half is interval() and heldThisCall(); main() does the I/O.
40
+
41
+ // Back-off. The interval doubles while the fleet has nothing to act on, so a
42
+ // quiet night costs a few wakes instead of one every five minutes — and stops
43
+ // doubling at a ceiling, because the ceiling IS the worst-case latency for
44
+ // noticing work that arrives with no event to announce it.
45
+ //
46
+ // That case is real and is the reason the ceiling is not simply "long": supply
47
+ // grows from OUTSIDE the fleet. A maintainer triages a ticket, or a reviewer
48
+ // files a correction ticket carrying `ready-for-agent`, and neither emits
49
+ // anything the controller can observe. An unbounded back-off would therefore
50
+ // reintroduce #3's own defect in a form that reads like a feature — asleep at a
51
+ // level check, just slower. Twenty minutes bounds it while still cutting a
52
+ // quiet eight hours from ~96 wakes to ~26.
53
+ export function interval({ quiet, base, ceiling, multiplier }) {
54
+ // Math.min, never a conditional chain: `base * multiplier ** quiet` overflows
55
+ // to Infinity after ~1000 quiet ticks and every comparison against Infinity
56
+ // still resolves correctly through min, where a hand-rolled ladder would have
57
+ // to name that case to survive it.
58
+ return Math.min(base * multiplier ** quiet, ceiling);
59
+ }
60
+
61
+ // How long THIS invocation may block, which is not the same as the interval.
62
+ //
63
+ // Nothing lets one command block for twenty minutes. Measured: omp
64
+ // auto-backgrounds any foreground command at 60s (`bash.autoBackground`), and
65
+ // its command deadline defaults to 300s — the fact run-merge-bot.md's CI wait
66
+ // rule already states.
67
+ //
68
+ // So a long interval is served by SEVERAL holds, and the elapsed total is
69
+ // persisted rather than counted in prose. That is the same remedy the CI gate
70
+ // reached for, made mechanical: the script says how much remains, so the
71
+ // controller re-issues without tracking arithmetic across turns.
72
+ export function heldThisCall({ elapsed, target, hold }) {
73
+ return Math.min(hold, Math.max(0, target - elapsed));
74
+ }
75
+
76
+ // --------------------------------------------------------------------------
77
+ // I/O. Everything below runs only as a CLI — importing this file must never
78
+ // parse argv or touch the filesystem, or the pure half stops being unit-testable.
79
+
80
+ import { pathToFileURL } from "node:url";
81
+ import { parseArgs } from "node:util";
82
+ import { makeDie, isDigits } from "./arg.mjs";
83
+ import { statePath, readState, writeState, DEFAULT_CEILING_S } from "./fleet-state.mjs";
84
+
85
+ const NAME = "fleet-heartbeat";
86
+ const die = makeDie(NAME);
87
+
88
+ // Every flag defaults — see the header. The defaults are declared here rather
89
+ // than threaded through int() so they pass through the same guard a
90
+ // caller-supplied value does; a hand-passed default goes round it.
91
+ const OPTIONS = {
92
+ base: { type: "string", default: "300" },
93
+ // Single source of truth in fleet-state.mjs — assessBeat's own fallback
94
+ // freshness window for a busy run's `ticked` mark is this same number
95
+ // (#1597 follow-up), and a duplicated "1200" here is the drift the module
96
+ // header's "never a copy of it" rule exists to close.
97
+ ceiling: { type: "string", default: String(DEFAULT_CEILING_S) },
98
+ multiplier: { type: "string", default: "2" },
99
+ // Per-invocation blocking budget, under omp's defaults. 240s leaves
100
+ // headroom below omp's 300s deadline, the same ceiling run-merge-bot.md's
101
+ // CI wait rule measures against a 5-6 minute CI cycle. Raise
102
+ // it only together with the tool call's own timeout.
103
+ hold: { type: "string", default: "240" },
104
+ // The deliberate stop, #1597. No default and no boolean spelling: the flag
105
+ // IS the reason, and a `--stop` that recorded an empty string would be the
106
+ // abrupt-death case wearing a deliberate stop's clothes — a reader would
107
+ // report a recorded reason and then print nothing for it.
108
+ //
109
+ // It lives on THIS script rather than on fleet-tick because the mark is one
110
+ // key with one writer (fleet-state.mjs's ownership rule), and the reason is
111
+ // part of the mark: a stop written from the tick side would be two scripts
112
+ // writing `beat` and would need the lock that file exists to avoid.
113
+ stop: { type: "string" },
114
+ state: { type: "string" },
115
+ };
116
+
117
+ // State path, read and write all come from fleet-state.mjs, which owns the key
118
+ // ownership rule this script depends on: it writes `elapsed` and `beat` and
119
+ // nothing else, so fleet-tick's `quiet` and `digest` survive every hold.
120
+ // main() re-reads the file after its hold to keep that true across the hold
121
+ // itself, and treats a write that did not land as a fire rather than as
122
+ // progress.
123
+
124
+ // A blocking sleep, not a poll loop. Atomics.wait on a SharedArrayBuffer parks
125
+ // the thread; `while (Date.now() < end) {}` would burn a core for the whole
126
+ // hold, and setTimeout would need the event loop to stay alive and would let
127
+ // anything else queued run first.
128
+ function block(seconds) {
129
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, seconds * 1000);
130
+ }
131
+
132
+ function args() {
133
+ let values;
134
+ try {
135
+ ({ values } = parseArgs({ options: OPTIONS }));
136
+ } catch (e) {
137
+ // Unconditional catch, as in fleet-tick: parseArgs throws on the FIRST
138
+ // offending argument, so keying off an error code disables the guard for
139
+ // every argv where something else comes earlier.
140
+ die(`${e.message} — accepted: ${Object.keys(OPTIONS).map((f) => `--${f}`).join(", ")}`);
141
+ }
142
+ const int = (name, min) => {
143
+ const raw = String(values[name]).trim();
144
+ // Digits, not Number(): `Number("")` is 0, so `--base ""` — the shape an
145
+ // unset shell variable produces — would read as a real zero and turn the
146
+ // hold into a no-op that looks like a working heartbeat.
147
+ if (!isDigits(raw)) die(`--${name} must be a non-negative integer, got '${values[name]}'`);
148
+ const n = Number(raw);
149
+ if (n < min) die(`--${name} must be at least ${min}, got ${n}`);
150
+ return n;
151
+ };
152
+ const base = int("base", 1);
153
+ const ceiling = int("ceiling", 1);
154
+ const multiplier = int("multiplier", 1);
155
+ const hold = int("hold", 1);
156
+ // A ceiling under the base is not a slow heartbeat, it is a back-off that
157
+ // runs backwards — min() would clamp every interval to the ceiling and the
158
+ // base would never be honoured. Refuse rather than silently reinterpret.
159
+ if (ceiling < base) die(`--ceiling (${ceiling}) is below --base (${base}) — the back-off would run backwards`);
160
+ // `--stop` is read BELOW the int guards, so a malformed `--base` still
161
+ // refuses on the stop path: a stop is the last thing this script does for a
162
+ // run and it is not an excuse to stop validating.
163
+ //
164
+ // `values.stop` is `undefined` when the flag is absent and `""` when it was
165
+ // given empty — the shape an unset shell variable produces — and only the
166
+ // first is "not stopping". Same distinction every other flag in this file
167
+ // draws, for the same reason.
168
+ if (values.stop !== undefined && values.stop.trim() === "") {
169
+ die("--stop must carry the reason the run is stopping, e.g. --stop 'budget exhausted'");
170
+ }
171
+ return { base, ceiling, multiplier, hold, stop: values.stop?.trim(), state: values.state || statePath(NAME) };
172
+ }
173
+
174
+ // The mark, #1597: when this beat was seen and the interval that was in effect
175
+ // when it was. Built here rather than inline at each write so the two writes
176
+ // below cannot disagree about the shape of a key only this script owns.
177
+ //
178
+ // The interval travels WITH the time because a reader comparing an age
179
+ // against a fixed threshold either cries wolf on a quiet night at the ceiling
180
+ // or misses a death during a busy one at the base. It is the target interval
181
+ // and not the hold: the hold is this harness's blocking budget, an
182
+ // implementation detail of how one interval gets served, while the interval
183
+ // is the beat the run actually promised.
184
+ function mark(target, stopped) {
185
+ return { at: Date.now(), interval: target, stopped };
186
+ }
187
+
188
+ function main() {
189
+ const { base, ceiling, multiplier, hold, stop, state: path } = args();
190
+ const state = readState(path, NAME);
191
+ const target = interval({ quiet: state.quiet, base, ceiling, multiplier });
192
+
193
+ if (stop !== undefined) {
194
+ // No hold, and `elapsed` untouched: this invocation is not a beat, it is
195
+ // the run saying why there will not be another one. Leaving the partial
196
+ // interval where it is costs nothing — the next run reads a stopped mark
197
+ // and knows the streak behind it is a dead run's.
198
+ const persisted = writeState(path, NAME, state, { beat: mark(target, stop) });
199
+ // Announced on stdout as well as through writeState's own stderr warning,
200
+ // and still exit 0. An unrecorded stop is a real degradation — the next
201
+ // run will report a beat that stopped without a reason, which is the
202
+ // abrupt-death wording for a death that named itself — but it is not
203
+ // grounds to fail the command: the controller is stopping either way and
204
+ // a non-zero exit here only adds noise to a run that is already ending.
205
+ console.log(persisted
206
+ ? `heartbeat: stop recorded (${stop}) — the next run's start and the cockpit will report it`
207
+ : `heartbeat: WARNING stop NOT recorded (${stop}) — the next reader will see a beat that stopped with no reason`);
208
+ return;
209
+ }
210
+
211
+ const held = heldThisCall({ elapsed: state.elapsed, target, hold });
212
+
213
+ block(held);
214
+ // Re-read AFTER the hold, and patch THAT rather than the pre-hold snapshot.
215
+ // fleet-tick can run while this call is blocked — up to --hold seconds, 240
216
+ // by default — and it owns both keys this script must not touch. Writing the
217
+ // snapshot back reverts them: a busy stretch that reset `quiet` to 0 would find
218
+ // the long interval re-armed the moment the hold ended, and a reverted
219
+ // `digest` reads as "the output changed" on the next tick, un-folding the
220
+ // quiet night the digest exists to fold. `elapsed` is still one of the keys
221
+ // this script writes; it is now read fresh rather than remembered across a
222
+ // hold long enough for the file to have moved underneath it.
223
+ const now = readState(path, NAME);
224
+ const elapsed = now.elapsed + held;
225
+ const reached = elapsed >= target;
226
+ // Reset on fire, so the next interval starts from zero rather than from a
227
+ // total that has already elapsed. Only `elapsed` and `beat` are written —
228
+ // fleet-tick owns `quiet` and `digest`, and fleet-state.mjs's patch write
229
+ // preserves them.
230
+ //
231
+ // The mark rides the SAME write as `elapsed`, deliberately, rather than
232
+ // taking one of its own. One write per invocation means a mark can never
233
+ // land while the progress it was taken beside did not, and the two can
234
+ // never disagree about which invocation they came from. It also keeps the
235
+ // failure story single: the warning below covers both keys at once.
236
+ //
237
+ // `stopped: ""` on every ordinary beat, never carried forward: a run that
238
+ // recorded a stop and then kept beating is a run that did not stop, and a
239
+ // stale reason surviving into a live beat would have the next reader
240
+ // announcing a death that already un-happened.
241
+ const persisted = writeState(path, NAME, now, { elapsed: reached ? 0 : elapsed, beat: mark(target, "") });
242
+ // A failed write is itself a fire. With nothing persisting the remainder,
243
+ // every invocation reads the same elapsed total, holds the same seconds and
244
+ // prints the same remainder: the interval can never complete, so fleet-tick
245
+ // is never run at all — #357's own defect, reached through a line that reads
246
+ // like a working heartbeat. Beating too often is the harmless direction;
247
+ // never beating is the one this script exists to prevent.
248
+ //
249
+ // The mark fails the same way and on purpose: writeState has already said
250
+ // so on stderr, this process keeps beating, and a reader that never sees a
251
+ // mark reports a stall it cannot explain — loud and wrong in the safe
252
+ // direction — rather than this script dying to protect its own telemetry.
253
+ // A liveness mark that killed the beat it measures would be #357's defect
254
+ // wearing a new hat.
255
+ const done = reached || !persisted;
256
+
257
+ // One line either way, and never zero lines. Silence is the failure mode this
258
+ // whole ticket is about: a heartbeat that printed nothing would be
259
+ // indistinguishable from a heartbeat that died, which is the same
260
+ // "indistinguishable from a working one" the member-idle measurement names.
261
+ // The partial line says what to do next in the imperative, because the one
262
+ // thing that must not happen here is the controller ending its turn.
263
+ //
264
+ // `quiet=` is the pre-hold streak, the one the interval was DERIVED from: a
265
+ // fresh streak printed beside a target computed from the old one would be two
266
+ // numbers that do not explain each other.
267
+ console.log(done
268
+ ? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-tick`
269
+ : `heartbeat: held ${held}s, ${target - elapsed}s of ${target}s remain (quiet=${state.quiet}) → re-issue this command now, do not end your turn`);
270
+ }
271
+
272
+ if (import.meta.url === pathToFileURL(process.argv[1] || "").href) main();