@feigi/fleet-ctl 3.37.1 → 3.38.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.37.1",
3
+ "version": "3.38.0",
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": {
@@ -35,6 +35,12 @@
35
35
  // when rotate wrote it — a mark older than `at` is the previous
36
36
  // run's. Removed, not left stale, by a rotate that finds no omp
37
37
  // ancestor.
38
+ // seen fleet-tick only. {member: firstSeenAtMs}: the first tick that saw
39
+ // each live ledger token, so a later tick can say how long a token
40
+ // has stayed live — the ledger records that a member was dispatched,
41
+ // never when. Pruned to the live set on every tick, so a settled
42
+ // member's stamp does not outlive it. Carried, never written, by
43
+ // the heartbeat and by rotate.
38
44
  //
39
45
  // One writer per key. A key two scripts wrote would need locking to be
40
46
  // correct, and none of them is in a position to hold one. That holds per key,
@@ -105,7 +111,7 @@ export function readState(path, name) {
105
111
  // to judge and nothing to report. A zeroed mark would date the beat to the
106
112
  // epoch and read as decades overdue on a run that has simply not started
107
113
  // one — the cry-wolf direction this key must never fail in.
108
- const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, controller: null, rest: {} };
114
+ const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, controller: null, seen: {}, rest: {} };
109
115
  // The same state, flagged: the file EXISTS and could not be used. A caller
110
116
  // that acts on the absence of a record — ledger.mjs rotate — must tell this
111
117
  // from `fresh`, which is a run that has simply not written one yet.
@@ -197,7 +203,17 @@ export function readState(path, name) {
197
203
  at: Number.isInteger(v.at) && v.at > 0 ? v.at : null,
198
204
  };
199
205
  };
200
- const { quiet, elapsed, digest, beat, ticked, controller, ...rest } = parsed;
206
+ // `seen` is validated per entry, not as a unit: each stamp is a separate
207
+ // member's age, so one junk entry costs only that member its age. A stamp
208
+ // that cannot be read restarts that member's clock, which is the late
209
+ // direction — never the early one, where a healthy member reads as stuck.
210
+ const stamps = (v) => {
211
+ if (!isRecord(v)) return {};
212
+ const out = {};
213
+ for (const [member, at] of Object.entries(v)) if (Number.isInteger(at) && at > 0) out[member] = at;
214
+ return out;
215
+ };
216
+ const { quiet, elapsed, digest, beat, ticked, controller, seen, ...rest } = parsed;
201
217
  return {
202
218
  quiet: num(quiet),
203
219
  elapsed: num(elapsed),
@@ -205,6 +221,7 @@ export function readState(path, name) {
205
221
  beat: mark(beat),
206
222
  ticked: tick(ticked),
207
223
  controller: ctl(controller),
224
+ seen: stamps(seen),
208
225
  rest,
209
226
  };
210
227
  }
@@ -257,6 +274,9 @@ export function writeState(path, name, prev, patch) {
257
274
  // by naming it with the value `undefined`, which JSON.stringify drops —
258
275
  // the way rotate retires a record no omp ancestor replaces.
259
276
  ...(prev.controller ? { controller: prev.controller } : {}),
277
+ // `seen` is fleet-tick's, and the heartbeat and rotate write this file
278
+ // too: carried the same way, so neither erases the ages the tick keeps.
279
+ ...(prev.seen && Object.keys(prev.seen).length > 0 ? { seen: prev.seen } : {}),
260
280
  ...patch,
261
281
  };
262
282
  const tmp = `${path}.${process.pid}.tmp`;
@@ -269,7 +289,7 @@ export function writeState(path, name, prev, patch) {
269
289
  // Best-effort and never fatal: a cleanup that threw would turn a reported,
270
290
  // survived write failure into the crash the comment above rules out.
271
291
  try { rmSync(tmp, { force: true }); } catch {}
272
- console.error(`${name}: WARNING could not write ${path} (${e.message}) — back-off progress will not persist`);
292
+ console.error(`${name}: WARNING could not write ${path} (${e.message}) — back-off progress and the liveness ages the tick stamps will not persist`);
273
293
  return false;
274
294
  }
275
295
  }
@@ -56,12 +56,20 @@
56
56
  // file reads DEFAULT-ONLY, the way the router (not in the tree
57
57
  // yet) is to read it. pr-cost.mjs writes the main
58
58
  // workspace's file by default, the one read here.
59
+ // seen `seen` in the heartbeat's state file, this script's own key:
60
+ // when it first saw each live token. The ledger records that a
61
+ // member was dispatched, never when, so the age of a live token
62
+ // exists nowhere else. A token live past its family's threshold
63
+ // prints one `CHECK-LIVENESS` line — advice to the controller to
64
+ // take the registry census, never an action: it resets no
65
+ // `quiet`, changes no row and frees no slot, and the tick never
66
+ // settles or kills anything.
59
67
  //
60
68
  // The pure half below is `reconcile()` over the counts `deriveRun()` reads off
61
69
  // the ledger; main() does the I/O. Split so the guard table and the reading are
62
70
  // both unit-testable without a network.
63
71
 
64
- import { parseMember, parseToken, premisesOf, rowNums, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
72
+ import { parseMember, parseToken, premisesOf, rowNums, nextRetry, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
65
73
 
66
74
  // Every role's TARGET is its configured cap. Availability of work belongs in
67
75
  // the ACTION, not the target: a reviewer target that shrank to the backlog
@@ -128,20 +136,14 @@ const tierCheckStep = (members) => "run ~/.fleet/bin/fleet-run tier-check.mjs --
128
136
  + JSON.stringify(members.map((member) => ({ member, session: "<session>" })));
129
137
 
130
138
  // A mismatch clears when the next attempt on the ticket is dispatched at its
131
- // row's tier: one retry letter past the HIGHEST any impl member of that ticket
132
- // has used, not past the held member's own — a controller can dispatch `-c`
133
- // before `-b`, ledger.mjs refuses a name already dispatched, and the highest
134
- // letter is what compute-board.mjs's laterAttempt reads as the latest attempt.
135
- // No suffix is the `a` attempt (ledger-grammar.mjs orders it first). `-z` is
136
- // the grammar's last, so past it there is no legal name to print.
139
+ // row's tier: ledger-grammar.mjs's nextRetry(), one letter past the highest
140
+ // any impl member of that ticket has used, null past `-z`.
137
141
  function replaceStep(held, implNames) {
138
142
  const named = [], stuck = [];
139
143
  for (const name of held) {
140
- const { family, number } = parseMember(name);
141
- const top = [name, ...implNames].map(parseMember).filter((m) => m.number === number)
142
- .map((m) => m.retry ?? "a").sort().at(-1);
143
- if (top === "z") stuck.push(name);
144
- else named.push(`${family}-${number}-${String.fromCharCode(top.charCodeAt(0) + 1)}`);
144
+ const next = nextRetry(name, implNames);
145
+ if (next === null) stuck.push(name);
146
+ else named.push(next);
145
147
  }
146
148
  return [
147
149
  named.length ? `dispatch ${named.join(", ")} ${named.length > 1 ? "each " : ""}at its row's tier` : "",
@@ -918,6 +920,64 @@ export function refreshWhy({ draining, status, entries, unclaimed: k, implCap })
918
920
  return null;
919
921
  }
920
922
 
923
+ // How long, in minutes, a live token of each family may run before the tick
924
+ // asks the controller to look at it. Each default is that family's p99
925
+ // run time: a token past it is rare among members that finished, so a line
926
+ // is worth a look and not noise. Measured 2026-10-11. The four member
927
+ // families are the maintainer's reading of the omp rows of
928
+ // member-outcomes.tsv, one family each; `review` is
929
+ // the nearest-rank p99 of (last - first entry timestamp) over every
930
+ // review-pr-*.jsonl under ~/.omp/agent/sessions — 77.09 min over 4751
931
+ // transcripts, rounded up. Re-derive by re-running that query; no script
932
+ // carries it.
933
+ export const LIVENESS_DEFAULTS = { impl: 78, "fix-pr": 56, "finisher-pr": 57, "merge-bot": 101, review: 78 };
934
+ // One flag per family, so a controller can tune what the defaults get wrong.
935
+ const LIVENESS_FLAGS = {
936
+ impl: "liveness-impl", "fix-pr": "liveness-fix-pr", "finisher-pr": "liveness-finisher",
937
+ "merge-bot": "liveness-merge-bot", review: "liveness-review",
938
+ };
939
+
940
+ // A live name's family: a member token's own, or `review` for the in-flight
941
+ // `review:PR#<n>` a `review=` launch is named by (it carries no member token).
942
+ const livenessFamily = (name) => (name.startsWith("review:") ? "review" : parseMember(name)?.family ?? null);
943
+
944
+ // The `seen` map for this tick: one stamp per live name, carried when it can
945
+ // be trusted and `now` when not. A stamp is the age of the token, so the rule
946
+ // is which ones still describe THIS run's token:
947
+ // - an `ancestor` rotate carried this run's tokens across — they are old, and
948
+ // their age must survive it;
949
+ // - `dead` and `none` carry nothing, so a stamp older than the record's `at`
950
+ // belongs to a token of the previous run, even one that shares its name
951
+ // (`merge-bot-1` is reused), and restarts at zero;
952
+ // - no record, or one with no `at`, leaves nothing to compare, so the stamp
953
+ // stands.
954
+ // A name that is no longer live is dropped: a settled member's stamp must not
955
+ // age a later token of the same name.
956
+ export function stampSeen({ live, prev, controller, now }) {
957
+ const thisRun = (at) => controller === null || controller.prior === "ancestor" || controller.at === null || at >= controller.at;
958
+ const next = {};
959
+ for (const name of live) next[name] = prev[name] !== undefined && thisRun(prev[name]) ? prev[name] : now;
960
+ return next;
961
+ }
962
+
963
+ // The CHECK-LIVENESS lines: one per live name past its family's threshold, as
964
+ // `{member, line}`. The age shows only as a multiple of the threshold, so the
965
+ // line — and the digest `--fold-unchanged` compares — changes when a member
966
+ // crosses into the next bucket and never on the minute between.
967
+ export function livenessLines({ live, seen, thresholds, now }) {
968
+ const out = [];
969
+ for (const member of live) {
970
+ const family = livenessFamily(member);
971
+ if (family === null || seen[member] === undefined) continue;
972
+ const minutes = thresholds[family];
973
+ const k = Math.floor(Math.max(0, now - seen[member]) / (minutes * 60_000));
974
+ if (k < 1) continue;
975
+ const label = family === "finisher-pr" ? "finisher" : family;
976
+ out.push({ member, line: `CHECK-LIVENESS ${member} (${label} > ${k === 1 ? "" : `${k}×`}p99 ${k * minutes}m)` });
977
+ }
978
+ return out;
979
+ }
980
+
921
981
  // --------------------------------------------------------------------------
922
982
  // I/O. Everything below runs only as a CLI — importing this file must never
923
983
  // parse argv or touch the network, or the pure half stops being unit-testable.
@@ -993,6 +1053,8 @@ const OPTIONS = {
993
1053
  // under parseArgs, and no path is legitimately empty, so empty resolves to
994
1054
  // the default.
995
1055
  state: { type: "string", default: "" },
1056
+ // Minutes a live token of each family may run before CHECK-LIVENESS names it.
1057
+ ...Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [flag, { type: "string", default: String(LIVENESS_DEFAULTS[family]) }])),
996
1058
  };
997
1059
 
998
1060
  function options() {
@@ -1023,6 +1085,7 @@ function options() {
1023
1085
  implCap: positive("implementer-cap"), reviewerCap,
1024
1086
  maxReviews: values["max-reviews"] === undefined ? reviewerCap : positive("max-reviews"),
1025
1087
  fold: values["fold-unchanged"], state: values.state || statePath(NAME),
1088
+ liveness: Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [family, positive(flag)])),
1026
1089
  };
1027
1090
  }
1028
1091
 
@@ -1248,7 +1311,7 @@ function claimed() {
1248
1311
  }
1249
1312
 
1250
1313
  function main() {
1251
- const { fold, state: path, ...caps } = options();
1314
+ const { fold, state: path, liveness, ...caps } = options();
1252
1315
  const listPath = shortlistPath();
1253
1316
  const current = readShortlist(listPath);
1254
1317
  // Beside the shortlist, off the same git probe rather than a second one.
@@ -1316,20 +1379,33 @@ function main() {
1316
1379
  ...caps, ...run, heads, supply, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
1317
1380
  });
1318
1381
  const said = describe(mainCheckout, run.live);
1319
- const lines = [...(said === null ? [] : [said]), ...formatLines(rows)];
1382
+ // Re-read rather than reusing priorState: this must be the freshest
1383
+ // snapshot, or this tick reverts whatever the heartbeat wrote while the
1384
+ // reads above were in flight. Read before the lines are built because the
1385
+ // liveness lines need the stamps it holds, and nothing between here and the
1386
+ // write below is I/O.
1387
+ const prev = readState(path, NAME);
1388
+ const now = Date.now();
1389
+ // Advisory only: a stale token prints a line asking the controller for the
1390
+ // registry census. It is not a row — it resets no `quiet`, moves no count
1391
+ // and frees no slot — and nothing here settles, kills or writes the ledger.
1392
+ const seen = stampSeen({ live: run.live, prev: prev.seen, controller: prev.controller, now });
1393
+ const stale = livenessLines({ live: run.live, seen, thresholds: liveness, now });
1394
+ const lines = [...(said === null ? [] : [said]), ...stale.map((s) => s.line), ...formatLines(rows)];
1320
1395
 
1321
1396
  // The back-off streak and the fold digest, written on EVERY tick: an edge
1322
1397
  // tick that dispatched is the clearest possible "there is work here". Digest,
1323
- // not the lines themselves, so the file stays readable. Re-read rather than
1324
- // reusing priorState: this must be the freshest snapshot, or this tick
1325
- // reverts whatever the heartbeat wrote while the reads above were in flight.
1326
- const prev = readState(path, NAME);
1398
+ // not the lines themselves, so the file stays readable.
1327
1399
  const digest = createHash("sha256").update(lines.join("\n")).digest("hex");
1328
1400
  const acts = actionable(rows);
1329
1401
  // `ticked`, fleet-tick's own liveness key: written on every tick that gets
1330
1402
  // past its refusals — a refused tick (exit 2) writes none; this tick
1331
- // reaching here IS the occurrence.
1332
- writeState(path, NAME, prev, { quiet: acts ? 0 : prev.quiet + 1, digest, ticked: { at: Date.now() } });
1403
+ // reaching here IS the occurrence. `seen` is pruned to the live set on the
1404
+ // same write; an empty one removes the key.
1405
+ writeState(path, NAME, prev, {
1406
+ quiet: acts ? 0 : prev.quiet + 1, digest, ticked: { at: now },
1407
+ seen: Object.keys(seen).length > 0 ? seen : undefined,
1408
+ });
1333
1409
 
1334
1410
  // Fold only when BOTH hold: nothing to act on, and nothing new to say. A
1335
1411
  // main-checkout hold still holding dispatch stays named on the folded line
@@ -1339,7 +1415,11 @@ function main() {
1339
1415
  if (fold && !acts && digest === prev.digest) {
1340
1416
  const why = mainCheckoutHoldReason(mainCheckout);
1341
1417
  const held = why === null ? "" : `; HOLD (${why}) persists`;
1342
- console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held} — full rows on the next change`);
1418
+ // A stale member persists the same way: advisory, so it never resets
1419
+ // `quiet`, and named on the folded line for as long as it stays live
1420
+ // past its threshold. The digest already moves when its bucket does.
1421
+ const aged = stale.map((s) => `; CHECK-LIVENESS ${s.member} persists`).join("");
1422
+ console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held}${aged} — full rows on the next change`);
1343
1423
  return;
1344
1424
  }
1345
1425
  for (const line of lines) console.log(line);
@@ -213,11 +213,12 @@ function added(before, after) {
213
213
 
214
214
  // The runner name a new launch on PR <pr> takes: `review-pr-<pr>`, else the
215
215
  // first letter from `b` that no runner launch on the PR's rows already uses —
216
- // member or fallback, `=failed` or not. null for a stream keyed by no PR
217
- // number, or with every letter taken.
218
- function nextReviewer(launches, pr) {
216
+ // member or fallback, `=failed` or not — and no name in `retired` holds, the
217
+ // names an earlier run of this omp session launched. null for a stream keyed
218
+ // by no PR number, or with every letter taken.
219
+ function nextReviewer(launches, pr, retired) {
219
220
  if (typeof pr !== "number") return null;
220
- const used = new Set(launches.filter((l) => l.kind !== "wf").map((l) => l.name));
221
+ const used = new Set([...launches.filter((l) => l.kind !== "wf").map((l) => l.name), ...retired]);
221
222
  const base = `review-pr-${pr}`;
222
223
  if (!used.has(base)) return base;
223
224
  for (let c = "b".charCodeAt(0); c <= "z".charCodeAt(0); c++) {
@@ -275,7 +276,7 @@ export function newSplitRow(before, after) {
275
276
  /**
276
277
  * Why `ledger.mjs row` or `ledger.mjs review` must not write `line` over
277
278
  * `oldLine` (null for a new row), `before` and `after` the ledger's rows on
278
- * either side of the write —
279
+ * either side of the write, `retired` the ledger's `## Retired` names —
279
280
  * or null when it may. Only a violation the write ADDS is a reason: each
280
281
  * rule's offending entries are listed before the write and after it, and the
281
282
  * after list must hold nothing the before list lacks, duplicates counted. Where
@@ -289,11 +290,13 @@ export function newSplitRow(before, after) {
289
290
  * - paired results: every `reviewed=` answers a launch (readReviews above);
290
291
  * - unique launches: a launch identity — a workflow's runId, a runner's name
291
292
  * whatever its kind — appears at most once in its PR's stream;
293
+ * - unretired runners: no launch takes a runner name `retired` holds, which an
294
+ * earlier run of this omp session launched;
292
295
  * - one open launch per PR: no launch appears while an earlier one is open;
293
296
  * - an open launch is never removed: every launch open before the write is in
294
297
  * its PR's stream after it, `=failed` allowed, on any of the PR's rows.
295
298
  */
296
- export function rowWriteRefusal(before, after, oldLine, line) {
299
+ export function rowWriteRefusal(before, after, oldLine, line, retired = []) {
297
300
  const names = (text) => (text === null ? [] : memberTokens(text).map((t) => t.name));
298
301
  const dupes = (list) => list.filter((n, i) => list.indexOf(n) !== i);
299
302
  const member = added(dupes(names(oldLine)), dupes(names(line)))[0];
@@ -319,10 +322,16 @@ export function rowWriteRefusal(before, after, oldLine, line) {
319
322
  }
320
323
  const repeated = added(b.repeated, a.repeated)[0];
321
324
  if (repeated !== undefined) {
322
- const next = nextReviewer(a.launches, id);
325
+ const next = nextReviewer(a.launches, id, retired);
323
326
  return `launch '${repeated}' is already on ${where(id)}'s rows — unique launches: every launch takes an identity the PR has not used`
324
327
  + (next === null ? "" : `; the next free reviewer name is ${next}`);
325
328
  }
329
+ const reused = a.launches.find((l) => l.kind !== "wf" && retired.includes(l.name) && !b.launches.some((o) => o.key === l.key));
330
+ if (reused !== undefined) {
331
+ const next = nextReviewer(a.launches, id, retired);
332
+ return `launch '${reused.id}' on ${where(id)} names a runner an earlier run of this session already used — unretired runners: omp would answer it with \`${reused.name}-2\``
333
+ + (next === null ? "" : `; the next free reviewer name is ${next}`);
334
+ }
326
335
  const crowded = added(b.crowded.map((c) => c.id), a.crowded.map((c) => c.id))[0];
327
336
  if (crowded !== undefined) {
328
337
  const { open } = a.crowded.find((c) => c.id === crowded);
@@ -421,6 +430,68 @@ export function liveOnLedger(rows, dispatched) {
421
430
  return out;
422
431
  }
423
432
 
433
+ // A reviewer's runner name: `review-pr-<n>` for a PR's first, `-b`, `-c`, …
434
+ // for each later one. The only runner names the grammar knows, so the only
435
+ // ones a rotate retires; a launch under any other name retires nothing.
436
+ const REVIEWER = /^review-pr-[1-9][0-9]*(-[b-z])?$/;
437
+
438
+ /** Whether `name` is one a `## Retired` line may hold: a member's name or a
439
+ * reviewer's, bare. */
440
+ export const isRetirable = (name) => parseMember(name) !== null || REVIEWER.test(name);
441
+
442
+ // The reviewer runner names a row's `review=member:<name>` and
443
+ // `review=fallback:<name>` launches took, `=failed` or answered or open. A
444
+ // workflow launch is named by its runId, which no hub member holds.
445
+ function launchedRunners(text) {
446
+ const out = [];
447
+ for (const word of text.split(/\s+/)) {
448
+ const m = REVIEW.exec(word);
449
+ if (m !== null && m.groups.kind !== "wf" && REVIEWER.test(m.groups.name)) out.push(m.groups.name);
450
+ }
451
+ return out;
452
+ }
453
+
454
+ /**
455
+ * The names an `ancestor` rotate retires: every member the archive settled —
456
+ * in `## Dispatched` or on any row, the same two places `ledger.mjs dispatch`
457
+ * refuses a repeat from within a run — and every reviewer runner a row
458
+ * launched, that `liveOnLedger` does not carry, plus every name the archive's
459
+ * own `## Retired` already held (`retired`, bare retirable names — the caller
460
+ * validates them), once each, in that order. A retired name stays taken for
461
+ * the rest of the omp session: the process that ran the member still holds a
462
+ * peer under it, and omp answers a second task of that name with `<name>-2`
463
+ * while `hub send <name>` keeps reaching the first. `carried` is
464
+ * `{rows, dispatched}`, the texts of the rows and the `## Dispatched` entries
465
+ * the new ledger carries (`liveOnLedger`'s picks); a name it carries, live or
466
+ * as a settled copy, is on the new ledger already and is not listed twice. A
467
+ * row is read whether or not it parsed, but an unsettled member token on it
468
+ * retires nothing: only a settled name is known gone.
469
+ */
470
+ export function retiredOnLedger(rows, dispatched, retired, carried) {
471
+ const seen = new Set();
472
+ for (const e of carried.dispatched) seen.add(parseToken(e).name);
473
+ for (const text of carried.rows) {
474
+ for (const t of memberTokens(text)) if (t.error === null) seen.add(t.name);
475
+ for (const name of launchedRunners(text)) seen.add(name);
476
+ }
477
+ const out = [];
478
+ const add = (name) => {
479
+ if (seen.has(name)) return;
480
+ seen.add(name);
481
+ out.push(name);
482
+ };
483
+ for (const name of retired) add(name);
484
+ for (const e of dispatched) {
485
+ const t = parseToken(e);
486
+ if (t !== null && t.error === null && t.outcome !== null) add(t.name);
487
+ }
488
+ for (const text of rows) {
489
+ for (const t of memberTokens(text)) if (t.error === null && t.outcome !== null) add(t.name);
490
+ for (const name of launchedRunners(text)) add(name);
491
+ }
492
+ return out;
493
+ }
494
+
424
495
  // A ticket row is `#N <text>`; it is an Exclusion when `excluded` is the
425
496
  // text's first word — `impl-N · … excluded …` is a row about something else.
426
497
  // `#N excluded · behind-pr:#M` / `behind-issue:#M`: `#M` is an issue or PR
@@ -441,6 +512,7 @@ export const DISPATCHED = "## Dispatched";
441
512
  export const FILED = "## Filed";
442
513
  export const RULED = "## Ruled";
443
514
  export const DRAIN = "## Drain";
515
+ export const RETIRED = "## Retired";
444
516
 
445
517
  // What a section header looks like on disk, defined once because a second
446
518
  // copy drifts: ledger.mjs slices sections with it, and sets its readability
@@ -465,15 +537,31 @@ export function unescapeText(s) {
465
537
  }
466
538
 
467
539
  /** The name the next merge bot takes: 1 + the highest `merge-bot-<n>` in
468
- * `## Dispatched`, settled ones included — the highest, not the count, since
469
- * a rotate that carries a live bot forward carries a settled predecessor
470
- * only when a carried row names it. n restarts at 1 with every run that
471
- * carries no bot. */
472
- export function nextMergeBot(dispatched) {
473
- const ns = dispatched.map(parseToken).filter((t) => t?.family === "merge-bot").map((t) => t.number);
540
+ * `## Dispatched`, settled ones included, or among `names` — the other names
541
+ * the session holds, a retired bot's and a settled token on a row — the
542
+ * highest, not the count, since a rotate that carries a live bot forward
543
+ * carries a settled predecessor only when a carried row names it, and
544
+ * retires the rest by name. n restarts at 1 with every run that carries and
545
+ * retires no bot: a `dead` or `none` rotate, whose bots ran in an omp
546
+ * process that is gone. */
547
+ export function nextMergeBot(dispatched, names = []) {
548
+ const ns = [...dispatched.map(parseToken), ...names.map(parseMember)]
549
+ .filter((t) => t?.family === "merge-bot").map((t) => t.number);
474
550
  return `merge-bot-${Math.max(0, ...ns) + 1}`;
475
551
  }
476
552
 
553
+ /** The replacement name a member of `name`'s family and number takes next:
554
+ * one retry letter past the HIGHEST any of `names` on that number has used,
555
+ * `name` itself included — not past `name`'s own, since a controller can
556
+ * dispatch `-c` before `-b`. No suffix is the `a` attempt; `-z` is the
557
+ * grammar's last, past which there is no legal name, so null. */
558
+ export function nextRetry(name, names) {
559
+ const { family, number } = parseMember(name);
560
+ const top = [name, ...names].map(parseMember).filter((m) => m !== null && m.family === family && m.number === number)
561
+ .map((m) => m.retry ?? "a").sort().at(-1);
562
+ return top === "z" ? null : `${family}-${number}-${String.fromCharCode(top.charCodeAt(0) + 1)}`;
563
+ }
564
+
477
565
  // An implementer cell is `<role>-<level>` — an omp role and a thinking
478
566
  // level — and each cell is one definition, `fleet-implementer-<cell>`, whose
479
567
  // `model:` is `@<role>:<level>`. Nothing is named
@@ -20,7 +20,8 @@
20
20
  // dispatch and never loses or reorders one — settling annotates an entry in
21
21
  // place — which is what lets `merge-bot-<n>` be numbered from it; a rotate
22
22
  // that carries a run's live entries forward carries a settled one only for a
23
- // member a carried row names.
23
+ // member a carried row names, and retires every other settled name into
24
+ // `## Retired`, where `dispatch` and that numbering still read it.
24
25
  //
25
26
  // Writer policy: the controller owns run state
26
27
  // (`row`/`settle`/`dispatch`/`review`/`drain`/`ruled`/`rotate`); filers append
@@ -38,7 +39,7 @@ import { fileURLToPath } from "node:url";
38
39
  import { spawnSync, execFileSync } from "node:child_process";
39
40
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
40
41
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
41
- import { parseMember, parseToken, memberTokens, nextMergeBot, liveOnLedger, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, premisesOf, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
42
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, premisesOf, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
42
43
  import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
43
44
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
44
45
  import { isDead, processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -452,7 +453,7 @@ function sectionOf(text, name) {
452
453
  }
453
454
 
454
455
  function load() {
455
- if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], drain: null };
456
+ if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], drain: null, retired: [] };
456
457
  let text;
457
458
  try {
458
459
  text = readFileSync(file, "utf8");
@@ -479,12 +480,16 @@ function load() {
479
480
  return {
480
481
  rows: section(ROWS), filed: section(FILED), ruled: section(RULED),
481
482
  dispatched: section(DISPATCHED), drain: drainEntries[0] ?? null,
483
+ retired: section(RETIRED),
482
484
  };
483
485
  }
484
486
 
485
487
  // `## Drain` is written only once there is a marker to hold: an empty section
486
488
  // under that name would read, to anyone scanning the file by eye, as a run
487
- // that is draining.
489
+ // that is draining. `## Retired` likewise: only an `ancestor` rotate writes
490
+ // it (runRotate()), as the bare names of the members this omp session has
491
+ // already run and the new ledger does not carry, so a ledger without it is
492
+ // a session's first run.
488
493
  function save(d) {
489
494
  const list = (entries) => entries.map((r) => `- ${escapeText(r)}`).join("\n");
490
495
  const out =
@@ -492,7 +497,8 @@ function save(d) {
492
497
  `\n\n${DISPATCHED}\n\n` + list(d.dispatched) +
493
498
  `\n\n${FILED}\n\n` + list(d.filed) +
494
499
  `\n\n${RULED}\n\n` + list(d.ruled) +
495
- (d.drain === null ? "" : `\n\n${DRAIN}\n\n` + list([d.drain])) + "\n";
500
+ (d.drain === null ? "" : `\n\n${DRAIN}\n\n` + list([d.drain])) +
501
+ (d.retired.length === 0 ? "" : `\n\n${RETIRED}\n\n` + list(d.retired)) + "\n";
496
502
  try {
497
503
  mkdirSync(dirname(file), { recursive: true });
498
504
  // Write to a sibling temp file and rename over the target. rename is
@@ -1539,6 +1545,18 @@ function runCheck() {
1539
1545
  // against the session's job list; rotate cannot, since that list is the
1540
1546
  // controller's to read and no script's.
1541
1547
  //
1548
+ // An `ancestor` rotate also writes `## Retired`: the bare name of every
1549
+ // member the archive settled and the new ledger does not carry, of every
1550
+ // reviewer runner its rows launched and the new ledger does not carry, and
1551
+ // every name the archive's own `## Retired` held. The omp process those
1552
+ // members ran in is still this run's, and it answers a second task under a
1553
+ // name it has used with `<name>-2` while `hub send <name>` keeps reaching the
1554
+ // first — so a settled name stays taken for the session, not the run:
1555
+ // `dispatch` and `review` refuse it (a replacement takes its own suffix) and
1556
+ // `nextMergeBot` numbers past it. Measured before this: a session's second
1557
+ // run restarted at `merge-bot-1`. A `dead` or `none` rotate retires nothing,
1558
+ // since the process that held those names is gone.
1559
+ //
1542
1560
  // Under the write lock like every other write subcommand, so a concurrent
1543
1561
  // writer either lands before the move (in the archive, whole) or after it (in
1544
1562
  // the fresh skeleton) — never half in each.
@@ -1601,7 +1619,7 @@ function runRotate() {
1601
1619
  }
1602
1620
  // Read before anything moves: a ledger whose live tokens cannot be read is
1603
1621
  // refused with nothing moved, never archived with those tokens dropped.
1604
- let carry = { rows: [], dispatched: [], skipped: [] };
1622
+ let carry = { rows: [], dispatched: [], retired: [], skipped: [] };
1605
1623
  if (prior === "ancestor" && exists) {
1606
1624
  let text;
1607
1625
  try {
@@ -1611,7 +1629,7 @@ function runRotate() {
1611
1629
  }
1612
1630
  carry = carryOf(text);
1613
1631
  }
1614
- const carrying = carry.rows.length > 0 || carry.dispatched.length > 0;
1632
+ const carrying = carry.rows.length > 0 || carry.dispatched.length > 0 || carry.retired.length > 0;
1615
1633
  let archive = null;
1616
1634
  if (exists) {
1617
1635
  const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
@@ -1639,7 +1657,7 @@ function runRotate() {
1639
1657
  // Nothing to carry writes nothing, so the next write starts the skeleton
1640
1658
  // exactly as after any other verdict.
1641
1659
  if (carrying) {
1642
- save({ rows: carry.rows, dispatched: carry.dispatched, filed: [], ruled: [], drain: null });
1660
+ save({ rows: carry.rows, dispatched: carry.dispatched, filed: [], ruled: [], drain: null, retired: carry.retired });
1643
1661
  }
1644
1662
  if (archive !== null) console.error(` rotated ${file} -> ${archive}`);
1645
1663
  for (const { line, why } of carry.skipped) {
@@ -1647,6 +1665,7 @@ function runRotate() {
1647
1665
  }
1648
1666
  if (carrying) {
1649
1667
  console.error(` carried ${carry.rows.length} row(s) and ${carry.dispatched.length} ## Dispatched entr${carry.dispatched.length === 1 ? "y" : "ies"} from ${archive}`);
1668
+ console.error(` retired ${carry.retired.length} name(s) from ${archive}`);
1650
1669
  }
1651
1670
  // Re-read rather than reuse the read above: the heartbeat file has other
1652
1671
  // writers, and a patch built from an older view would undo what they wrote
@@ -1658,6 +1677,7 @@ function runRotate() {
1658
1677
  console.log(JSON.stringify({
1659
1678
  rotated: archive !== null, archive,
1660
1679
  carried: { rows: carry.rows, dispatched: carry.dispatched },
1680
+ retired: carry.retired,
1661
1681
  skipped: carry.skipped.map((s) => s.line),
1662
1682
  }));
1663
1683
  }
@@ -1675,9 +1695,14 @@ function runRotate() {
1675
1695
  // tokens, `reviewed=` and every other record on it come along, and its
1676
1696
  // siblings' with them, and the tick's per-PR reading of the PR is unchanged;
1677
1697
  // and the `## Dispatched` entries, settled ones among them, that keep a
1678
- // carried member from reading live again.
1698
+ // carried member from reading live again. retiredOnLedger() names the rest:
1699
+ // every settled member neither travels, and every reviewer runner a row
1700
+ // launched, read off the parsed rows and the skipped ones alike — a row the
1701
+ // tick refuses still names members this session ran — and the archive's own
1702
+ // `## Retired`, each line of which must be a bare member or reviewer name.
1679
1703
  function carryOf(text) {
1680
1704
  const skipped = [];
1705
+ const skippedRows = [];
1681
1706
  const rows = sectionOf(text, ROWS).filter((r) => {
1682
1707
  try {
1683
1708
  deriveRun({ rows: [r], dispatched: [], drain: null }, []);
@@ -1685,6 +1710,7 @@ function carryOf(text) {
1685
1710
  } catch (e) {
1686
1711
  if (!(e instanceof LedgerError)) throw e;
1687
1712
  skipped.push({ line: r, why: e.message });
1713
+ skippedRows.push(r);
1688
1714
  return false;
1689
1715
  }
1690
1716
  });
@@ -1694,8 +1720,15 @@ function carryOf(text) {
1694
1720
  skipped.push({ line: e, why: t === null ? "not a member token" : `${t.name}: ${t.error}` });
1695
1721
  return false;
1696
1722
  });
1723
+ const archivedRetired = sectionOf(text, RETIRED).filter((name) => {
1724
+ if (isRetirable(name)) return true;
1725
+ skipped.push({ line: name, why: "not a bare member or reviewer name" });
1726
+ return false;
1727
+ });
1697
1728
  const live = liveOnLedger(rows, dispatched);
1698
- return { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched, skipped };
1729
+ const carried = { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched };
1730
+ const retired = retiredOnLedger([...rows, ...skippedRows], dispatched, archivedRetired, carried);
1731
+ return { ...carried, retired, skipped };
1699
1732
  }
1700
1733
 
1701
1734
  // ── dispatch / settle ────────────────────────────────────────────────────────
@@ -1799,15 +1832,17 @@ function runDispatch() {
1799
1832
  refuseMalformedDispatched();
1800
1833
 
1801
1834
  // `merge-bot` bare is the merge-bot case of this command: the ledger names
1802
- // the bot, 1 + the merge-bot entries already in `## Dispatched`, so the
1803
- // controller never counts. An explicit `merge-bot-<n>` is accepted only
1804
- // when it is that one.
1805
- const member = parseMember(name === "merge-bot" ? nextMergeBot(data.dispatched) : name);
1835
+ // the bot, 1 + the highest merge-bot name this session holds — in
1836
+ // `## Dispatched`, on a row or in `## Retired` — so the controller never
1837
+ // counts. An explicit `merge-bot-<n>` is accepted only when it is that one.
1838
+ // `sessionNames` is every name beyond `## Dispatched` the session has used.
1839
+ const sessionNames = [...data.rows.flatMap(memberTokens).map((t) => t.name), ...data.retired];
1840
+ const member = parseMember(name === "merge-bot" ? nextMergeBot(data.dispatched, sessionNames) : name);
1806
1841
  if (!member) die(unknownMember(name));
1807
1842
  if (member.bound === null) {
1808
1843
  if (key !== null) die(`merge bots work no ticket or PR — ${usage}`);
1809
- const next = nextMergeBot(data.dispatched);
1810
- if (member.name !== next) die(`${member.name} is not next — the next merge bot this run is ${next}; \`dispatch merge-bot\` names it`);
1844
+ const next = nextMergeBot(data.dispatched, sessionNames);
1845
+ if (member.name !== next) die(`${member.name} is not next — the next merge bot this session is ${next}; \`dispatch merge-bot\` names it`);
1811
1846
  } else if (key === null) {
1812
1847
  die(`${member.name} works a ticket or PR — ${usage}`);
1813
1848
  }
@@ -1822,14 +1857,24 @@ function runDispatch() {
1822
1857
  die(`the run is draining (${data.drain}) — no implementer dispatch; drain stops supply`);
1823
1858
  }
1824
1859
 
1825
- // One token per member for the whole run. A settled token on a row counts
1826
- // too — a `row`-written record the ledger never saw dispatched.
1860
+ // One token per member for the whole omp session. A settled token on a row
1861
+ // counts too — a `row`-written record the ledger never saw dispatched — and
1862
+ // so does a name `## Retired` holds: an earlier run of this session ran it,
1863
+ // and omp still holds that peer under the name (see runRotate()). The
1864
+ // replacement's name is spelled out: one letter past the highest this
1865
+ // session has used on the number, wherever that name sits.
1827
1866
  const settledOnRow = data.rows.flatMap(memberTokens).find((t) => t.name === member.name && t.outcome !== null);
1828
1867
  const prior =
1829
1868
  data.dispatched.find((e) => parseToken(e).name === member.name) ??
1830
- (settledOnRow && `${settledOnRow.name}=${settledOnRow.outcome}`);
1869
+ (settledOnRow && `${settledOnRow.name}=${settledOnRow.outcome}`) ??
1870
+ (data.retired.includes(member.name) ? "retired by rotate" : undefined);
1831
1871
  if (prior !== undefined) {
1832
- die(`${member.name} was already dispatched this run (${prior}) — a replacement takes a name of its own (a -b, -c … suffix)`);
1872
+ // Never a merge bot: it is accepted only as the number past every name
1873
+ // the session holds, so none of the three places above can name it.
1874
+ const used = [...data.dispatched.map((e) => parseToken(e).name), ...sessionNames];
1875
+ const next = nextRetry(member.name, used);
1876
+ die(`${member.name} was already dispatched this session (${prior}) — a replacement takes a name of its own`
1877
+ + (next === null ? `, and ${member.name} has no retry letter left` : ` (${next})`));
1833
1878
  }
1834
1879
 
1835
1880
  // A replacement (`-b`, `-c` …) works the same ticket or PR as its
@@ -2069,7 +2114,7 @@ function runReview() {
2069
2114
  : created ? `${head} ${appended.join(" · ")}`
2070
2115
  : `${head} · ${appended.join(" · ")}`;
2071
2116
  const after = created ? [...data.rows, line] : data.rows.with(i, line);
2072
- const refusal = rowWriteRefusal(data.rows, after, oldLine, line);
2117
+ const refusal = rowWriteRefusal(data.rows, after, oldLine, line, data.retired);
2073
2118
  if (refusal !== null) die(`review #${prNum}: ${refusal}`);
2074
2119
  data.rows = after;
2075
2120
  save(data);
@@ -404,12 +404,25 @@ phase, or in any later one, asks the maintainer which tickets to take.
404
404
  or an open `review=` launch, whole and with every other token on it, plus
405
405
  every unsettled `## Dispatched` entry and the settled entry of each
406
406
  member a carried row names; exclusions, `## Filed`, `## Ruled` and the
407
- drain marker are never carried.
407
+ drain marker are never carried. Every other settled name — in
408
+ `## Dispatched` or on any row — and every reviewer runner a row launched
409
+ goes into the new ledger's `## Retired` as a bare name, with whatever the
410
+ archive's own `## Retired` held: omp answers a second `task` under a name
411
+ this process has used with `<name>-2` while `hub send <name>` keeps
412
+ reaching the first, so a settled name stays taken for the session, not
413
+ the run. `dispatch` refuses a retired name and names the replacement — one
414
+ retry letter past the highest the session has used on that number,
415
+ `impl-42-b` for a ticket this session's earlier run worked as `impl-42` —
416
+ `review` refuses a retired runner name and names the next free reviewer
417
+ name, and `dispatch merge-bot` numbers past retired bots. The tick never
418
+ reads `## Retired`: a ticket an earlier run worked is not claimed by it
419
+ and can be shortlisted again.
408
420
  A line it cannot parse is skipped with a warning naming it, and the
409
421
  rotation still succeeds. It prints `{rotated, archive, carried: {rows,
410
- dispatched}, skipped}`. The carried tokens keep the tick from dispatching
411
- onto those members' work, keep their names taken, and give their late
412
- results a token to settle; the stranded-claim step below reconciles them.
422
+ dispatched}, retired, skipped}`. The carried tokens keep the tick from
423
+ dispatching onto those members' work, keep their names taken, and give
424
+ their late results a token to settle; the stranded-claim step below
425
+ reconciles them.
413
426
  What an unclean end left in
414
427
  flight comes back through the ordinary per-run path: open PRs through the
415
428
  fold-in below, `behind-pr:`/`behind-issue:` exclusions through phase 1's
@@ -1893,6 +1906,16 @@ depth** guard table applied in code. Act on each line as it reads:
1893
1906
  baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
1894
1907
  that vanished mid-run is not a fresh run — report it to the maintainer
1895
1908
  before recording over whatever the tree now holds.
1909
+ - `CHECK-LIVENESS <member> (<family> > p99 <t>m)`, printed above the rows — a
1910
+ live ledger token has stayed live past its family's p99 run time, counted
1911
+ from the first tick that saw it (`> 2×p99 …` from the second multiple of the
1912
+ threshold on; `review:PR#<n>` names an in-flight `review=` launch). Advice,
1913
+ not an action: it is not actionable, resets no `quiet`, changes no row and
1914
+ frees no slot, and the tick settles and kills nothing. Take the census the
1915
+ **Member unaccounted** row of **Failure handling** gives before you touch the
1916
+ token. It repeats every tick while the token stays live past the threshold.
1917
+ `--liveness-impl`, `--liveness-fix-pr`, `--liveness-finisher`,
1918
+ `--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
1896
1919
 
1897
1920
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
1898
1921
  phase 2's own step: a mismatch it finds is the
@@ -1959,6 +1982,10 @@ ticket's own remedy. A dirty or unknown main checkout still folds — clearing i
1959
1982
  is the maintainer's, so it is nothing for you to act on — but the folded line
1960
1983
  names it (`…; HOLD (main checkout dirty) persists — …`) for as long as it holds
1961
1984
  dispatch.
1985
+ A live member past its family's threshold folds the same way — it is advice, so
1986
+ nothing for the heartbeat to act on by itself — and the folded line names each
1987
+ such member (`…; CHECK-LIVENESS fix-pr-5 persists — …`) for as long as it stays
1988
+ live past the threshold.
1962
1989
 
1963
1990
  **When you stop on purpose, say why — one command, and it is the last thing
1964
1991
  you owe the next run.** The beat leaves a dated mark on every hold, so a run
@@ -3440,9 +3467,11 @@ there.
3440
3467
  ### Merge bot
3441
3468
 
3442
3469
  Per pass, named `merge-bot-<n>`, never two at once. `ledger.mjs dispatch
3443
- merge-bot` names it before the dispatch call — `n` is 1 + the `merge-bot-`
3444
- entries already in the ledger's `## Dispatched` list, so it restarts at 1 every
3445
- run, a replacement for a dead bot takes the next `n`, and nobody counts. Dispatch
3470
+ merge-bot` names it before the dispatch call — `n` is 1 + the highest
3471
+ `merge-bot-<n>` the session holds, in the ledger's `## Dispatched` list, on a
3472
+ row or in `## Retired`, so it restarts at 1 only when none was carried or
3473
+ retired (a `dead` or `none` rotate, or a fresh start), a replacement for a
3474
+ dead bot takes the next `n`, and nobody counts. Dispatch
3446
3475
  it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
3447
3476
  enough, and it never waits for the finisher's report. Tell it to read
3448
3477
  `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
@@ -4001,6 +4030,7 @@ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
4001
4030
  | Member silent or truncated | Send to ping or resume — same unit of work; see the state machine below |
4002
4031
  | Member idle with work outstanding | Read the PR first, *then* ping. Idle ≠ done |
4003
4032
  | Member **killed** (spend limit, API error, crash) | Confirm it is dead first — a frozen transcript does not establish that; see below — then new member, new name, prompt carries inherited state |
4033
+ | Member **unaccounted** (a live token the tick flags `CHECK-LIVENESS`, or any live token nothing has reported on) | Registry census first: `read history://` once. A row other than `running` → `read agent://<member>` and the artifacts (PR head, worktree, labels), settle the real outcome with the existing vocabulary, and resume a `parked` member with `write agent://<member>` when its work is worth continuing. A `running` row → the mtime discriminator below, two polls: moved means BLOCKED and alive; frozen at both polls **and** no artifact movement → `write proc://<member>/kill`, `ledger.mjs settle <member> killed`, fresh name. Three independent alive-signals — the first poll, the second poll, the artifacts — must all be silent before a kill; the tick settles and kills nothing |
4004
4034
 
4005
4035
  A red PR never silently becomes `ready-to-merge`.
4006
4036
 
@@ -4020,8 +4050,8 @@ moved: **mtimes that moved between the two mean BLOCKED, a live member
4020
4050
  still holding its claim and its worktree, so the killed row above does not
4021
4051
  apply to it; mtimes unchanged at both are the dead signature.** Only the first
4022
4052
  of those two verdicts is conclusive — a member wedged on a call that writes
4023
- nothing freezes its scratch dir too — so settle the dead one on the liveness
4024
- read below, never on the two listings alone. Measured once: a refuter
4053
+ nothing freezes its scratch dir too — so settle the dead one on the Member
4054
+ unaccounted row above, never on the two listings alone. Measured once: a refuter
4025
4055
  wedged forever on `until grep -q` for a marker `node --test` never writes, its
4026
4056
  transcript's record counts unchanged across two polls while its own scratch
4027
4057
  files carried fresh mtimes throughout — alive the entire time it read as dead.
@@ -4058,6 +4088,9 @@ One git-ignored `.fleet/ledger.md` per run, updated at **every** state change vi
4058
4088
  durable thing in the run: it compacts, and a controller that loses the dispatch
4059
4089
  map or the filed list redoes finished work. Two duplicate tickets shipped in one
4060
4090
  run from exactly that.
4091
+ Compaction parks every in-flight member and nothing reports it, so on resume
4092
+ take the registry census first (**Member unaccounted**, in **Failure
4093
+ handling**) before you trust a live token.
4061
4094
 
4062
4095
  **The file lives one run.** Phase 0 rotates it before anything reads it, so
4063
4096
  no exclusion, filing, ruling or drain marker outlives the run that wrote it,
@@ -4088,7 +4121,8 @@ live count from it, so nobody states one. Write neither by hand:
4088
4121
  mapping), a finisher's and a merge bot's are their own definitions, a
4089
4122
  review fix-applier's is `null`, and a conflict-hold fix-applier's is
4090
4123
  `fleet-implementer-slow-high`: its own section says how it is dispatched. It
4091
- refuses a name this run already used (a replacement takes `-b`, `-c` …), a
4124
+ refuses a name this session already used — on the ledger or in its
4125
+ `## Retired` — and names the replacement (`-b`, `-c` …), a
4092
4126
  second live member on one ticket or PR, any implementer once the run is
4093
4127
  draining, an implementer whose row's `tier=` names no single definition
4094
4128
  or one with no file under `agents/`, and a fix-applier on a ledger the tick
@@ -4120,7 +4154,8 @@ live count from it, so nobody states one. Write neither by hand:
4120
4154
  the file as-is to `ledger.<UTC YYYY-MM-DDTHHMMSSZ>.md` beside it under the
4121
4155
  same `<file>.lock`, and the next write starts the empty skeleton — unless
4122
4156
  the previous run was this session's own, when it first writes the rows and
4123
- `## Dispatched` entries still live into a new ledger (phase 0 says which). Refused
4157
+ `## Dispatched` entries still live into a new ledger, and every other
4158
+ settled name into its `## Retired` (phase 0 says which). Refused
4124
4159
  while the recorded controller is alive and not this run's ancestor, ledger
4125
4160
  or none — or, with no record and a ledger to move, while the heartbeat mark
4126
4161
  is still beating — or when the archive name already exists, the process
@@ -4168,7 +4203,9 @@ maps to the PR — its settled `impl-<N>=PR#<M>` token, else its first `PR#`
4168
4203
  mention, else its key — in ledger order. Every `reviewed=` answers the nearest
4169
4204
  earlier launch that is neither answered nor `=failed`. A launch identity (a
4170
4205
  workflow's runId, or a runner's name whichever of member or fallback launched
4171
- it, `=failed` aside) appears once. No launch appears
4206
+ it, `=failed` aside) appears once, and no launch takes a runner name the
4207
+ ledger's `## Retired` holds — an earlier run of this session launched it —
4208
+ naming the next free reviewer name instead. No launch appears
4172
4209
  while an earlier one is open — unanswered and not `=failed`. Every
4173
4210
  `review=`/`reviewed=` parses. `row` holds the rest: a launch open before the
4174
4211
  write is still on one of the PR's rows after it, `=failed` allowed, and a