@feigi/fleet-ctl 3.35.7 → 3.35.8

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.35.7",
3
+ "version": "3.35.8",
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": {
@@ -139,6 +139,9 @@ export function rowNums(text) {
139
139
  export const REVIEW = /^review=(?<kind>wf|member|fallback):(?<name>[^=\s]+)(?<failed>=failed)?$/;
140
140
  export const REVIEWED = /^reviewed=([0-9a-fA-F]{7,40}):(\d+)\/(\d+)\/(\d+):(run-[A-Za-z0-9]{8})$/;
141
141
 
142
+ // The stream a row belongs to: its PR, else its key.
143
+ const streamId = (text) => rowNums(text).pr ?? text.split(/\s/)[0];
144
+
142
145
  // Every PR's token stream: every row that maps to it under rowNums(), in
143
146
  // ledger row order, its tokens run end to end — the order fleet-tick.mjs's
144
147
  // fold reads a PR's review record in. A row naming no PR and keyed by no
@@ -146,7 +149,7 @@ export const REVIEWED = /^reviewed=([0-9a-fA-F]{7,40}):(\d+)\/(\d+)\/(\d+):(run-
146
149
  function streams(rows) {
147
150
  const out = new Map();
148
151
  for (const text of rows) {
149
- const id = rowNums(text).pr ?? text.split(/\s/)[0];
152
+ const id = streamId(text);
150
153
  if (!out.has(id)) out.set(id, []);
151
154
  out.get(id).push(...text.split(/\s+/).filter(Boolean));
152
155
  }
@@ -297,6 +300,82 @@ export function rowWriteRefusal(before, after, oldLine, line) {
297
300
  return null;
298
301
  }
299
302
 
303
+ /**
304
+ * What a ledger still holds live, and what must travel with it. `tokens` is
305
+ * every unsettled member token and every open review launch, once each, in
306
+ * ledger order, as `{name, token, row}` — the member or runner name (a
307
+ * workflow launch's runId), the token as written, and the key of the first
308
+ * row carrying it, null for a member `## Dispatched` alone names. `rows` is
309
+ * the indices of every row of a stream — the rows one PR's record spans, or
310
+ * a row's own key when it names none — in which any row carries one of those
311
+ * tokens: a stream's rows are read together, so a live row carried without
312
+ * its siblings would lose the PR's review record and the settled copies that
313
+ * keep a bare token from reading live again. `dispatched` is every
314
+ * `## Dispatched` entry whose member is unsettled, plus every settled entry
315
+ * naming a member a kept row carries, for the same reason. A member is
316
+ * settled by a settled copy in `## Dispatched` or on a row, except that a
317
+ * PR-bound member's settled copy counts only on its own PR's row — the reading
318
+ * fleet-tick.mjs folds liveness by, so nothing that fold calls live is left
319
+ * out. A launch is open while unanswered and not `=failed`, paired across its
320
+ * PR's rows as `rowWriteRefusal` pairs them. Malformed tokens are the caller's
321
+ * to have refused: one here is read as nothing.
322
+ */
323
+ export function liveOnLedger(rows, dispatched) {
324
+ const settled = new Set();
325
+ for (const e of dispatched) {
326
+ const t = parseToken(e);
327
+ if (t !== null && t.error === null && t.outcome !== null) settled.add(t.name);
328
+ }
329
+ for (const text of rows) {
330
+ const { pr } = rowNums(text);
331
+ for (const t of memberTokens(text)) {
332
+ if (t.error === null && t.outcome !== null && (t.bound !== "pr" || t.number === pr)) settled.add(t.name);
333
+ }
334
+ }
335
+ const live = (t) => t !== null && t.error === null && t.outcome === null && !settled.has(t.name);
336
+ const open = new Map();
337
+ for (const [id, tokens] of streams(rows)) {
338
+ const r = readReviews(tokens);
339
+ open.set(id, r.launches.filter((l) => r.open.includes(l.id)));
340
+ }
341
+ const out = { rows: [], dispatched: [], tokens: [] };
342
+ const seen = new Set();
343
+ const add = (name, token, row) => {
344
+ if (seen.has(token)) return;
345
+ seen.add(token);
346
+ out.tokens.push({ name, token, row });
347
+ };
348
+ const streamOf = rows.map(streamId);
349
+ const liveStreams = new Set();
350
+ rows.forEach((text, i) => {
351
+ const key = text.split(/\s/)[0];
352
+ const words = text.split(/\s+/).filter(Boolean);
353
+ const members = memberTokens(text).filter(live);
354
+ const launches = (open.get(streamOf[i]) ?? []).filter((l) => words.includes(l.id));
355
+ if (members.length === 0 && launches.length === 0) return;
356
+ liveStreams.add(streamOf[i]);
357
+ for (const t of members) add(t.name, t.name, key);
358
+ for (const l of launches) add(l.name, l.id, key);
359
+ });
360
+ const carried = new Set();
361
+ rows.forEach((text, i) => {
362
+ if (!liveStreams.has(streamOf[i])) return;
363
+ out.rows.push(i);
364
+ for (const t of memberTokens(text)) if (t.error === null) carried.add(t.name);
365
+ });
366
+ for (const e of dispatched) {
367
+ const t = parseToken(e);
368
+ if (t === null || t.error !== null) continue;
369
+ if (live(t)) {
370
+ out.dispatched.push(e);
371
+ add(t.name, t.name, null);
372
+ } else if (carried.has(t.name)) {
373
+ out.dispatched.push(e);
374
+ }
375
+ }
376
+ return out;
377
+ }
378
+
300
379
  // A ticket row is `#N <text>`; it is an Exclusion when `excluded` is the
301
380
  // text's first word — `impl-N · … excluded …` is a row about something else.
302
381
  // `#N excluded · behind-pr:#M` / `behind-issue:#M`: `#M` is an issue or PR
@@ -340,11 +419,14 @@ export function unescapeText(s) {
340
419
  return s.replace(/\\(\\|n)/g, (_, c) => (c === "n" ? "\n" : "\\"));
341
420
  }
342
421
 
343
- /** The name the next merge bot takes: 1 + the `merge-bot-` entries in
344
- * `## Dispatched`, settled ones included. One ledger per run, so n restarts
345
- * at 1 with every run. */
422
+ /** The name the next merge bot takes: 1 + the highest `merge-bot-<n>` in
423
+ * `## Dispatched`, settled ones included — the highest, not the count, since
424
+ * a rotate that carries a live bot forward carries a settled predecessor
425
+ * only when a carried row names it. n restarts at 1 with every run that
426
+ * carries no bot. */
346
427
  export function nextMergeBot(dispatched) {
347
- return `merge-bot-${dispatched.map(parseToken).filter((t) => t?.family === "merge-bot").length + 1}`;
428
+ const ns = dispatched.map(parseToken).filter((t) => t?.family === "merge-bot").map((t) => t.number);
429
+ return `merge-bot-${Math.max(0, ...ns) + 1}`;
348
430
  }
349
431
 
350
432
  // An implementer cell is `<role>-<level>` — an omp role and a thinking
@@ -15,9 +15,11 @@
15
15
  // `<member>=<outcome>` in both places (an implementer's settle to `PR#M` also
16
16
  // folds the PR's own `#M` row into its ticket's), and `drain` writes the
17
17
  // one marker that stops supply. The token grammar is
18
- // ledger-grammar.mjs's. `## Dispatched` gains an entry per dispatch and never
19
- // loses or reorders one — settling annotates an entry in place — which is what
20
- // lets `merge-bot-<n>` be counted from it.
18
+ // ledger-grammar.mjs's. Within a run `## Dispatched` gains an entry per
19
+ // dispatch and never loses or reorders one — settling annotates an entry in
20
+ // place — which is what lets `merge-bot-<n>` be numbered from it; a rotate
21
+ // that carries a run's live entries forward carries a settled one only for a
22
+ // member a carried row names.
21
23
  //
22
24
  // Writer policy: the controller owns run
23
25
  // state (`row`/`settle`/`dispatch`/`drain`/`ruled`/`rotate`); filers append
@@ -35,7 +37,7 @@ import { fileURLToPath } from "node:url";
35
37
  import { spawnSync, execFileSync } from "node:child_process";
36
38
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
37
39
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
38
- import { parseMember, parseToken, memberTokens, nextMergeBot, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
40
+ import { parseMember, parseToken, memberTokens, nextMergeBot, liveOnLedger, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
39
41
  import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
40
42
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
41
43
  import { isDead, processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -434,6 +436,20 @@ function refuseStrayInId(value, what) {
434
436
  // report what the parse saw rather than what a later stat() guesses.
435
437
  let ledgerParsed = false;
436
438
 
439
+ // A section's entries, unescaped, in file order — none when the header is
440
+ // absent. Lenient by design: it refuses nothing, so rotate reads a ledger
441
+ // load() refuses through the same slicing.
442
+ function sectionOf(text, name) {
443
+ const m = headerRe(name).exec(text);
444
+ if (!m) return [];
445
+ const start = m.index + m[1].length + name.length;
446
+ const after = text.slice(start);
447
+ const end = after.search(/\n## /);
448
+ return (end === -1 ? after : after.slice(0, end))
449
+ .split("\n").map((l) => l.trim()).filter((l) => l.startsWith("- "))
450
+ .map((l) => unescapeText(l.slice(2)));
451
+ }
452
+
437
453
  function load() {
438
454
  if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], drain: null };
439
455
  let text;
@@ -442,16 +458,7 @@ function load() {
442
458
  } catch (e) {
443
459
  die(`cannot read ${file}: ${e.message}`);
444
460
  }
445
- const section = (name) => {
446
- const m = headerRe(name).exec(text);
447
- if (!m) return [];
448
- const start = m.index + m[1].length + name.length;
449
- const after = text.slice(start);
450
- const end = after.search(/\n## /);
451
- return (end === -1 ? after : after.slice(0, end))
452
- .split("\n").map((l) => l.trim()).filter((l) => l.startsWith("- "))
453
- .map((l) => unescapeText(l.slice(2)));
454
- };
461
+ const section = (name) => sectionOf(text, name);
455
462
  // Set here, past the read and the early return, so it can only be true of a
456
463
  // file this function actually opened and recognised as a ledger.
457
464
  ledgerParsed = headerRe(FILED).test(text);
@@ -734,9 +741,9 @@ if (requireFile && !existsSync(file)) die(`--require-file given but ledger file
734
741
 
735
742
  const WRITE_COMMANDS = new Set(["row", "filed", "ruled", "dispatch", "settle", "drain", "rotate"]);
736
743
  if (WRITE_COMMANDS.has(cmd)) await acquireLock();
737
- // `rotate` moves the file whole and never parses it: a ledger load() would
738
- // refuse is still the previous run's record, and archiving it as-is is the
739
- // whole job.
744
+ // `rotate` never load()s: a ledger load() would refuse is still the previous
745
+ // run's record, and it is archived as-is — and read line by line when it
746
+ // carries live members forward, see carryOf().
740
747
  const data = cmd === "rotate" ? null : load();
741
748
 
742
749
  // The payload subcommands end by falling out of this chain, never by calling
@@ -1493,12 +1500,26 @@ function runCheck() {
1493
1500
  // ── rotate ───────────────────────────────────────────────────────────────────
1494
1501
  //
1495
1502
  // One ledger per run. Phase 0 of every run moves the previous run's file aside
1496
- // before anything reads it, so no row, exclusion, filing, ruling or drain
1497
- // marker outlives the run that wrote it: the next write subcommand finds no
1498
- // file and starts the empty skeleton, exactly as on a first run. The archive
1499
- // is the file itself — hard-linked to its stamped name, then unlinked — so its
1500
- // bytes are untouched, and the link refuses atomically when that name is
1501
- // already taken rather than overwriting an older archive.
1503
+ // before anything reads it, so no exclusion, filing, ruling or drain marker
1504
+ // outlives the run that wrote it. The archive is the file itself —
1505
+ // hard-linked to its stamped name, then unlinked or, when a successor is
1506
+ // carried, replaced by it — so its bytes are untouched, and the link refuses
1507
+ // atomically when that name is already taken rather than overwriting an older
1508
+ // archive.
1509
+ //
1510
+ // What follows depends on the verdict below. After a `dead` or `none` one
1511
+ // nothing is carried: the next write subcommand finds no file and starts the
1512
+ // empty skeleton, exactly as on a first run. After an `ancestor` one — this
1513
+ // session's own earlier run, whose members run inside the omp process that
1514
+ // is still this run's — rotate writes a new ledger holding what is still
1515
+ // live in the archive: every row of a stream that holds an unsettled member
1516
+ // token or an open review launch, whole, and every unsettled `## Dispatched`
1517
+ // entry plus the settled ones naming a carried member (see carryOf()). The
1518
+ // members those name may still be running, and dropping their tokens would
1519
+ // let the next tick dispatch onto their work and leave their
1520
+ // results nothing to settle. Phase 0 then reconciles each carried token
1521
+ // against the session's job list; rotate cannot, since that list is the
1522
+ // controller's to read and no script's.
1502
1523
  //
1503
1524
  // Under the write lock like every other write subcommand, so a concurrent
1504
1525
  // writer either lands before the move (in the archive, whole) or after it (in
@@ -1560,6 +1581,19 @@ function runRotate() {
1560
1581
  if (prior === "none" && exists && assessBeat({ beat, ticked, now: Date.now() }).kind === "beating") {
1561
1582
  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()}`);
1562
1583
  }
1584
+ // Read before anything moves: a ledger whose live tokens cannot be read is
1585
+ // refused with nothing moved, never archived with those tokens dropped.
1586
+ let carry = { rows: [], dispatched: [], skipped: [] };
1587
+ if (prior === "ancestor" && exists) {
1588
+ let text;
1589
+ try {
1590
+ text = readFileSync(file, "utf8");
1591
+ } catch (e) {
1592
+ die(`refusing to rotate ${file}: cannot read it to carry this session's live members forward: ${e.message}`);
1593
+ }
1594
+ carry = carryOf(text);
1595
+ }
1596
+ const carrying = carry.rows.length > 0 || carry.dispatched.length > 0;
1563
1597
  let archive = null;
1564
1598
  if (exists) {
1565
1599
  const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
@@ -1569,15 +1603,33 @@ function runRotate() {
1569
1603
  } catch (e) {
1570
1604
  die(e.code === "EEXIST" ? `refusing to rotate ${file}: ${archive} already exists` : `cannot rotate ${file} to ${archive}: ${e.message}`);
1571
1605
  }
1572
- try {
1573
- unlinkSync(file);
1574
- } catch (e) {
1575
- die(`archived ${file} as ${archive} but could not remove it: ${e.message} — remove it by hand before the next write`);
1606
+ // Carrying, the new ledger is renamed over the old file by save(), so the
1607
+ // file is never absent while its live tokens exist only in memory: a write
1608
+ // that fails leaves the ledger where it was, the archive a second name for
1609
+ // the same bytes, and a retry carries from the unmoved file. Carrying
1610
+ // nothing, the file has no successor to wait for.
1611
+ if (!carrying) {
1612
+ try {
1613
+ unlinkSync(file);
1614
+ } catch (e) {
1615
+ die(`archived ${file} as ${archive} but could not remove it: ${e.message} — remove it by hand before the next write`);
1616
+ }
1576
1617
  }
1577
- console.error(` rotated ${file} -> ${archive}`);
1578
1618
  } else {
1579
1619
  console.error(` nothing to rotate: ${file} does not exist`);
1580
1620
  }
1621
+ // Nothing to carry writes nothing, so the next write starts the skeleton
1622
+ // exactly as after any other verdict.
1623
+ if (carrying) {
1624
+ save({ rows: carry.rows, dispatched: carry.dispatched, filed: [], ruled: [], drain: null });
1625
+ }
1626
+ if (archive !== null) console.error(` rotated ${file} -> ${archive}`);
1627
+ for (const { line, why } of carry.skipped) {
1628
+ console.error(` skipped unparseable line '${line}' — not carried: ${why}`);
1629
+ }
1630
+ if (carrying) {
1631
+ console.error(` carried ${carry.rows.length} row(s) and ${carry.dispatched.length} ## Dispatched entr${carry.dispatched.length === 1 ? "y" : "ies"} from ${archive}`);
1632
+ }
1581
1633
  // Re-read rather than reuse the read above: the heartbeat file has other
1582
1634
  // writers, and a patch built from an older view would undo what they wrote
1583
1635
  // since.
@@ -1585,7 +1637,47 @@ function runRotate() {
1585
1637
  if (!writeState(beatFile, NAME, readState(beatFile, NAME), { controller: record })) {
1586
1638
  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`);
1587
1639
  }
1588
- console.log(JSON.stringify({ rotated: archive !== null, archive }));
1640
+ console.log(JSON.stringify({
1641
+ rotated: archive !== null, archive,
1642
+ carried: { rows: carry.rows, dispatched: carry.dispatched },
1643
+ skipped: carry.skipped.map((s) => s.line),
1644
+ }));
1645
+ }
1646
+
1647
+ // What an `ancestor` rotate carries out of the archived text, read line by
1648
+ // line so one bad line costs only itself: the whole point is to keep live
1649
+ // members' tokens, and a ledger load() refuses (a second drain marker, say)
1650
+ // still holds them. A row is read the way the tick reads it — a row the tick
1651
+ // would refuse is skipped rather than carried into a ledger the next tick
1652
+ // refuses whole — and a `## Dispatched` entry must be a well-formed member
1653
+ // token. Every skipped line is returned with its reason; a skipped row's
1654
+ // member can still be carried by its `## Dispatched` entry, which keeps its
1655
+ // name taken. Of what parses, liveOnLedger() picks what travels: every row
1656
+ // of a stream that holds a live token, whole, so a carried row's settled
1657
+ // tokens, `reviewed=` and every other record on it come along, and its
1658
+ // siblings' with them, and the tick's per-PR reading of the PR is unchanged;
1659
+ // and the `## Dispatched` entries, settled ones among them, that keep a
1660
+ // carried member from reading live again.
1661
+ function carryOf(text) {
1662
+ const skipped = [];
1663
+ const rows = sectionOf(text, ROWS).filter((r) => {
1664
+ try {
1665
+ deriveRun({ rows: [r], dispatched: [], drain: null }, []);
1666
+ return true;
1667
+ } catch (e) {
1668
+ if (!(e instanceof LedgerError)) throw e;
1669
+ skipped.push({ line: r, why: e.message });
1670
+ return false;
1671
+ }
1672
+ });
1673
+ const dispatched = sectionOf(text, DISPATCHED).filter((e) => {
1674
+ const t = parseToken(e);
1675
+ if (t !== null && t.error === null) return true;
1676
+ skipped.push({ line: e, why: t === null ? "not a member token" : `${t.name}: ${t.error}` });
1677
+ return false;
1678
+ });
1679
+ const live = liveOnLedger(rows, dispatched);
1680
+ return { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched, skipped };
1589
1681
  }
1590
1682
 
1591
1683
  // ── dispatch / settle ────────────────────────────────────────────────────────
@@ -4,12 +4,12 @@
4
4
  // classifies; it acts on nothing — no dispatch, no label, no release. The
5
5
  // controller dispatches off its answer.
6
6
  //
7
- // A claim's label and worktree exist before its first push. Rotation carries
8
- // no ledger row forward, the candidate scan excludes `in-progress`, and the
9
- // in-flight check reads the worktree as taken — so a claim a dead run left
10
- // without a PR is held by nobody until this step names it. One with an open
11
- // PR is not stranded: phase 0's fold-in queues every open PR, so it is never
12
- // listed here.
7
+ // A claim's label and worktree exist before its first push. Rotation after a
8
+ // dead or unknown run carries no ledger row forward, the candidate scan
9
+ // excludes `in-progress`, and the in-flight check reads the worktree as
10
+ // taken — so a claim a dead run left without a PR is held by nobody until
11
+ // this step names it. One with an open PR is not stranded: phase 0's fold-in
12
+ // queues every open PR, so it is never listed here.
13
13
  //
14
14
  // THE VERDICT is `prior` in the controller record, the one `ledger.mjs
15
15
  // rotate` reached on the record it replaced — never a fresh judgement of the
@@ -19,8 +19,10 @@
19
19
  // dead every open in-progress issue with no open PR: `resume` when
20
20
  // exactly one worktree for it sits under this checkout's
21
21
  // `.worktrees/` and its directory is there, `report` otherwise
22
- // ancestor this session's earlier run: nothing listed — its members may
23
- // still be live, and the in-run liveness check covers them
22
+ // ancestor this session's earlier run: no claim listed — its members may
23
+ // still be live, and rotate carried their tokens forward;
24
+ // `carried` lists them instead, for the controller to reconcile
25
+ // against the session's job list
24
26
  // none nothing proves the previous run dead: every claim `report`
25
27
  //
26
28
  // "An open PR about the issue" is the in-flight check's reading, its branch rule
@@ -33,18 +35,27 @@
33
35
  // the number as a whole segment, so a worktree named for issue 129 is never
34
36
  // issue 12's.
35
37
  //
36
- // Prints `{prior, claims: [{n, t, action, worktree, branch, why}]}` on stdout.
38
+ // Prints `{prior, claims: [{n, t, action, worktree, branch, why}], carried:
39
+ // [{name, token, row}]}` on stdout. `carried` is empty unless prior is
40
+ // `ancestor`; each entry is the member or runner name (a workflow launch's
41
+ // runId), the token as the ledger holds it, and the key of the first row
42
+ // carrying it — null for a member only `## Dispatched` names. It is every
43
+ // live token on the ledger: at phase 0 this run has dispatched nothing yet,
44
+ // so each is one rotate carried.
37
45
  // Exit 0 answered; 2 a list that did not answer — a gh or git failure, a
38
- // list at its cap, which may hold more than it showed, or a worktree path
39
- // whose presence cannot be told. Never read 2 as nothing stranded.
46
+ // list at its cap, which may hold more than it showed, a worktree path
47
+ // whose presence cannot be told, or a ledger that cannot be read. Never read
48
+ // 2 as nothing stranded.
40
49
 
41
50
  import { spawnSync } from "node:child_process";
42
51
  import { realpathSync, statSync } from "node:fs";
43
52
  import { basename, dirname, join } from "node:path";
53
+ import { fileURLToPath } from "node:url";
44
54
  import { makeDie, writeAll } from "./arg.mjs";
45
55
  import { gitEnv } from "./git-env.mjs";
46
56
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
47
57
  import { readState, stateFileIn } from "./fleet-state.mjs";
58
+ import { liveOnLedger } from "./ledger-grammar.mjs";
48
59
 
49
60
  const NAME = "stranded";
50
61
  const die = makeDie(NAME);
@@ -149,8 +160,8 @@ function main() {
149
160
  const { controller } = readState(stateFileIn(fleetDir), NAME);
150
161
  const prior = controller?.prior ?? "none";
151
162
  if (prior === "ancestor") {
152
- log(`${NAME}: the previous run is this session's own earlier run — its claims are left alone`);
153
- console.log(JSON.stringify({ prior, claims: [] }));
163
+ log(`${NAME}: the previous run is this session's own earlier run — its claims are left alone, and the live tokens rotate carried are listed`);
164
+ console.log(JSON.stringify({ prior, claims: [], carried: carriedTokens(join(fleetDir, "ledger.md")) }));
154
165
  return;
155
166
  }
156
167
 
@@ -206,7 +217,26 @@ function main() {
206
217
  claims.push({ n: issue.number, t: issue.title, action, worktree: one?.path ?? null, branch: one?.branch ?? null, why });
207
218
  log(` #${issue.number} ${action} — ${why}`);
208
219
  }
209
- console.log(JSON.stringify({ prior, claims }));
220
+ console.log(JSON.stringify({ prior, claims, carried: [] }));
221
+ }
222
+
223
+ // Every live token on the ledger, read through `ledger.mjs read` so the
224
+ // ledger keeps one parser. A read that fails is a list that did not answer.
225
+ function carriedTokens(file) {
226
+ const script = join(dirname(fileURLToPath(import.meta.url)), "ledger.mjs");
227
+ // `--file` names the ledger outright, so the read resolves no workspace
228
+ // and runs no git.
229
+ const r = spawnSync(process.execPath, [script, "--file", file, "read"], { encoding: "utf8", maxBuffer: MAX_BUFFER });
230
+ if (r.error || r.status !== 0) die(`ledger.mjs read failed (${how(r)}) — which tokens rotate carried is unknown`);
231
+ let d;
232
+ try {
233
+ d = JSON.parse(r.stdout);
234
+ } catch (e) {
235
+ die(`could not parse ledger.mjs read output: ${e.message}`);
236
+ }
237
+ const strings = (xs) => Array.isArray(xs) && xs.every((x) => typeof x === "string");
238
+ if (!d || !strings(d.rows) || !strings(d.dispatched)) die("ledger.mjs read returned no {rows, dispatched}");
239
+ return liveOnLedger(d.rows, d.dispatched).tokens;
210
240
  }
211
241
 
212
242
  main();
@@ -374,18 +374,31 @@ phase, or in any later one, asks the maintainer which tickets to take.
374
374
  every run, whatever way the previous one ended.** One ledger per run:
375
375
  `~/.fleet/bin/fleet-run ledger.mjs rotate` moves the previous run's
376
376
  `.fleet/ledger.md` byte-for-byte to `.fleet/ledger.<UTC
377
- YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind, so this run's first write
378
- starts the empty skeleton. Nothing is carried forward — no row, exclusion,
379
- `## Filed` or `## Ruled` entry — so an unchecked `impl-` row a prior run
380
- left behind can no longer hold this run's tick. What an unclean end left in
377
+ YYYY-MM-DDTHHMMSSZ>.md` and leaves none behind. What it carries forward
378
+ turns on the verdict it reaches below. After `dead` or `none` nothing is
379
+ carried — no row, exclusion, `## Filed` or `## Ruled` entry — so this
380
+ run's first write starts the empty skeleton, and an unchecked `impl-` row
381
+ a prior run left behind can no longer hold this run's tick: a dead
382
+ controller took its in-process members with it. After `ancestor` — this
383
+ session's own earlier run, whose members run inside the same omp process
384
+ and may still be live — it writes a new ledger holding every row of a
385
+ stream (one PR's rows) in which a row carries an unsettled member token
386
+ or an open `review=` launch, whole and with every other token on it, plus
387
+ every unsettled `## Dispatched` entry and the settled entry of each
388
+ member a carried row names; exclusions, `## Filed`, `## Ruled` and the
389
+ drain marker are never carried.
390
+ A line it cannot parse is skipped with a warning naming it, and the
391
+ rotation still succeeds. It prints `{rotated, archive, carried: {rows,
392
+ dispatched}, skipped}`. The carried tokens keep the tick from dispatching
393
+ onto those members' work, keep their names taken, and give their late
394
+ results a token to settle; the stranded-claim step below reconciles them.
395
+ What an unclean end left in
381
396
  flight comes back through the ordinary per-run path: open PRs through the
382
397
  fold-in below, `behind-pr:`/`behind-issue:` exclusions through phase 1's
383
398
  collision and sequence checks, and a claim a dead run left without a PR
384
399
  through the stranded-claim step below — resumed by a new member under a
385
400
  new name when its worktree is in this checkout, reported to the
386
- maintainer otherwise. A claim this session's own earlier run left stays
387
- with it: its member may still be live, and the Member-killed row's check
388
- covers it. An exclusion that expires with the run that wrote
401
+ maintainer otherwise. An exclusion that expires with the run that wrote
389
402
  it (`deferred-to-session-end` and its like) must be restated if it still
390
403
  holds. **The guard is the
391
404
  controller record**, `controller` in `.fleet/heartbeat.json`: the omp
@@ -476,8 +489,12 @@ phase, or in any later one, asks the maintainer which tickets to take.
476
489
  that run's own metrics — it is reviewable work no member otherwise picks up,
477
490
  because the Shortlist holds ISSUES and nothing looks at inherited PRs. Queue
478
491
  each for review exactly as ticket work: same review workflow, same
479
- fix-applier, same finisher. Measured 2026-09-03 — a prior run's ticket PR
480
- arrived this way and its review found a defect its own PR body called
492
+ fix-applier, same finisher. **Skip a PR a row rotate carried already
493
+ holds** — its `#<pr>` key, or the PR of its `impl-<N>=PR#<pr>` token: that
494
+ row already queues it, and a `ledger.mjs row` write replaces the whole
495
+ line, wiping the live tokens carried on it. Measured 2026-09-03 — a prior
496
+ run's ticket PR arrived this way and its review found a defect its own PR
497
+ body called
481
498
  unreviewed, and a metrics PR's review then caught two metrics rows the
482
499
  controller had missed in its own close-out, so no PR is exempt from being
483
500
  wrong. Reviewing them next run is also what stops one pinning
@@ -486,20 +503,39 @@ phase, or in any later one, asks the maintainer which tickets to take.
486
503
 
487
504
  **Resume the claims a dead run left without a PR — after the fold-in,
488
505
  before shortlisting.** A claim's label and worktree exist before its first
489
- push, and rotation carries no row forward, the candidate scan excludes
490
- `in-progress`, and the in-flight check reads the worktree as taken — so a
506
+ push, and rotation after a dead run carries no row forward, the candidate
507
+ scan excludes `in-progress`, and the in-flight check reads the worktree as
508
+ taken — so a
491
509
  claim the previous run left without a PR is held by nobody until this step
492
510
  names it. `~/.fleet/bin/fleet-run stranded.mjs` lists and classifies; you
493
511
  dispatch. It reads the `prior` rotate just recorded, never the record
494
512
  itself, which names this run's own live controller, and prints
495
- `{prior, claims: [{n, t, action, worktree, branch, why}]}`:
513
+ `{prior, claims: [{n, t, action, worktree, branch, why}], carried: [{name,
514
+ token, row}]}`:
496
515
 
497
516
  - `prior: dead` — every open `in-progress` issue with no open PR (one with
498
517
  an open PR is the fold-in's): `resume` when exactly one worktree for it
499
518
  sits under this checkout's `.worktrees/`, `report` otherwise.
500
- - `prior: ancestor` — this session's own earlier run: nothing is listed.
501
- Its members may still be live, and the Member-killed row's check covers
502
- them.
519
+ - `prior: ancestor` — this session's own earlier run: no claim is listed.
520
+ `carried` lists every live token rotate carried — its member or runner
521
+ `name` (a `review=wf:` launch's runId), the `token` as the ledger holds
522
+ it, and the `row` carrying it, null for a member only `## Dispatched`
523
+ names. Reconcile them before shortlisting: read `proc://` once, find
524
+ each `name` among this session's jobs, and act on its state.
525
+ `running` → keep the token. `completed` or `failed` → record its
526
+ result from `agent://<id>` as the **Record, then tick** table records
527
+ that member's report; an output you cannot read is a death the
528
+ Member-killed row confirms. `cancelled` → record it dead. Absent, or a
529
+ state you cannot read → keep the token live and let the Member-killed
530
+ row clear it: a token nothing confirms dead counts as live. Recording a
531
+ death has two forms, here and on the Member-killed row alike. An
532
+ `impl-`, `fix-pr-`, `finisher-pr-` or `merge-bot-` member is settled:
533
+ `ledger.mjs settle <name> killed`. A reviewer is no member `settle`
534
+ takes — `settle review-pr-<n> killed` exits 2 — so its launch is
535
+ settled `=failed` where it stands: a `ledger.mjs row` rewrite of its row
536
+ that turns `review=member:<name>` into `review=member:<name>=failed`
537
+ (`fallback:` and `wf:` launches alike), after which the tick owes the PR
538
+ a review again under the next free reviewer name.
503
539
  - `prior: none` — no record proves the previous run dead (no record yet, or
504
540
  no `omp` process found above the rotation): every claim is `report`, and
505
541
  nothing is resumed.
@@ -517,8 +553,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
517
553
  `claim-ticket.sh`: the claim already stands. A `report` goes to the
518
554
  maintainer as `#<N> — <why>` and nothing else: no dispatch, no label change,
519
555
  no release. Exit 2 is a list that did not answer — a `gh` or `git`
520
- failure, a list at its cap, or a worktree whose presence cannot be told —
521
- and is never nothing stranded.
556
+ failure, a list at its cap, a worktree whose presence cannot be told, or,
557
+ after `ancestor`, a ledger that cannot be read — and is never nothing
558
+ stranded.
522
559
 
523
560
  1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
524
561
  `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
@@ -1156,6 +1193,18 @@ or `released`, and exit 2 naming the wrong session for any other. Clear a
1156
1193
  mismatch by fixing the definition or the dispatch and dispatching the
1157
1194
  replacement at the right tier.
1158
1195
 
1196
+ **After `/resume`, a carried implementer can hold the whole tick.** A live
1197
+ implementer rotate carried forward with no verdict on its row is unchecked,
1198
+ and once this session has been reopened with `/resume` its transcript sits
1199
+ under the earlier session's directory: the check given this run's `session`
1200
+ finds no `<member>.jsonl` and exits 2, writing nothing. `HOLD (tier unchecked
1201
+ impl-<N>)` then stops the whole tick, not only that member's ticket. It
1202
+ clears once the member settles: one settled `killed` or `released` gets
1203
+ `tier-unverifiable=` from the same check, and one settled any other way ran,
1204
+ so pass the directory that dispatched it, as above. Until it settles,
1205
+ follow the carried token's reconciliation in phase 0: `proc://` reads
1206
+ `running` → wait; dead → the Member-killed row.
1207
+
1159
1208
  **Run the check right after the dispatch, and never reinstall the plugin or
1160
1209
  change `modelRoles` while any member is unchecked.** The check reads the
1161
1210
  installed definition and the live `modelRoles` at check time, not at
@@ -3975,8 +4024,11 @@ map or the filed list redoes finished work. Two duplicate tickets shipped in one
3975
4024
  run from exactly that.
3976
4025
 
3977
4026
  **The file lives one run.** Phase 0 rotates it before anything reads it, so
3978
- no row, exclusion, filing, ruling or drain marker outlives the run that
3979
- wrote it. Never rotate mid-run: it is phase 0's step alone.
4027
+ no exclusion, filing, ruling or drain marker outlives the run that wrote it,
4028
+ and no row does either — except, when the previous run was this session's
4029
+ own, a row still carrying a live token, which rotate carries forward with
4030
+ its live `## Dispatched` entries (phase 0). Never rotate mid-run: it is
4031
+ phase 0's step alone.
3980
4032
 
3981
4033
  One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`):
3982
4034
 
@@ -4023,7 +4075,9 @@ live count from it, so nobody states one. Write neither by hand:
4023
4075
  ledger, so the next run's rotation retires it with everything else.
4024
4076
  - **`ledger.mjs rotate`** — phase 0's first ledger write, every run: moves
4025
4077
  the file as-is to `ledger.<UTC YYYY-MM-DDTHHMMSSZ>.md` beside it under the
4026
- same `<file>.lock`, and the next write starts the empty skeleton. Refused
4078
+ same `<file>.lock`, and the next write starts the empty skeleton — unless
4079
+ the previous run was this session's own, when it first writes the rows and
4080
+ `## Dispatched` entries still live into a new ledger (phase 0 says which). Refused
4027
4081
  while the recorded controller is alive and not this run's ancestor, ledger
4028
4082
  or none — or, with no record and a ledger to move, while the heartbeat mark
4029
4083
  is still beating — or when the archive name already exists, the process