@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.
- package/.claude-plugin/plugin.json +9 -0
- package/LICENSE +202 -0
- package/NOTICE +18 -0
- package/agents/fleet-finisher.agent.md +7 -0
- package/agents/fleet-implementer-alt.agent.md +210 -0
- package/agents/fleet-implementer.agent.md +210 -0
- package/agents/fleet-merge-bot.agent.md +7 -0
- package/agents/fleet-review-comments.agent.md +40 -0
- package/agents/fleet-review-correctness.agent.md +43 -0
- package/agents/fleet-review-runner.agent.md +73 -0
- package/agents/fleet-review-silent-failure.agent.md +49 -0
- package/agents/fleet-review-simplify.agent.md +46 -0
- package/agents/fleet-review-snapshot.agent.md +24 -0
- package/agents/fleet-review-tests.agent.md +46 -0
- package/agents/fleet-review-types.agent.md +41 -0
- package/agents/fleet-review-verifier.agent.md +29 -0
- package/commands/review-and-fix.md +98 -0
- package/commands/run-merge-bot.md +357 -0
- package/commands/run-team-help.md +17 -0
- package/package.json +23 -0
- package/scripts/agent-test-dir-prose.test.mjs +59 -0
- package/scripts/agent-test.test.mjs +1636 -0
- package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
- package/scripts/ambient-git-vars-prose.test.mjs +192 -0
- package/scripts/ancestry-check-position-prose.test.mjs +175 -0
- package/scripts/apply-ruleset.test.mjs +420 -0
- package/scripts/arg-header-probes-prose.test.mjs +393 -0
- package/scripts/arg.mjs +600 -0
- package/scripts/arg.test.mjs +1354 -0
- package/scripts/board-cli.test.mjs +694 -0
- package/scripts/board-identity.test.mjs +429 -0
- package/scripts/board-liveness-banner.test.mjs +119 -0
- package/scripts/board-prev-shape.test.mjs +229 -0
- package/scripts/board-tryparse-null.test.mjs +119 -0
- package/scripts/board.html +471 -0
- package/scripts/board.mjs +2037 -0
- package/scripts/board.test.mjs +3086 -0
- package/scripts/brief-after-cut-prose.test.mjs +53 -0
- package/scripts/candidates-exit3-prose.test.mjs +302 -0
- package/scripts/candidates.mjs +674 -0
- package/scripts/candidates.test.mjs +2101 -0
- package/scripts/caveat-unification-prose.test.mjs +98 -0
- package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
- package/scripts/ci-completes-premise-prose.test.mjs +257 -0
- package/scripts/ci-state-prose.test.mjs +113 -0
- package/scripts/ci-state.mjs +761 -0
- package/scripts/ci-state.test.mjs +1640 -0
- package/scripts/ci-vacuous-green.test.mjs +368 -0
- package/scripts/citation-sweep-prose.test.mjs +1572 -0
- package/scripts/claim-lifecycle.test.mjs +185 -0
- package/scripts/claim-ticket.sh +417 -0
- package/scripts/claim-ticket.test.mjs +1121 -0
- package/scripts/closing-keyword-prose.test.mjs +193 -0
- package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
- package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
- package/scripts/compute-board.mjs +579 -0
- package/scripts/compute-board.test.mjs +1060 -0
- package/scripts/compute-spend.mjs +329 -0
- package/scripts/compute-spend.test.mjs +451 -0
- package/scripts/cross-repo-citation-prose.test.mjs +156 -0
- package/scripts/cwd-isolation-pins.mjs +83 -0
- package/scripts/dedupe-guard-prose.test.mjs +243 -0
- package/scripts/derive-testcmd.sh +239 -0
- package/scripts/derive-testcmd.test.mjs +380 -0
- package/scripts/diff-stats.mjs +231 -0
- package/scripts/diff-stats.test.mjs +408 -0
- package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
- package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
- package/scripts/drop-merged-label.sh +173 -0
- package/scripts/drop-merged-label.test.mjs +480 -0
- package/scripts/expected-jobs-prose.test.mjs +80 -0
- package/scripts/filing-bar-seat-prose.test.mjs +242 -0
- package/scripts/filing-claim-bar-prose.test.mjs +166 -0
- package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
- package/scripts/finisher-halt-prose.test.mjs +106 -0
- package/scripts/finisher-name-prose.test.mjs +134 -0
- package/scripts/finisher-own-tree-prose.test.mjs +285 -0
- package/scripts/finisher-pin-race-prose.test.mjs +339 -0
- package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
- package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
- package/scripts/fleet-bootstrap +155 -0
- package/scripts/fleet-heartbeat.mjs +272 -0
- package/scripts/fleet-heartbeat.test.mjs +450 -0
- package/scripts/fleet-provenance +207 -0
- package/scripts/fleet-provenance.test.mjs +64 -0
- package/scripts/fleet-run +148 -0
- package/scripts/fleet-run.test.mjs +90 -0
- package/scripts/fleet-state.mjs +400 -0
- package/scripts/fleet-state.test.mjs +373 -0
- package/scripts/fleet-tick-prose.test.mjs +299 -0
- package/scripts/fleet-tick.mjs +832 -0
- package/scripts/fleet-tick.test.mjs +1332 -0
- package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
- package/scripts/frontmatter-allowlist.json +64 -0
- package/scripts/frontmatter-check.mjs +256 -0
- package/scripts/frontmatter-check.test.mjs +436 -0
- package/scripts/git-env.mjs +124 -0
- package/scripts/git-env.test.mjs +149 -0
- package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
- package/scripts/gone-walk.test.mjs +213 -0
- package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
- package/scripts/head-moved-after-label-prose.test.mjs +233 -0
- package/scripts/immutable-body-claim-prose.test.mjs +413 -0
- package/scripts/implementer-model-tier.test.mjs +643 -0
- package/scripts/inflight-citation-prose.test.mjs +144 -0
- package/scripts/inflight-exit2-prose.test.mjs +81 -0
- package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
- package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
- package/scripts/inflight.sh +1106 -0
- package/scripts/inflight.test.mjs +2984 -0
- package/scripts/injection-control-prose.test.mjs +404 -0
- package/scripts/install-root-audit.test.mjs +464 -0
- package/scripts/instrument-check-prose.test.mjs +235 -0
- package/scripts/instruments.sh +394 -0
- package/scripts/instruments.test.mjs +787 -0
- package/scripts/issue-tracker-prose.test.mjs +71 -0
- package/scripts/json.sh +248 -0
- package/scripts/json.test.mjs +364 -0
- package/scripts/ledger-dispatch.test.mjs +516 -0
- package/scripts/ledger-grammar.mjs +85 -0
- package/scripts/ledger-grammar.test.mjs +142 -0
- package/scripts/ledger-read-require-file.test.mjs +197 -0
- package/scripts/ledger.mjs +1753 -0
- package/scripts/ledger.test.mjs +3554 -0
- package/scripts/line-distance-prose.test.mjs +245 -0
- package/scripts/liveness-rationale-prose.test.mjs +83 -0
- package/scripts/locale-pin-prose.test.mjs +189 -0
- package/scripts/member-outcome-prose.test.mjs +167 -0
- package/scripts/member-outcomes-header.test.mjs +148 -0
- package/scripts/member-outcomes-prose.test.mjs +63 -0
- package/scripts/member-outcomes.mjs +231 -0
- package/scripts/member-outcomes.test.mjs +507 -0
- package/scripts/member-prompt-prose.test.mjs +161 -0
- package/scripts/member-record.mjs +605 -0
- package/scripts/member-record.test.mjs +516 -0
- package/scripts/member-write-guard.mjs +279 -0
- package/scripts/member-write-guard.test.mjs +211 -0
- package/scripts/merge-commit-probe-prose.test.mjs +122 -0
- package/scripts/merge-gate.mjs +262 -0
- package/scripts/merge-gate.test.mjs +613 -0
- package/scripts/muted-git-guard-sweep.test.mjs +493 -0
- package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
- package/scripts/net-watchdog-prose.test.mjs +79 -0
- package/scripts/net.sh +409 -0
- package/scripts/net.test.mjs +211 -0
- package/scripts/no-ci-gate-prose.test.mjs +108 -0
- package/scripts/no-undo-audit.sh +1134 -0
- package/scripts/no-undo-audit.test.mjs +3965 -0
- package/scripts/no-wave.test.mjs +138 -0
- package/scripts/node-floor-sweep.test.mjs +611 -0
- package/scripts/pointer-target-prose.test.mjs +186 -0
- package/scripts/pr-overlap.mjs +417 -0
- package/scripts/pr-overlap.test.mjs +695 -0
- package/scripts/printf-die-sweep.test.mjs +384 -0
- package/scripts/prompt-renderer.mjs +39 -0
- package/scripts/prompt-renderer.test.mjs +68 -0
- package/scripts/prose-pin.mjs +808 -0
- package/scripts/prose-pin.test.mjs +1034 -0
- package/scripts/prove-merge.sh +228 -0
- package/scripts/prove-merge.test.mjs +995 -0
- package/scripts/pull-table-relabel-prose.test.mjs +60 -0
- package/scripts/quiet-payload-prose.test.mjs +222 -0
- package/scripts/reap.sh +1768 -0
- package/scripts/reap.test.mjs +4395 -0
- package/scripts/reaping-prose.test.mjs +159 -0
- package/scripts/refuter-scratch-prose.test.mjs +135 -0
- package/scripts/release-label-required-prose.test.mjs +71 -0
- package/scripts/release-label-split-prose.test.mjs +169 -0
- package/scripts/release-ticket.sh +1716 -0
- package/scripts/release-ticket.test.mjs +5106 -0
- package/scripts/renovate-release-contract.test.mjs +379 -0
- package/scripts/repo-root.mjs +544 -0
- package/scripts/repo-root.test.mjs +873 -0
- package/scripts/reporter-output-rule-prose.test.mjs +208 -0
- package/scripts/review-agent-report-only.test.mjs +49 -0
- package/scripts/review-core-cwd-isolation.test.mjs +374 -0
- package/scripts/review-core-reads.test.mjs +478 -0
- package/scripts/review-core-refuter-scratch.test.mjs +148 -0
- package/scripts/review-core-snapshot-path.test.mjs +777 -0
- package/scripts/review-core-specialist-scratch.test.mjs +189 -0
- package/scripts/review-core-testcmd.test.mjs +288 -0
- package/scripts/review-core-unrun.test.mjs +530 -0
- package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
- package/scripts/review-core.mjs +1028 -0
- package/scripts/review-eval-resolver-path.test.mjs +55 -0
- package/scripts/review-eval.mjs +197 -0
- package/scripts/review-host-fixture.mjs +73 -0
- package/scripts/review-in-run-retry.test.mjs +187 -0
- package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
- package/scripts/review-path-default.test.mjs +796 -0
- package/scripts/review-runner-spawns.test.mjs +93 -0
- package/scripts/review-runner.test.mjs +155 -0
- package/scripts/review-tier-audit.test.mjs +140 -0
- package/scripts/run-artifact-pr-prose.test.mjs +341 -0
- package/scripts/run-merge-bot-prose.test.mjs +1391 -0
- package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
- package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
- package/scripts/section-between-guard-prose.test.mjs +378 -0
- package/scripts/select-dimensions.test.mjs +674 -0
- package/scripts/shared-refusal.test.mjs +388 -0
- package/scripts/shell-traps-prose.test.mjs +507 -0
- package/scripts/shortlist.mjs +355 -0
- package/scripts/shortlist.test.mjs +366 -0
- package/scripts/slow-transport.mjs +72 -0
- package/scripts/snapshot-repo.test.mjs +772 -0
- package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
- package/scripts/spend-view.test.mjs +312 -0
- package/scripts/staleness-qualifier-prose.test.mjs +251 -0
- package/scripts/staleness-verdict-prose.test.mjs +142 -0
- package/scripts/staleness.mjs +414 -0
- package/scripts/staleness.test.mjs +893 -0
- package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
- package/scripts/stash-prohibition-prose.test.mjs +313 -0
- package/scripts/strip-comments.mjs +44 -0
- package/scripts/tier-check.mjs +468 -0
- package/scripts/tier-check.test.mjs +726 -0
- package/scripts/tier-guard-gate-prose.test.mjs +216 -0
- package/scripts/tier-outcomes-header.test.mjs +586 -0
- package/scripts/tier-outcomes.mjs +441 -0
- package/scripts/tier-outcomes.test.mjs +342 -0
- package/scripts/tier-roles.mjs +250 -0
- package/scripts/tier-roles.test.mjs +316 -0
- package/scripts/tracker-block-copy-prose.test.mjs +288 -0
- package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
- package/scripts/unattended-git-sweep.test.mjs +142 -0
- package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
- package/scripts/verify-sha.sh +117 -0
- package/scripts/verify-sha.test.mjs +693 -0
- package/scripts/watcher-degraded-block.test.mjs +372 -0
- package/scripts/watcher-key-prose.test.mjs +106 -0
- package/scripts/within-run-pair-prose.test.mjs +208 -0
- package/scripts/worktree-audit.sh +482 -0
- package/scripts/worktree-audit.test.mjs +1407 -0
- package/scripts/worktree-head-prose.test.mjs +276 -0
- package/scripts/worktree-listing-sweep.test.mjs +217 -0
- package/scripts/worktree-model-prose.test.mjs +216 -0
- package/scripts/worktree.sh +470 -0
- package/skills/next-ticket/SKILL.md +138 -0
- package/skills/run-team/SKILL.md +3603 -0
- package/skills/run-team/references/ci-and-staleness.md +75 -0
- package/skills/run-team/references/correction-tickets.md +37 -0
- package/skills/run-team/references/isolation.md +23 -0
- package/skills/run-team/references/member-lifecycle.md +73 -0
- package/skills/run-team/references/reaping.md +73 -0
- 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();
|