@feigi/fleet-ctl 3.30.33 → 3.30.35
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/package.json +1 -1
- package/scripts/fleet-state.mjs +63 -22
- package/scripts/ledger.mjs +75 -37
- package/scripts/proc.mjs +161 -0
- package/skills/run-team/SKILL.md +33 -12
package/package.json
CHANGED
package/scripts/fleet-state.mjs
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
|
-
// The heartbeat's shared state file, owned jointly by fleet-tick.mjs
|
|
2
|
-
// fleet-heartbeat.mjs — so the path and the file's shape
|
|
3
|
-
// in
|
|
4
|
-
// what travels between scripts is the rule, never a copy of
|
|
1
|
+
// The heartbeat's shared state file, owned jointly by fleet-tick.mjs,
|
|
2
|
+
// fleet-heartbeat.mjs and ledger.mjs rotate — so the path and the file's shape
|
|
3
|
+
// live here rather than in spellings that drift. Same rule arg.mjs states for
|
|
4
|
+
// the digits guard: what travels between scripts is the rule, never a copy of
|
|
5
|
+
// it.
|
|
5
6
|
//
|
|
6
|
-
// KEY OWNERSHIP, which is the whole reason
|
|
7
|
+
// KEY OWNERSHIP, which is the whole reason several scripts can share one file
|
|
7
8
|
// without a lock:
|
|
8
9
|
//
|
|
9
10
|
// quiet fleet-tick only. Consecutive ticks that asked the controller for
|
|
@@ -28,9 +29,18 @@
|
|
|
28
29
|
// keeps firing on every completion, and without this key that
|
|
29
30
|
// healthy busy run reads as a dead one the moment the OLD beat
|
|
30
31
|
// ages past the interval it recorded before the stretch started.
|
|
32
|
+
// controller ledger.mjs rotate only. {pid, lstart, prior}: the omp process
|
|
33
|
+
// that owns this run, its start time, and the verdict rotate
|
|
34
|
+
// judged on the record it replaced (dead, ancestor or none).
|
|
35
|
+
// Removed, not left stale, by a rotate that finds no omp ancestor.
|
|
31
36
|
//
|
|
32
|
-
// One writer per key. A key
|
|
33
|
-
// correct, and
|
|
37
|
+
// One writer per key. A key two scripts wrote would need locking to be
|
|
38
|
+
// correct, and none of them is in a position to hold one. That holds per key,
|
|
39
|
+
// not per write: a writer carries every key it does not own from the view it
|
|
40
|
+
// read, so a read that lands before another script's write and a write that
|
|
41
|
+
// lands after it put the older value back. The windows are the gap between a
|
|
42
|
+
// script's own read and its own write, and the next write of that key
|
|
43
|
+
// corrects it, but until then a stale `controller` can be judged by a rotate.
|
|
34
44
|
|
|
35
45
|
import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
36
46
|
import { dirname, join } from "node:path";
|
|
@@ -69,6 +79,12 @@ export function statePath(name) {
|
|
|
69
79
|
}
|
|
70
80
|
}
|
|
71
81
|
|
|
82
|
+
// A plain JSON object: not null, not an array, not a scalar.
|
|
83
|
+
const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
84
|
+
|
|
85
|
+
// A recorded `prior` is one of these; anything else degrades to "none".
|
|
86
|
+
const PRIORS = ["dead", "ancestor", "none"];
|
|
87
|
+
|
|
72
88
|
// An unreadable or corrupt state file is NOT fatal, and the direction of the
|
|
73
89
|
// failure is the argument: a missing streak reads as quiet=0, which is the BASE
|
|
74
90
|
// interval — more frequent level checks, never fewer. Dying instead would stop
|
|
@@ -77,14 +93,20 @@ export function statePath(name) {
|
|
|
77
93
|
// Absent is the ONLY silent case, because it is the only one that is not a
|
|
78
94
|
// fault: a fresh run legitimately has no file yet. An unreadable file and a
|
|
79
95
|
// corrupt one are both announced — each discards real state, and silence about
|
|
80
|
-
// a degraded read is the failure class this whole ticket exists to close.
|
|
96
|
+
// a degraded read is the failure class this whole ticket exists to close. Both
|
|
97
|
+
// come back flagged `degraded`, for the one caller that must not read them as
|
|
98
|
+
// a file with nothing in it.
|
|
81
99
|
export function readState(path, name) {
|
|
82
100
|
// `beat: null` is the absent MARK, and it is not the same value as a mark
|
|
83
101
|
// whose fields are zero: nothing has been seen beating, so there is nothing
|
|
84
102
|
// to judge and nothing to report. A zeroed mark would date the beat to the
|
|
85
103
|
// epoch and read as decades overdue on a run that has simply not started
|
|
86
104
|
// one — the cry-wolf direction this key must never fail in.
|
|
87
|
-
const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, rest: {} };
|
|
105
|
+
const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, controller: null, rest: {} };
|
|
106
|
+
// The same state, flagged: the file EXISTS and could not be used. A caller
|
|
107
|
+
// that acts on the absence of a record — ledger.mjs rotate — must tell this
|
|
108
|
+
// from `fresh`, which is a run that has simply not written one yet.
|
|
109
|
+
const degraded = { ...fresh, degraded: true };
|
|
88
110
|
let raw;
|
|
89
111
|
try {
|
|
90
112
|
raw = readFileSync(path, "utf8");
|
|
@@ -99,6 +121,7 @@ export function readState(path, name) {
|
|
|
99
121
|
// whole ticket exists to close.
|
|
100
122
|
if (e.code !== "ENOENT") {
|
|
101
123
|
console.error(`${name}: WARNING could not read ${path} (${e.message}) — restarting at the base interval`);
|
|
124
|
+
return degraded;
|
|
102
125
|
}
|
|
103
126
|
return fresh;
|
|
104
127
|
}
|
|
@@ -107,11 +130,11 @@ export function readState(path, name) {
|
|
|
107
130
|
parsed = JSON.parse(raw);
|
|
108
131
|
} catch (e) {
|
|
109
132
|
console.error(`${name}: WARNING ${path} is not JSON (${e.message}) — restarting at the base interval`);
|
|
110
|
-
return
|
|
133
|
+
return degraded;
|
|
111
134
|
}
|
|
112
|
-
if (!
|
|
135
|
+
if (!isRecord(parsed)) {
|
|
113
136
|
console.error(`${name}: WARNING ${path} is not an object — restarting at the base interval`);
|
|
114
|
-
return
|
|
137
|
+
return degraded;
|
|
115
138
|
}
|
|
116
139
|
// Per-field validation, not all-or-nothing: a file carrying a good `quiet`
|
|
117
140
|
// and a junk `elapsed` keeps the streak instead of losing both to one key.
|
|
@@ -139,7 +162,7 @@ export function readState(path, name) {
|
|
|
139
162
|
// a stop AT ALL while the mark is still fresh; it is announced, correctly,
|
|
140
163
|
// once the silence itself earns a verdict.
|
|
141
164
|
const mark = (v) => {
|
|
142
|
-
if (!
|
|
165
|
+
if (!isRecord(v)) return null;
|
|
143
166
|
const at = num(v.at), interval = num(v.interval);
|
|
144
167
|
if (at === 0 || interval === 0) return null;
|
|
145
168
|
return { at, interval, stopped: typeof v.stopped === "string" ? v.stopped : "" };
|
|
@@ -148,17 +171,30 @@ export function readState(path, name) {
|
|
|
148
171
|
// occurrence — so it is a mark of one field, valid or absent, same "never
|
|
149
172
|
// zero" rule as `mark` above for the same cry-wolf reason.
|
|
150
173
|
const tick = (v) => {
|
|
151
|
-
if (!
|
|
174
|
+
if (!isRecord(v)) return null;
|
|
152
175
|
const at = num(v.at);
|
|
153
176
|
return at === 0 ? null : { at };
|
|
154
177
|
};
|
|
155
|
-
|
|
178
|
+
// `controller` is validated as a unit for the mark's reason: a pid without
|
|
179
|
+
// the start time it was recorded with cannot be told from a reused pid. A
|
|
180
|
+
// pid outside the range a process id can take is no record either, since
|
|
181
|
+
// no process could ever answer for it. `prior` degrades like `stopped`
|
|
182
|
+
// does: a junk verdict proves nothing, so it reads as "none", and the
|
|
183
|
+
// record around it still names a controller to judge.
|
|
184
|
+
const ctl = (v) => {
|
|
185
|
+
if (!isRecord(v)) return null;
|
|
186
|
+
if (!Number.isInteger(v.pid) || v.pid < 1 || v.pid > 0x7fffffff) return null;
|
|
187
|
+
if (typeof v.lstart !== "string" || v.lstart === "") return null;
|
|
188
|
+
return { pid: v.pid, lstart: v.lstart, prior: PRIORS.includes(v.prior) ? v.prior : "none" };
|
|
189
|
+
};
|
|
190
|
+
const { quiet, elapsed, digest, beat, ticked, controller, ...rest } = parsed;
|
|
156
191
|
return {
|
|
157
192
|
quiet: num(quiet),
|
|
158
193
|
elapsed: num(elapsed),
|
|
159
194
|
digest: typeof digest === "string" ? digest : "",
|
|
160
195
|
beat: mark(beat),
|
|
161
196
|
ticked: tick(ticked),
|
|
197
|
+
controller: ctl(controller),
|
|
162
198
|
rest,
|
|
163
199
|
};
|
|
164
200
|
}
|
|
@@ -182,13 +218,13 @@ export function readState(path, name) {
|
|
|
182
218
|
// writeFileSync truncates and then writes, and readState() maps the empty or
|
|
183
219
|
// half-written file a reader can land on to the fresh, no-mark state on
|
|
184
220
|
// purpose — so a reader racing a live beat read "no mark", and ledger.mjs
|
|
185
|
-
// rotate, which refuses only while a mark is
|
|
186
|
-
// controller's ledger. rename is atomic on POSIX: a
|
|
187
|
-
// file or the whole new one. The temp name carries
|
|
188
|
-
// ledger.mjs gives:
|
|
189
|
-
// lets one rename
|
|
190
|
-
// into place is removed rather than left to accumulate,
|
|
191
|
-
// invocation, beside the file it failed to replace.
|
|
221
|
+
// rotate, which with no controller record refuses only while a mark is
|
|
222
|
+
// beating, moved a live controller's ledger. rename is atomic on POSIX: a
|
|
223
|
+
// reader sees the whole old file or the whole new one. The temp name carries
|
|
224
|
+
// the pid for the reason ledger.mjs gives: several scripts write this file,
|
|
225
|
+
// and a shared temp name lets one rename another's out from under it. A temp
|
|
226
|
+
// that never made it into place is removed rather than left to accumulate,
|
|
227
|
+
// one per failed invocation, beside the file it failed to replace.
|
|
192
228
|
export function writeState(path, name, prev, patch) {
|
|
193
229
|
// Built from the VALIDATED view plus the fields outside the schema, never
|
|
194
230
|
// from the raw parse: see `rest` in readState above.
|
|
@@ -206,6 +242,11 @@ export function writeState(path, name, prev, patch) {
|
|
|
206
242
|
// every hold and would otherwise erase fleet-tick's `ticked` the first
|
|
207
243
|
// time a heartbeat lands after a busy stretch.
|
|
208
244
|
...(prev.ticked ? { ticked: prev.ticked } : {}),
|
|
245
|
+
// And again for ledger.mjs rotate's `controller`, which both scripts
|
|
246
|
+
// above would otherwise erase on their next write. A patch REMOVES a key
|
|
247
|
+
// by naming it with the value `undefined`, which JSON.stringify drops —
|
|
248
|
+
// the way rotate retires a record no omp ancestor replaces.
|
|
249
|
+
...(prev.controller ? { controller: prev.controller } : {}),
|
|
209
250
|
...patch,
|
|
210
251
|
};
|
|
211
252
|
const tmp = `${path}.${process.pid}.tmp`;
|
package/scripts/ledger.mjs
CHANGED
|
@@ -37,7 +37,8 @@ import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
|
|
|
37
37
|
import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
|
|
38
38
|
import { parseMember, parseToken, memberTokens, nextMergeBot, agentDefinition, CELL, tierValues, rowPr, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
|
|
39
39
|
import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
|
|
40
|
-
import { stateFileIn, readState, assessBeat, stallsAt } from "./fleet-state.mjs";
|
|
40
|
+
import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
|
|
41
|
+
import { isDead, processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
|
|
41
42
|
|
|
42
43
|
const NAME = "ledger";
|
|
43
44
|
// The plugin's own agent definitions — the directory tier-check.mjs reads
|
|
@@ -589,17 +590,6 @@ function readLock() {
|
|
|
589
590
|
}
|
|
590
591
|
}
|
|
591
592
|
|
|
592
|
-
// ESRCH alone is dead. EPERM is a live process we may not signal, and any
|
|
593
|
-
// other error is not evidence of death either.
|
|
594
|
-
function isDead(pid) {
|
|
595
|
-
try {
|
|
596
|
-
process.kill(pid, 0);
|
|
597
|
-
return false;
|
|
598
|
-
} catch (e) {
|
|
599
|
-
return e.code === "ESRCH";
|
|
600
|
-
}
|
|
601
|
-
}
|
|
602
|
-
|
|
603
593
|
// true when the takeover ran (whatever it found under the reap lock), so the
|
|
604
594
|
// caller retries the create at once; false when another waiter holds the
|
|
605
595
|
// reap lock, so the caller waits like any other contended lock.
|
|
@@ -1510,38 +1500,86 @@ function runCheck() {
|
|
|
1510
1500
|
// writer either lands before the move (in the archive, whole) or after it (in
|
|
1511
1501
|
// the fresh skeleton) — never half in each.
|
|
1512
1502
|
//
|
|
1513
|
-
// The liveness guard reads the heartbeat
|
|
1514
|
-
//
|
|
1515
|
-
//
|
|
1516
|
-
//
|
|
1517
|
-
//
|
|
1518
|
-
//
|
|
1519
|
-
//
|
|
1503
|
+
// The liveness guard reads `controller` in the heartbeat file beside the
|
|
1504
|
+
// ledger, the record the previous run's rotate left: the omp process that
|
|
1505
|
+
// owned that run and its start time. It is judged once, before anything is
|
|
1506
|
+
// written. A recorded controller that is alive, still the process it was
|
|
1507
|
+
// (same start time), and not an ancestor of this call owns this file —
|
|
1508
|
+
// whatever its heartbeat mark says, because a controller can stop beating
|
|
1509
|
+
// and keep dispatching — and rotating under it would split its run across
|
|
1510
|
+
// two ledgers. A dead one, a reused pid, or this session's own earlier run
|
|
1511
|
+
// allows the rotation. With no record the guard falls back to the mark, read
|
|
1512
|
+
// through fleet-state.mjs's own reader and verdict: still beating refuses; a
|
|
1513
|
+
// stalled mark, a recorded stop, or no mark at all allows the rotation, and
|
|
1514
|
+
// that fallback proves "not beating", never "dead".
|
|
1515
|
+
//
|
|
1516
|
+
// A heartbeat file that exists but cannot be read or parsed gets neither
|
|
1517
|
+
// verdict: a record it may hold cannot be known, so rotate refuses rather
|
|
1518
|
+
// than read the fault as "no record".
|
|
1519
|
+
//
|
|
1520
|
+
// Its last act, whether or not there was a ledger to move, replaces the
|
|
1521
|
+
// record with this run's own, carrying the verdict as `prior` — the next
|
|
1522
|
+
// step reads `prior`, because the new record always names this run's own
|
|
1523
|
+
// live ancestor. No omp ancestor removes the key: an older run's record left
|
|
1524
|
+
// in place would be judged again, as dead, by a run that cannot know whether
|
|
1525
|
+
// the run after it is still live. This run's own record is computed before
|
|
1526
|
+
// anything moves too, so a process table that cannot be read refuses with
|
|
1527
|
+
// nothing moved rather than after the move.
|
|
1520
1528
|
function runRotate() {
|
|
1521
|
-
if (!existsSync(file)) {
|
|
1522
|
-
console.error(` nothing to rotate: ${file} does not exist`);
|
|
1523
|
-
console.log(JSON.stringify({ rotated: false, archive: null }));
|
|
1524
|
-
return;
|
|
1525
|
-
}
|
|
1526
1529
|
const beatFile = stateFileIn(dirname(file));
|
|
1527
|
-
const
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
+
const state = readState(beatFile, NAME);
|
|
1531
|
+
const { beat, ticked, controller } = state;
|
|
1532
|
+
// A file that exists and could not be used holds no record we can know of:
|
|
1533
|
+
// reading it as "no record" would let a live controller's ledger be moved
|
|
1534
|
+
// by exactly the fault that hid its record.
|
|
1535
|
+
if (state.degraded) {
|
|
1536
|
+
die(`refusing to rotate ${file}: ${beatFile} exists but cannot be read or parsed, so a controller record in it cannot be judged — repair or remove it`);
|
|
1530
1537
|
}
|
|
1531
|
-
|
|
1532
|
-
const archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
|
|
1538
|
+
let prior, ours;
|
|
1533
1539
|
try {
|
|
1534
|
-
|
|
1540
|
+
const source = processSource();
|
|
1541
|
+
const chain = ancestry(source);
|
|
1542
|
+
prior = judgeController(controller, source, chain);
|
|
1543
|
+
ours = controllerOf(source, chain);
|
|
1535
1544
|
} catch (e) {
|
|
1536
|
-
|
|
1545
|
+
if (!(e instanceof ProcUnreadable)) throw e;
|
|
1546
|
+
die(`refusing to rotate ${file}: ${e.message} — ${controller === null ? "this run's own controller cannot be determined" : `the controller recorded in ${beatFile} cannot be judged`}`);
|
|
1537
1547
|
}
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
}
|
|
1541
|
-
|
|
1548
|
+
if (prior === "alive") {
|
|
1549
|
+
die(`refusing to rotate ${file}: the controller that owns it is alive — controller pid ${controller.pid} (started ${controller.lstart}) recorded in ${beatFile} is alive and not an ancestor of this run, whatever its heartbeat mark says; one controller per checkout — end that omp session, or start the run from inside it`);
|
|
1550
|
+
}
|
|
1551
|
+
// The fallback guards a ledger, as it always has: with none to move there
|
|
1552
|
+
// is nothing for a beating mark to protect.
|
|
1553
|
+
const exists = existsSync(file);
|
|
1554
|
+
if (prior === "none" && exists && assessBeat({ beat, ticked, now: Date.now() }).kind === "beating") {
|
|
1555
|
+
die(`refusing to rotate ${file}: the controller that owns it is still beating — last beat ${new Date(beat.at).toISOString()} in ${beatFile}; it counts as stalled after ${new Date(stallsAt({ beat, ticked })).toISOString()}`);
|
|
1556
|
+
}
|
|
1557
|
+
let archive = null;
|
|
1558
|
+
if (exists) {
|
|
1559
|
+
const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
|
|
1560
|
+
archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
|
|
1561
|
+
try {
|
|
1562
|
+
linkSync(file, archive);
|
|
1563
|
+
} catch (e) {
|
|
1564
|
+
die(e.code === "EEXIST" ? `refusing to rotate ${file}: ${archive} already exists` : `cannot rotate ${file} to ${archive}: ${e.message}`);
|
|
1565
|
+
}
|
|
1566
|
+
try {
|
|
1567
|
+
unlinkSync(file);
|
|
1568
|
+
} catch (e) {
|
|
1569
|
+
die(`archived ${file} as ${archive} but could not remove it: ${e.message} — remove it by hand before the next write`);
|
|
1570
|
+
}
|
|
1571
|
+
console.error(` rotated ${file} -> ${archive}`);
|
|
1572
|
+
} else {
|
|
1573
|
+
console.error(` nothing to rotate: ${file} does not exist`);
|
|
1574
|
+
}
|
|
1575
|
+
// Re-read rather than reuse the read above: the heartbeat file has other
|
|
1576
|
+
// writers, and a patch built from an older view would undo what they wrote
|
|
1577
|
+
// since.
|
|
1578
|
+
const record = ours === null ? undefined : { ...ours, prior };
|
|
1579
|
+
if (!writeState(beatFile, NAME, readState(beatFile, NAME), { controller: record })) {
|
|
1580
|
+
die(`${archive === null ? "found no ledger" : `rotated ${file} -> ${archive}`} but could not record this run's controller in ${beatFile} — the next run judges whatever record that file still holds, and none if it cannot be read`);
|
|
1542
1581
|
}
|
|
1543
|
-
console.
|
|
1544
|
-
console.log(JSON.stringify({ rotated: true, archive }));
|
|
1582
|
+
console.log(JSON.stringify({ rotated: archive !== null, archive }));
|
|
1545
1583
|
}
|
|
1546
1584
|
|
|
1547
1585
|
// ── dispatch / settle ────────────────────────────────────────────────────────
|
package/scripts/proc.mjs
ADDED
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
// Process liveness and the process tree, in one place: the ledger lock's dead
|
|
2
|
+
// holder and the controller record in heartbeat.json are judged by the same
|
|
3
|
+
// predicate, so the two cannot disagree about what "dead" means.
|
|
4
|
+
|
|
5
|
+
import { readFileSync } from "node:fs";
|
|
6
|
+
import { spawnSync } from "node:child_process";
|
|
7
|
+
import { basename } from "node:path";
|
|
8
|
+
|
|
9
|
+
// ESRCH alone is dead. EPERM is a live process we may not signal, and any
|
|
10
|
+
// other error is not evidence of death either.
|
|
11
|
+
export function isDead(pid) {
|
|
12
|
+
try {
|
|
13
|
+
process.kill(pid, 0);
|
|
14
|
+
return false;
|
|
15
|
+
} catch (e) {
|
|
16
|
+
return e.code === "ESRCH";
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
// Thrown when the process tree or a start time cannot be read. A caller that
|
|
21
|
+
// would act on a verdict refuses instead: a controller nobody could judge is
|
|
22
|
+
// never judged dead.
|
|
23
|
+
export class ProcUnreadable extends Error {}
|
|
24
|
+
|
|
25
|
+
// The two reads the controller record needs — a process's parent and argv,
|
|
26
|
+
// and its start time — behind one source. The real one is `ps`. A
|
|
27
|
+
// FLEET_PROC_TABLE file replaces it whole: a test suite run from inside a live
|
|
28
|
+
// omp session would otherwise find that session's omp as its ancestor. The
|
|
29
|
+
// file is a JSON object keyed by pid:
|
|
30
|
+
//
|
|
31
|
+
// { "<pid>": { "ppid": <pid>, "argv": ["bun", "/…/omp"], "lstart": "<start>" } }
|
|
32
|
+
//
|
|
33
|
+
// A pid the table does not name has no parent and no start time, as a pid
|
|
34
|
+
// `ps` does not list.
|
|
35
|
+
export function processSource(env = process.env) {
|
|
36
|
+
return env.FLEET_PROC_TABLE ? tableSource(env.FLEET_PROC_TABLE) : psSource(env);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function tableSource(path) {
|
|
40
|
+
let table;
|
|
41
|
+
try {
|
|
42
|
+
table = JSON.parse(readFileSync(path, "utf8"));
|
|
43
|
+
} catch (e) {
|
|
44
|
+
throw new ProcUnreadable(`cannot read the process table ${path}: ${e.message}`);
|
|
45
|
+
}
|
|
46
|
+
const bad = tableProblem(table);
|
|
47
|
+
if (bad !== null) throw new ProcUnreadable(`cannot read the process table ${path}: ${bad}`);
|
|
48
|
+
const entry = (pid) => (Object.hasOwn(table, String(pid)) ? table[String(pid)] : null);
|
|
49
|
+
return {
|
|
50
|
+
parentOf: (pid) => {
|
|
51
|
+
const e = entry(pid);
|
|
52
|
+
return e ? { ppid: e.ppid, argv: e.argv } : null;
|
|
53
|
+
},
|
|
54
|
+
startTime: (pid) => entry(pid)?.lstart ?? null,
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Why `table` is not the shape processSource() documents, or null when it is:
|
|
59
|
+
// a plain object whose every entry names an integer parent, an argv of
|
|
60
|
+
// strings, and — when it names one at all — a start time that is a string.
|
|
61
|
+
function tableProblem(table) {
|
|
62
|
+
if (table === null || typeof table !== "object" || Array.isArray(table)) return "it is not a JSON object keyed by pid";
|
|
63
|
+
for (const [pid, e] of Object.entries(table)) {
|
|
64
|
+
if (e === null || typeof e !== "object" || Array.isArray(e)) return `pid ${pid} is not an object`;
|
|
65
|
+
if (!Number.isInteger(e.ppid)) return `pid ${pid} has no integer ppid`;
|
|
66
|
+
if (!Array.isArray(e.argv) || !e.argv.every((a) => typeof a === "string")) return `pid ${pid} has no argv array of strings`;
|
|
67
|
+
if (e.lstart !== undefined && typeof e.lstart !== "string") return `pid ${pid} has an lstart that is not a string`;
|
|
68
|
+
}
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function psSource(env) {
|
|
73
|
+
// `lstart` is printed in the caller's zone and locale, and a later run —
|
|
74
|
+
// with its own TZ — compares it as an opaque string. Pinning both makes the
|
|
75
|
+
// string a property of the process, not of whoever asked.
|
|
76
|
+
const psEnv = { ...env, TZ: "UTC", LC_ALL: "C" };
|
|
77
|
+
const ps = (args) => {
|
|
78
|
+
const r = spawnSync("ps", args, { encoding: "utf8", env: psEnv });
|
|
79
|
+
if (r.error) throw new ProcUnreadable(`cannot read the process table: ps: ${r.error.message}`);
|
|
80
|
+
return r;
|
|
81
|
+
};
|
|
82
|
+
let parents = null;
|
|
83
|
+
return {
|
|
84
|
+
parentOf(pid) {
|
|
85
|
+
if (parents === null) {
|
|
86
|
+
// -ww: without it `args` is cut to the terminal width, and the
|
|
87
|
+
// omp path can be the part that is cut.
|
|
88
|
+
const r = ps(["-A", "-ww", "-o", "pid=,ppid=,args="]);
|
|
89
|
+
if (r.status !== 0) throw new ProcUnreadable(`cannot read the process table: ps -A exited ${r.status}: ${r.stderr.trim()}`);
|
|
90
|
+
parents = parsePs(r.stdout);
|
|
91
|
+
}
|
|
92
|
+
return parents.get(pid) ?? null;
|
|
93
|
+
},
|
|
94
|
+
startTime(pid) {
|
|
95
|
+
const r = ps(["-o", "lstart=", "-p", String(pid)]);
|
|
96
|
+
const out = r.stdout.trim();
|
|
97
|
+
if (r.status === 0 && out !== "") return out;
|
|
98
|
+
// Exit 1 with nothing on either stream is `ps` selecting no process:
|
|
99
|
+
// the pid is gone. Anything else is a `ps` that did not answer.
|
|
100
|
+
if (r.status === 1 && out === "" && r.stderr.trim() === "") return null;
|
|
101
|
+
throw new ProcUnreadable(`cannot read the start time of pid ${pid}: ps exited ${r.status}: ${r.stderr.trim()}`);
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// `args` is argv joined by single spaces, so an argument that itself holds a
|
|
107
|
+
// space splits here; the omp match only reads argv[0] and argv[1], and a path
|
|
108
|
+
// with a space in it misses the match rather than mismatching.
|
|
109
|
+
function parsePs(text) {
|
|
110
|
+
const parents = new Map();
|
|
111
|
+
for (const line of text.split("\n")) {
|
|
112
|
+
const m = /^\s*(\d+)\s+(\d+)(.*)$/.exec(line);
|
|
113
|
+
if (m) parents.set(Number(m[1]), { ppid: Number(m[2]), argv: m[3].trim().split(/\s+/) });
|
|
114
|
+
}
|
|
115
|
+
return parents;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// The caller's ancestors, nearest first, from its parent up to the first pid
|
|
119
|
+
// the source cannot place.
|
|
120
|
+
export function ancestry(source, start = process.ppid) {
|
|
121
|
+
const chain = [];
|
|
122
|
+
const seen = new Set();
|
|
123
|
+
for (let pid = start; pid > 0 && !seen.has(pid);) {
|
|
124
|
+
seen.add(pid);
|
|
125
|
+
const e = source.parentOf(pid);
|
|
126
|
+
if (e === null) break;
|
|
127
|
+
chain.push({ pid, argv: e.argv });
|
|
128
|
+
pid = e.ppid;
|
|
129
|
+
}
|
|
130
|
+
return chain;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
// omp runs as `bun …/omp`, so its process name is `bun` and only its first
|
|
134
|
+
// argument names it; an installed binary would be argv[0]. The file name must
|
|
135
|
+
// be exactly `omp`.
|
|
136
|
+
const isOmp = (argv) => argv.slice(0, 2).some((a) => basename(a) === "omp");
|
|
137
|
+
|
|
138
|
+
// The record this run writes: the nearest omp ancestor and its start time, or
|
|
139
|
+
// null when the chain holds none. Nearest, because two omp sessions can be
|
|
140
|
+
// live in one checkout and one can be the other's ancestor.
|
|
141
|
+
export function controllerOf(source, chain) {
|
|
142
|
+
const omp = chain.find((e) => isOmp(e.argv));
|
|
143
|
+
if (!omp) return null;
|
|
144
|
+
const lstart = source.startTime(omp.pid);
|
|
145
|
+
return lstart === null ? null : { pid: omp.pid, lstart };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// What a recorded controller is now, judged against the caller's chain:
|
|
149
|
+
// none no record
|
|
150
|
+
// dead isDead() says so, or the pid's start time is not the recorded
|
|
151
|
+
// one — a reused pid, which the record must outlast for days
|
|
152
|
+
// where the ledger lock tolerates it for seconds
|
|
153
|
+
// ancestor the record names one of the caller's own ancestors
|
|
154
|
+
// alive any other live controller
|
|
155
|
+
export function judgeController(record, source, chain) {
|
|
156
|
+
if (!record) return "none";
|
|
157
|
+
if (isDead(record.pid)) return "dead";
|
|
158
|
+
if (source.startTime(record.pid) !== record.lstart) return "dead";
|
|
159
|
+
if (chain.some((e) => e.pid === record.pid)) return "ancestor";
|
|
160
|
+
return "alive";
|
|
161
|
+
}
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -349,16 +349,33 @@ phase, or in any later one, asks the maintainer which tickets to take.
|
|
|
349
349
|
collision and sequence checks, and a killed member's ticket through a new
|
|
350
350
|
member under a new name. An exclusion that expires with the run that wrote
|
|
351
351
|
it (`deferred-to-session-end` and its like) must be restated if it still
|
|
352
|
-
holds.
|
|
353
|
-
|
|
354
|
-
the
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
352
|
+
holds. **The guard is the
|
|
353
|
+
controller record**, `controller` in `.fleet/heartbeat.json`: the omp
|
|
354
|
+
process the previous run's rotation found above itself, and that
|
|
355
|
+
process's start time. Rotate judges it once, before anything moves. A
|
|
356
|
+
recorded controller that is still alive, still the same process (its
|
|
357
|
+
start time matches), and not an ancestor of this run refuses — exit 2,
|
|
358
|
+
nothing moved — **whatever its heartbeat mark says**, because a
|
|
359
|
+
controller can stop beating and keep dispatching. A dead one, a pid
|
|
360
|
+
reused by another process, or this session's own earlier run lets it
|
|
361
|
+
rotate. With no record the heartbeat mark decides, as the only guard
|
|
362
|
+
there is: still beating refuses, naming the last beat and when it would
|
|
363
|
+
count as stalled; a stalled mark, a recorded `--stop`, or no mark at all
|
|
364
|
+
lets it rotate — and that fallback proves "not beating", never "dead", and
|
|
365
|
+
guards a ledger only: with none to move the mark is not consulted. With no
|
|
366
|
+
ledger the record is still judged, so a live recorded controller refuses
|
|
367
|
+
even then. It also refuses, nothing moved, when the stamped archive name
|
|
368
|
+
already exists, when the process table cannot be read, or when
|
|
369
|
+
`.fleet/heartbeat.json` exists but cannot be read or parsed — a record
|
|
370
|
+
nobody could judge is never taken for no record. Its last act, ledger or none, is
|
|
371
|
+
to replace the record with this run's own — the nearest `omp` process
|
|
372
|
+
above it, its start time, and as `prior` the verdict it reached on the
|
|
373
|
+
record it found (`dead`, `ancestor` or `none`) — or to remove the key when
|
|
374
|
+
no `omp` process is above it. That write can fail, and then exit 2 follows
|
|
375
|
+
a move: `rotated <file> -> <archive>` on stderr, then the refusal that the
|
|
376
|
+
record could not be written. Run the rotation before this run's own first
|
|
377
|
+
tick or beat, either of which writes the mark the fallback reads. Older
|
|
378
|
+
archives, hand-named ones included, are left alone.
|
|
362
379
|
|
|
363
380
|
**Derive the Recipe — the Recipe derivation step — before the fold-in below
|
|
364
381
|
and before the first claim.** Every claim runs this repository's Install
|
|
@@ -3754,8 +3771,12 @@ live count from it, so nobody states one. Write neither by hand:
|
|
|
3754
3771
|
- **`ledger.mjs rotate`** — phase 0's first ledger write, every run: moves
|
|
3755
3772
|
the file as-is to `ledger.<UTC YYYY-MM-DDTHHMMSSZ>.md` beside it under the
|
|
3756
3773
|
same `<file>.lock`, and the next write starts the empty skeleton. Refused
|
|
3757
|
-
while the
|
|
3758
|
-
|
|
3774
|
+
while the recorded controller is alive and not this run's ancestor, ledger
|
|
3775
|
+
or none — or, with no record and a ledger to move, while the heartbeat mark
|
|
3776
|
+
is still beating — or when the archive name already exists, the process
|
|
3777
|
+
table or `.fleet/heartbeat.json` cannot be read; with no ledger and no such
|
|
3778
|
+
refusal it moves nothing and exits 0. Then it records this run's controller
|
|
3779
|
+
in `.fleet/heartbeat.json`. Phase 0 states the guard.
|
|
3759
3780
|
|
|
3760
3781
|
`row` refuses a malformed member token anywhere in its text — one whose outcome
|
|
3761
3782
|
is outside the vocabulary above, e.g. `merge-bot-1=dispatched` — at exit 2,
|