@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,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
|
+
}
|