@feigi/fleet-ctl 3.30.32 → 3.30.34

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.30.32",
3
+ "version": "3.30.34",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -1,9 +1,10 @@
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.
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 two scripts can share one file
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 both scripts wrote would need locking to be
33
- // correct, and neither script is in a position to hold one.
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 fresh;
133
+ return degraded;
111
134
  }
112
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
135
+ if (!isRecord(parsed)) {
113
136
  console.error(`${name}: WARNING ${path} is not an object — restarting at the base interval`);
114
- return fresh;
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 (!v || typeof v !== "object" || Array.isArray(v)) return null;
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 (!v || typeof v !== "object" || Array.isArray(v)) return null;
174
+ if (!isRecord(v)) return null;
152
175
  const at = num(v.at);
153
176
  return at === 0 ? null : { at };
154
177
  };
155
- const { quiet, elapsed, digest, beat, ticked, ...rest } = parsed;
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 beating, moved a live
186
- // controller's ledger. rename is atomic on POSIX: a reader sees the whole old
187
- // file or the whole new one. The temp name carries the pid for the reason
188
- // ledger.mjs gives: two scripts write this file, and a shared temp name
189
- // lets one rename the other's out from under it. A temp that never made it
190
- // into place is removed rather than left to accumulate, one per failed
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`;
@@ -1280,8 +1280,9 @@ function main() {
1280
1280
  const prev = readState(path, NAME);
1281
1281
  const digest = createHash("sha256").update(lines.join("\n")).digest("hex");
1282
1282
  const acts = actionable(rows);
1283
- // `ticked`, fleet-tick's own liveness key: written on
1284
- // every invocation unconditionally — this tick running IS the occurrence.
1283
+ // `ticked`, fleet-tick's own liveness key: written on every tick that gets
1284
+ // past its refusals — a refused tick (exit 2) writes none; this tick
1285
+ // reaching here IS the occurrence.
1285
1286
  writeState(path, NAME, prev, { quiet: acts ? 0 : prev.quiet + 1, digest, ticked: { at: Date.now() } });
1286
1287
 
1287
1288
  // Fold only when BOTH hold: nothing to act on, and nothing new to say. A
@@ -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 mark beside the ledger, through
1514
- // fleet-state.mjs's own reader and verdict: a controller whose mark is still
1515
- // beating owns this file, and rotating under it would split its run across
1516
- // two ledgers. A stalled mark, a recorded stop, or no mark at all allows the
1517
- // rotation. The guard proves "not beating", never "dead": a controller alive
1518
- // but busy outside its heartbeat hold for longer than its recorded interval
1519
- // reads as stalled, and is rotated under.
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 { beat, ticked } = readState(beatFile, NAME);
1528
- if (assessBeat({ beat, ticked, now: Date.now() }).kind === "beating") {
1529
- 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()}`);
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
- const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
1532
- const archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
1538
+ let prior, ours;
1533
1539
  try {
1534
- linkSync(file, archive);
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
- die(e.code === "EEXIST" ? `refusing to rotate ${file}: ${archive} already exists` : `cannot rotate ${file} to ${archive}: ${e.message}`);
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
- try {
1539
- unlinkSync(file);
1540
- } catch (e) {
1541
- die(`archived ${file} as ${archive} but could not remove it: ${e.message} — remove it by hand before the next write`);
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.error(` rotated ${file} -> ${archive}`);
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 ────────────────────────────────────────────────────────
@@ -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
+ }
@@ -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. No ledger is exit 0, nothing to rotate. It refuses — exit 2,
353
- nothing moved — when the stamped archive name already exists, and while
354
- the heartbeat mark beside the ledger is still beating, naming the last
355
- beat and when it would count as stalled; a stalled mark, a recorded
356
- `--stop`, or no mark at all lets it rotate. **The guard proves "not
357
- beating", never "dead":** a previous controller that is alive but busy
358
- outside its heartbeat hold for longer than its recorded interval reads as
359
- stalled, and its ledger is rotated out from under it. Run the rotation
360
- before this run's own first tick or beat, either of which writes the mark
361
- the guard reads. Older archives, hand-named ones included, are left alone.
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 heartbeat mark is still beating or when the archive name already
3758
- exists; no ledger is exit 0. Phase 0 states the guard's limit.
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,