@feigi/fleet-ctl 3.30.34 → 3.31.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.30.34",
3
+ "version": "3.31.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": {
package/scripts/board.mjs CHANGED
@@ -47,7 +47,10 @@ import { mergedReadPrs } from "./compute-board.mjs";
47
47
  // file's own resolveCockpitInstance(), not from statePath(): the workspace is
48
48
  // already resolved once per launch here, with the `canonicalise` opt-in only
49
49
  // this caller takes, and a second resolution could answer differently.
50
- import { readState, stateFileIn } from "./fleet-state.mjs";
50
+ // It also reads the controller record beside the mark, and the process table
51
+ // through stallOwner(), to name whose stall a stopped beat is; the record's
52
+ // writer is `ledger.mjs rotate`, and the cockpit never writes it either.
53
+ import { readState, stateFileIn, assessBeat, isStalled, stallOwner } from "./fleet-state.mjs";
51
54
  import { fileURLToPath } from "node:url";
52
55
  import { isCLI } from "./is-cli.mjs";
53
56
  import { dirname, join, basename } from "node:path";
@@ -1223,9 +1226,14 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
1223
1226
  const priorState = stateFile ? readState(stateFile, NAME) : null;
1224
1227
  const beat = priorState?.beat ?? null;
1225
1228
  const ticked = priorState?.ticked ?? null;
1226
- return { ledger, issues, prs, merged, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, poolOk,
1229
+ // Whose stall it is, off the controller record in the same file — judged
1230
+ // here because it reads the process table, and only when the mark is
1231
+ // stalled, so a healthy board reads none. computeBoard() words it.
1232
+ const now = Date.now();
1233
+ const stallOwnerOf = isStalled(assessBeat({ beat, ticked, now })) ? stallOwner(priorState, NAME) : null;
1234
+ return { ledger, issues, prs, merged, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, stallOwner: stallOwnerOf, poolOk,
1227
1235
  poolCapped, prsCapped,
1228
- now: Date.now(), interval: interval ?? argInterval() ?? 15 };
1236
+ now, interval: interval ?? argInterval() ?? 15 };
1229
1237
  }
1230
1238
 
1231
1239
  async function main() {
@@ -24,7 +24,7 @@
24
24
  // it to its ticket number regardless; see the same paragraph below.
25
25
  // fleet-tick.mjs's I/O and main() never run here, main() being guarded on
26
26
  // argv[1].
27
- import { assessBeat, isStalled, stallReport } from "./fleet-state.mjs";
27
+ import { assessBeat, isStalled, stallReport, NO_OWNER } from "./fleet-state.mjs";
28
28
  import { parseToken, rowPr, premisesOf, HALT_CAUSES } from "./ledger-grammar.mjs";
29
29
  import { REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
30
30
 
@@ -376,12 +376,16 @@ function splitNumbered(line) {
376
376
  // this itself would be a second wording of the same verdict, free to drift
377
377
  // from fleet-tick's the moment either is edited. The page renders; the rule
378
378
  // and its words stay here.
379
- function stall(beat, ticked, tickets, pool, { ledgerOk, poolOk }, now) {
379
+ //
380
+ // `owner` is whose stall it is, fleet-state.mjs's stallOwner() answer: it
381
+ // reads the process table, which is I/O, so gather() judges it and this
382
+ // function only words it. Absent is no controller named.
383
+ function stall(beat, ticked, tickets, pool, { ledgerOk, poolOk, owner }, now) {
380
384
  const verdict = assessBeat({ beat, ticked, now });
381
385
  if (!isStalled(verdict)) return null;
382
386
  const claimed = ledgerOk ? tickets.filter((t) => t.column !== "POOL" && t.column !== "MERGED").length : null;
383
387
  const supply = poolOk ? pool : null;
384
- return { ...verdict, claimed, supply, text: stallReport(verdict, { claimed, supply }) };
388
+ return { ...verdict, claimed, supply, owner, text: stallReport(verdict, { claimed, supply, owner }) };
385
389
  }
386
390
 
387
391
  // Which of gather()'s `gh ... list` reads came back exactly as long as
@@ -591,6 +595,7 @@ export function computeBoard(inputs) {
591
595
  liveness: stall(inputs.beat, inputs.ticked, tickets, pool, {
592
596
  ledgerOk: (ledger.state ?? "read") === "read",
593
597
  poolOk: inputs.poolOk ?? true,
598
+ owner: inputs.stallOwner ?? NO_OWNER,
594
599
  }, now),
595
600
  attention,
596
601
  };
@@ -29,10 +29,12 @@
29
29
  // keeps firing on every completion, and without this key that
30
30
  // healthy busy run reads as a dead one the moment the OLD beat
31
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.
32
+ // controller ledger.mjs rotate only. {pid, lstart, prior, at}: the omp
33
+ // process that owns this run, its start time, the verdict rotate
34
+ // judged on the record it replaced (dead, ancestor or none), and
35
+ // when rotate wrote it — a mark older than `at` is the previous
36
+ // run's. Removed, not left stale, by a rotate that finds no omp
37
+ // ancestor.
36
38
  //
37
39
  // One writer per key. A key two scripts wrote would need locking to be
38
40
  // correct, and none of them is in a position to hold one. That holds per key,
@@ -45,6 +47,7 @@
45
47
  import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
46
48
  import { dirname, join } from "node:path";
47
49
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
50
+ import { judgeRecord, ProcUnreadable } from "./proc.mjs";
48
51
 
49
52
  // The filename, in one place, because the liveness mark gave this file a SECOND resolver.
50
53
  // board.mjs already resolves the run's workspace for itself — it has to, since
@@ -180,12 +183,19 @@ export function readState(path, name) {
180
183
  // pid outside the range a process id can take is no record either, since
181
184
  // no process could ever answer for it. `prior` degrades like `stopped`
182
185
  // does: a junk verdict proves nothing, so it reads as "none", and the
183
- // record around it still names a controller to judge.
186
+ // record around it still names a controller to judge. `at` degrades the
187
+ // same way, to null: the record still names a controller, and only when it
188
+ // was written is unknown.
184
189
  const ctl = (v) => {
185
190
  if (!isRecord(v)) return null;
186
191
  if (!Number.isInteger(v.pid) || v.pid < 1 || v.pid > 0x7fffffff) return null;
187
192
  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" };
193
+ return {
194
+ pid: v.pid,
195
+ lstart: v.lstart,
196
+ prior: PRIORS.includes(v.prior) ? v.prior : "none",
197
+ at: Number.isInteger(v.at) && v.at > 0 ? v.at : null,
198
+ };
189
199
  };
190
200
  const { quiet, elapsed, digest, beat, ticked, controller, ...rest } = parsed;
191
201
  return {
@@ -403,6 +413,49 @@ function mins(ms) {
403
413
  return `${m}m${s}s`;
404
414
  }
405
415
 
416
+ // Whose stall a reader sees, off the controller record — the mark says only
417
+ // that the beat stopped, never whether the run did. No record: unknown, and
418
+ // the report keeps the wording it had before there was one.
419
+ //
420
+ // A mark older than the record's `at` was left by the run BEFORE the one
421
+ // that wrote the record: rotate replaced the record after that run's last
422
+ // beat and tick. That is a run's first tick, and by then the record names
423
+ // this run's own live controller, so judging it would call every previous
424
+ // run alive. That stall reads the verdict rotate reached on the record it
425
+ // replaced, `prior`: dead is a controller gone whose claims this run resumes,
426
+ // ancestor is this same session's earlier run and so alive, none is unknown.
427
+ // A mark written since the record — any later tick — is the recorded
428
+ // controller's own, so the record itself is judged, through proc.mjs: dead or
429
+ // a reused pid is gone and the NEXT run resumes; alive, or an ancestor of the
430
+ // reader, is alive. A record with no `at` cannot place the mark and is
431
+ // judged too.
432
+ //
433
+ // `judge` is replaceable for the same reason proc.mjs's process source is: a
434
+ // reader under a live omp session would otherwise find that session. A
435
+ // process table that cannot be read leaves the stall unattributed, said on
436
+ // stderr, rather than calling a controller nobody could judge dead or alive.
437
+ export const NO_OWNER = Object.freeze({ kind: "none" });
438
+ export function stallOwner({ controller, beat, ticked }, name, judge = judgeRecord) {
439
+ if (!controller) return NO_OWNER;
440
+ const before = (mark) => mark === null || mark.at < controller.at;
441
+ if (controller.at !== null && before(beat) && before(ticked)) {
442
+ if (controller.prior === "dead") return { kind: "gone", resumes: "this run" };
443
+ if (controller.prior === "ancestor") return { kind: "alive", pid: null };
444
+ return NO_OWNER;
445
+ }
446
+ let verdict;
447
+ try {
448
+ verdict = judge(controller);
449
+ } catch (e) {
450
+ if (!(e instanceof ProcUnreadable)) throw e;
451
+ console.error(`${name}: WARNING ${e.message} — the recorded controller pid ${controller.pid} cannot be judged, so the stall report names no controller`);
452
+ return NO_OWNER;
453
+ }
454
+ if (verdict === "dead") return { kind: "gone", resumes: "the next run" };
455
+ if (verdict === "alive" || verdict === "ancestor") return { kind: "alive", pid: controller.pid };
456
+ return NO_OWNER;
457
+ }
458
+
406
459
  // The report. Returns null for anything isStalled() rejects, so a caller that
407
460
  // skipped the predicate cannot print a stall for a healthy run by accident.
408
461
  //
@@ -414,12 +467,18 @@ function mins(ms) {
414
467
  // candidate scan excludes that label, so those tickets are invisible to the
415
468
  // next run's scans and to the maintainer's both.
416
469
  //
470
+ // `owner` is stallOwner()'s answer and leads the line, because it is what
471
+ // the maintainer acts on: a controller alive is a run that stopped beating
472
+ // and kept going, never one to restart; a controller gone is a run whose
473
+ // claims without a PR the next phase 0 resumes and whose open PRs its fold-in
474
+ // queues. No owner keeps the wording the report had before the record existed.
475
+ //
417
476
  // `claimed` and `supply` are `null` for UNKNOWN, never 0. The two readers
418
477
  // count them from different sources (a gh query on the claim label; the
419
478
  // cockpit's own cards) and either source can fail, and "0 claimed" off a
420
479
  // failed read is the same lie as "supply 0" off one — it says the night cost
421
480
  // nothing when it may have stranded the whole pool.
422
- export function stallReport(verdict, { claimed, supply }) {
481
+ export function stallReport(verdict, { claimed, supply, owner = NO_OWNER }) {
423
482
  if (!isStalled(verdict)) return null;
424
483
  const n = (v) => (v == null ? "unknown" : String(v));
425
484
  // Present tense for the deliberate stop and past for the abrupt one, because
@@ -428,7 +487,13 @@ export function stallReport(verdict, { claimed, supply }) {
428
487
  const why = verdict.kind === "stopped"
429
488
  ? `stopped deliberately — recorded reason: ${verdict.reason}`
430
489
  : "the beat stopped without a recorded reason";
431
- return `heartbeat STALLED: last beat ${new Date(verdict.at).toISOString()}`
490
+ const head = owner.kind === "alive"
491
+ ? `heartbeat not beating, controller alive (${owner.pid === null ? "this session's earlier run" : `pid ${owner.pid}`})`
492
+ : owner.kind === "gone" ? "heartbeat STALLED, controller gone" : "heartbeat STALLED";
493
+ const tail = owner.kind === "gone"
494
+ ? `; ${owner.resumes} resumes its claims without a PR, and its open PRs return through the fold-in`
495
+ : "";
496
+ return `${head}: last beat ${new Date(verdict.at).toISOString()}`
432
497
  + ` (${mins(verdict.ageMs)} ago, ${mins(verdict.overdueMs)} past the ${mins(verdict.intervalMs)} interval it promised)`
433
- + ` — ${why}; ${n(claimed)} ticket(s) claimed and in flight, pool supply ${n(supply)}`;
498
+ + ` — ${why}; ${n(claimed)} ticket(s) claimed and in flight, pool supply ${n(supply)}${tail}`;
434
499
  }
@@ -895,7 +895,7 @@ import { parseArgs } from "node:util";
895
895
  import { makeDie, isDigits } from "./arg.mjs";
896
896
  import { gitEnv } from "./git-env.mjs";
897
897
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
898
- import { statePath, readState, writeState, assessBeat, isStalled, stallReport } from "./fleet-state.mjs";
898
+ import { statePath, readState, writeState, assessBeat, isStalled, stallReport, stallOwner } from "./fleet-state.mjs";
899
899
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
900
900
 
901
901
  const NAME = "fleet-tick";
@@ -1216,9 +1216,13 @@ function main() {
1216
1216
  // read and the ledger read below both exit 2 on failure, and a stall
1217
1217
  // announced after them is a stall a gh outage can silence. The supply it
1218
1218
  // reports is the local shortlist file's, which no outage can take away.
1219
+ // Whose stall it is comes off the controller record, judged only once
1220
+ // there is a stall to name, so a healthy tick reads no process table.
1219
1221
  const priorState = readState(path, NAME);
1220
1222
  const verdict = assessBeat({ beat: priorState.beat, ticked: priorState.ticked, now: Date.now() });
1221
- if (isStalled(verdict)) console.log(stallReport(verdict, { claimed: claimed(), supply: current.scanned }));
1223
+ if (isStalled(verdict)) {
1224
+ console.log(stallReport(verdict, { claimed: claimed(), supply: current.scanned, owner: stallOwner(priorState, NAME) }));
1225
+ }
1222
1226
 
1223
1227
  // Every read happens before anything prints: a partial tick is worse than no
1224
1228
  // tick, because half a reconcile still reads like a reconcile.
@@ -1520,11 +1520,13 @@ function runCheck() {
1520
1520
  // Its last act, whether or not there was a ledger to move, replaces the
1521
1521
  // record with this run's own, carrying the verdict as `prior` — the next
1522
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.
1523
+ // live ancestor — and the time of this write as `at`, so a reader can tell a
1524
+ // mark the previous run left from one written since. No omp ancestor removes
1525
+ // the key: an older run's record left in place would be judged again, as
1526
+ // dead, by a run that cannot know whether the run after it is still live.
1527
+ // This run's own record is computed before anything moves too, so a process
1528
+ // table that cannot be read refuses with nothing moved rather than after the
1529
+ // move.
1528
1530
  function runRotate() {
1529
1531
  const beatFile = stateFileIn(dirname(file));
1530
1532
  const state = readState(beatFile, NAME);
@@ -1575,7 +1577,7 @@ function runRotate() {
1575
1577
  // Re-read rather than reuse the read above: the heartbeat file has other
1576
1578
  // writers, and a patch built from an older view would undo what they wrote
1577
1579
  // since.
1578
- const record = ours === null ? undefined : { ...ours, prior };
1580
+ const record = ours === null ? undefined : { ...ours, prior, at: Date.now() };
1579
1581
  if (!writeState(beatFile, NAME, readState(beatFile, NAME), { controller: record })) {
1580
1582
  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`);
1581
1583
  }
package/scripts/proc.mjs CHANGED
@@ -159,3 +159,10 @@ export function judgeController(record, source, chain) {
159
159
  if (chain.some((e) => e.pid === record.pid)) return "ancestor";
160
160
  return "alive";
161
161
  }
162
+
163
+ // judgeController() for a reader that only names a record: the process
164
+ // source and the caller's own chain read here, once. Throws ProcUnreadable.
165
+ export function judgeRecord(record) {
166
+ const source = processSource();
167
+ return judgeController(record, source, ancestry(source));
168
+ }
@@ -0,0 +1,212 @@
1
+ #!/usr/bin/env node
2
+ // Phase 0's stranded-claim step: which claims did the previous run leave
3
+ // without a PR, and which of them does this run resume? It lists and
4
+ // classifies; it acts on nothing — no dispatch, no label, no release. The
5
+ // controller dispatches off its answer.
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.
13
+ //
14
+ // THE VERDICT is `prior` in the controller record, the one `ledger.mjs
15
+ // rotate` reached on the record it replaced — never a fresh judgement of the
16
+ // record itself, which names this run's own live controller and would read
17
+ // alive every time. A record that is absent, or a heartbeat file that cannot
18
+ // be read, is `none`.
19
+ // dead every open in-progress issue with no open PR: `resume` when
20
+ // exactly one worktree for it sits under this checkout's
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
24
+ // none nothing proves the previous run dead: every claim `report`
25
+ //
26
+ // "An open PR about the issue" is the in-flight check's reading, its branch rule
27
+ // narrowed: a PR linked to the issue that is still open, a linked PR in another
28
+ // repository (whose state this repository's list cannot show, so it counts), or
29
+ // an open PR whose branch opens with the number — `<type>/<n>-<slug>`,
30
+ // claim-ticket.sh's shape. A PR that carries the number elsewhere in its branch
31
+ // is not taken for the claim's: the claim is listed `report`, never resumed,
32
+ // with that PR named. A worktree is the issue's when its directory name names
33
+ // the number as a whole segment, so a worktree named for issue 129 is never
34
+ // issue 12's.
35
+ //
36
+ // Prints `{prior, claims: [{n, t, action, worktree, branch, why}]}` on stdout.
37
+ // 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.
40
+
41
+ import { spawnSync } from "node:child_process";
42
+ import { realpathSync, statSync } from "node:fs";
43
+ import { basename, dirname, join } from "node:path";
44
+ import { makeDie, writeAll } from "./arg.mjs";
45
+ import { gitEnv } from "./git-env.mjs";
46
+ import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
47
+ import { readState, stateFileIn } from "./fleet-state.mjs";
48
+
49
+ const NAME = "stranded";
50
+ const die = makeDie(NAME);
51
+ const LABEL = "in-progress";
52
+ const LIMIT = 1000;
53
+ const GH_TIMEOUT_MS = 20_000;
54
+ const GIT_TIMEOUT_MS = 20_000;
55
+ const MAX_BUFFER = 64 * 1024 * 1024;
56
+
57
+ const log = (line) => writeAll(2, `${line}\n`);
58
+ const segment = (n) => new RegExp(`(^|[/-])${n}([-/]|$)`);
59
+ // `owner/repo` of a github.com issue or PR URL.
60
+ const repoOf = (url) => String(url ?? "").split("/").slice(3, 5).join("/");
61
+
62
+ function how(r) {
63
+ if (r.error) return r.error.code ?? r.error.message;
64
+ if (r.signal) return `killed by ${r.signal}`;
65
+ const said = String(r.stderr ?? "").trim().split("\n").at(-1);
66
+ return said ? `exit ${r.status}: ${said}` : `exit ${r.status}`;
67
+ }
68
+
69
+ // gh resolves its repository from GH_REPO, then the cwd's git remotes: either
70
+ // one ambient would list another repository's tracker.
71
+ function ghList(what, args) {
72
+ const r = spawnSync("gh", [...args, "--limit", String(LIMIT)], {
73
+ encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv({ GH_REPO: "" }),
74
+ });
75
+ if (r.error || r.status !== 0) die(`gh ${args.slice(0, 2).join(" ")} failed (${how(r)}) — the ${what} is unknown, so nothing is classified`);
76
+ let rows;
77
+ try {
78
+ rows = JSON.parse(r.stdout);
79
+ } catch (e) {
80
+ die(`could not parse the ${what}: ${e.message}`);
81
+ }
82
+ if (!Array.isArray(rows)) die(`the ${what} is not a JSON array`);
83
+ if (rows.length >= LIMIT) die(`the ${what} came back at its cap of ${LIMIT} — it may hold more than it showed, so nothing is classified`);
84
+ return rows;
85
+ }
86
+
87
+ // Every registered worktree: its path, branch (null when detached) and
88
+ // whether git calls it prunable — its directory gone.
89
+ function worktrees(cwd) {
90
+ const r = spawnSync("git", ["worktree", "list", "--porcelain", "-z"], {
91
+ cwd, encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GIT_TIMEOUT_MS, env: gitEnv(),
92
+ });
93
+ if (r.error || r.status !== 0) die(`git worktree list failed (${how(r)}) — which claims have a worktree is unknown`);
94
+ const out = [];
95
+ let cur = null;
96
+ for (const field of r.stdout.split("\0")) {
97
+ if (field === "") {
98
+ cur = null;
99
+ continue;
100
+ }
101
+ if (field.startsWith("worktree ")) {
102
+ cur = { path: field.slice("worktree ".length), branch: null, prunable: false };
103
+ out.push(cur);
104
+ } else if (cur !== null && field.startsWith("branch refs/heads/")) {
105
+ cur.branch = field.slice("branch refs/heads/".length);
106
+ } else if (cur !== null && (field === "prunable" || field.startsWith("prunable "))) {
107
+ cur.prunable = true;
108
+ }
109
+ }
110
+ return out;
111
+ }
112
+
113
+ // Whether `p` is on disk. Only ENOENT is gone: any other failure (EACCES on a
114
+ // parent of a worktree git still lists, a locked one whose directory is gone)
115
+ // leaves it unknown, and unknown is never read as gone — that would report the
116
+ // claim as one with no worktree and say nothing of why.
117
+ function present(p) {
118
+ try {
119
+ statSync(p);
120
+ return true;
121
+ } catch (e) {
122
+ if (e.code === "ENOENT") return false;
123
+ return die(`cannot tell whether ${p} exists (${e.code ?? e.message}) — which claims have a worktree is unknown, so nothing is classified`);
124
+ }
125
+ }
126
+
127
+ const real = (p) => {
128
+ try {
129
+ return realpathSync(p);
130
+ } catch (e) {
131
+ if (e.code === "ENOENT") return p;
132
+ return die(`cannot resolve ${p} (${e.code ?? e.message}) — which worktrees are in this checkout is unknown, so nothing is classified`);
133
+ }
134
+ };
135
+
136
+ function main() {
137
+ if (process.argv.length > 2) die(`takes no arguments, got ${process.argv.slice(2).join(" ")}`);
138
+ let fleetDir;
139
+ try {
140
+ fleetDir = fleetFile(null);
141
+ } catch (e) {
142
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
143
+ die(e.message);
144
+ }
145
+ const checkout = dirname(fleetDir);
146
+
147
+ // readState() announces a file it could not use on stderr and returns no
148
+ // record, which is `none`: unknown, so nothing is resumed.
149
+ const { controller } = readState(stateFileIn(fleetDir), NAME);
150
+ const prior = controller?.prior ?? "none";
151
+ 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: [] }));
154
+ return;
155
+ }
156
+
157
+ const issues = ghList(`list of open ${LABEL} issues`, [
158
+ "issue", "list", "--label", LABEL, "--state", "open", "--json", "number,title,url,closedByPullRequestsReferences",
159
+ ]);
160
+ const prs = ghList("list of open PRs", ["pr", "list", "--state", "open", "--json", "number,headRefName,url"]);
161
+ const openByUrl = new Map(prs.map((p) => [p.url, p]));
162
+
163
+ // The PRs that make an issue someone else's business, or none — and, apart,
164
+ // the open PRs whose branch carries the number somewhere other than as the
165
+ // ticket's own: `<type>/<n>-<slug>` is claim-ticket.sh's shape, so
166
+ // `implementer/1799-bump-node-20` names issue 1799 and merely ends in 20.
167
+ const prsFor = (issue, seg) => {
168
+ const here = repoOf(issue.url);
169
+ const linked = (issue.closedByPullRequestsReferences ?? []).flatMap((ref) => {
170
+ if (openByUrl.has(ref.url)) return [`open PR #${openByUrl.get(ref.url).number}`];
171
+ const repo = repoOf(ref.url);
172
+ return repo !== here ? [`linked PR ${repo}#${ref.url.split("/").at(-1)}, whose state this repository's list cannot show`] : [];
173
+ });
174
+ const own = new RegExp(`^([^/]*/)?${issue.number}([-/]|$)`);
175
+ const named = prs.filter((p) => seg.test(p.headRefName ?? ""));
176
+ const describe = (p) => `open PR #${p.number} (branch ${p.headRefName})`;
177
+ return {
178
+ held: [...linked, ...named.filter((p) => own.test(p.headRefName)).map(describe)],
179
+ mentioned: named.filter((p) => !own.test(p.headRefName)).map(describe),
180
+ };
181
+ };
182
+
183
+ const home = real(join(checkout, ".worktrees"));
184
+ const all = worktrees(checkout);
185
+ const claims = [];
186
+ for (const issue of issues) {
187
+ const seg = segment(issue.number);
188
+ const { held, mentioned } = prsFor(issue, seg);
189
+ if (held.length > 0) {
190
+ log(` #${issue.number} has ${held.join(", ")} — the fold-in owns it`);
191
+ continue;
192
+ }
193
+ const mine = all.filter((w) => !w.prunable && seg.test(basename(w.path)) && present(w.path));
194
+ const inside = mine.filter((w) => real(dirname(w.path)) === home);
195
+ const outside = mine.filter((w) => !inside.includes(w));
196
+ const one = inside.length === 1 ? inside[0] : null;
197
+ let why;
198
+ if (prior !== "dead") why = "no record proves the previous run dead, so nothing is resumed";
199
+ else if (one) why = "its worktree is in this checkout";
200
+ else if (inside.length > 1) why = `several worktrees for it in this checkout: ${inside.map((w) => w.path).join(", ")}`;
201
+ else if (outside.length > 0) why = `its worktree is outside this checkout's .worktrees/: ${outside.map((w) => w.path).join(", ")}`;
202
+ else why = "no worktree for it in this checkout";
203
+ const action = prior === "dead" && one && mentioned.length === 0 ? "resume" : "report";
204
+ // Not taken for its PR — but never resumed past one that might be.
205
+ if (mentioned.length > 0) why += `; ${mentioned.join(", ")} carries the number outside the ticket position, so check whether it is this claim's`;
206
+ claims.push({ n: issue.number, t: issue.title, action, worktree: one?.path ?? null, branch: one?.branch ?? null, why });
207
+ log(` #${issue.number} ${action} — ${why}`);
208
+ }
209
+ console.log(JSON.stringify({ prior, claims }));
210
+ }
211
+
212
+ main();
@@ -346,8 +346,12 @@ phase, or in any later one, asks the maintainer which tickets to take.
346
346
  left behind can no longer hold this run's tick. What an unclean end left in
347
347
  flight comes back through the ordinary per-run path: open PRs through the
348
348
  fold-in below, `behind-pr:`/`behind-issue:` exclusions through phase 1's
349
- collision and sequence checks, and a killed member's ticket through a new
350
- member under a new name. An exclusion that expires with the run that wrote
349
+ collision and sequence checks, and a claim a dead run left without a PR
350
+ through the stranded-claim step below — resumed by a new member under a
351
+ new name when its worktree is in this checkout, reported to the
352
+ maintainer otherwise. A claim this session's own earlier run left stays
353
+ with it: its member may still be live, and the Member-killed row's check
354
+ covers it. An exclusion that expires with the run that wrote
351
355
  it (`deferred-to-session-end` and its like) must be restated if it still
352
356
  holds. **The guard is the
353
357
  controller record**, `controller` in `.fleet/heartbeat.json`: the omp
@@ -369,8 +373,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
369
373
  `.fleet/heartbeat.json` exists but cannot be read or parsed — a record
370
374
  nobody could judge is never taken for no record. Its last act, ledger or none, is
371
375
  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
376
+ above it, its start time, as `prior` the verdict it reached on the
377
+ record it found (`dead`, `ancestor` or `none`), and as `at` when it wrote
378
+ it — or to remove the key when
374
379
  no `omp` process is above it. That write can fail, and then exit 2 follows
375
380
  a move: `rotated <file> -> <archive>` on stderr, then the refusal that the
376
381
  record could not be written. Run the rotation before this run's own first
@@ -444,6 +449,42 @@ phase, or in any later one, asks the maintainer which tickets to take.
444
449
  `fleet-tick`'s backlog forever: unreviewable AND uncounted is the state
445
450
  that strands it.
446
451
 
452
+ **Resume the claims a dead run left without a PR — after the fold-in,
453
+ before shortlisting.** A claim's label and worktree exist before its first
454
+ push, and rotation carries no row forward, the candidate scan excludes
455
+ `in-progress`, and the in-flight check reads the worktree as taken — so a
456
+ claim the previous run left without a PR is held by nobody until this step
457
+ names it. `~/.fleet/bin/fleet-run stranded.mjs` lists and classifies; you
458
+ dispatch. It reads the `prior` rotate just recorded, never the record
459
+ itself, which names this run's own live controller, and prints
460
+ `{prior, claims: [{n, t, action, worktree, branch, why}]}`:
461
+
462
+ - `prior: dead` — every open `in-progress` issue with no open PR (one with
463
+ an open PR is the fold-in's): `resume` when exactly one worktree for it
464
+ sits under this checkout's `.worktrees/`, `report` otherwise.
465
+ - `prior: ancestor` — this session's own earlier run: nothing is listed.
466
+ Its members may still be live, and the Member-killed row's check covers
467
+ them.
468
+ - `prior: none` — no record proves the previous run dead (no record yet, or
469
+ no `omp` process found above the rotation): every claim is `report`, and
470
+ nothing is resumed.
471
+
472
+ A `resume` follows the Member-killed row across the run boundary: a new
473
+ member under a new name — `impl-<N>-b`, or one letter past the highest
474
+ `impl-<N>-<x>` in the archive that rotate printed the path of — on the same
475
+ ticket, in the printed worktree and branch, its prompt the phase 2 prompt
476
+ off a fresh read of the issue plus what it inherits (`git -C <worktree> log
477
+ --oneline origin/main..HEAD`, `git -C <worktree> status --short`, and the
478
+ files under `<scratch>/impl-<N>/`). Record it the ordinary way —
479
+ `ledger.mjs row <N>
480
+ "impl-<N>-b"`, then `ledger.mjs dispatch <N> impl-<N>-b`, then the `task`
481
+ call naming the `agent` it printed, then the tier check — and never
482
+ `claim-ticket.sh`: the claim already stands. A `report` goes to the
483
+ maintainer as `#<N> — <why>` and nothing else: no dispatch, no label change,
484
+ no release. Exit 2 is a list that did not answer — a `gh` or `git`
485
+ failure, a list at its cap, or a worktree whose presence cannot be told —
486
+ and is never nothing stranded.
487
+
447
488
  1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
448
489
  `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
449
490
  — no ticket body is read here, because a Pull reads one ticket in full at
@@ -1802,16 +1843,30 @@ Skipping it is not fatal — the next reader still reports the stop, it just
1802
1843
  reports that the beat stopped *without a recorded reason*, which is all it can
1803
1844
  honestly say about a death that named nothing.
1804
1845
 
1805
- **A `heartbeat STALLED` line is the PREVIOUS run, never this one.** `fleet-tick`
1846
+ **A stall line names whose stall it is.** `fleet-tick`
1806
1847
  prints it before its own rows when the mark it finds is overdue against the
1807
1848
  interval that mark recorded, and the cockpit shows the same line while it is
1808
1849
  up. It names when the beat was last seen, how overdue that is, how many
1809
1850
  tickets are still claimed and in flight, and how much supply the last read found
1810
1851
  — because the claimed ones keep the `in-progress` label, the candidate scan
1811
1852
  EXCLUDES that label, and those tickets are therefore invisible to your own
1812
- shortlist and to the maintainer's. Read the line, decide what to do about the
1813
- stranded tickets, and carry on; nothing in the fleet releases, relabels or
1814
- reaps them for you, and nothing restarts the run that stranded them.
1853
+ shortlist and to the maintainer's. Its opening words come off the controller
1854
+ record. Your first tick's line is the PREVIOUS run's stall, read off the
1855
+ `prior` rotate recorded; any later line is judged off the record itself:
1856
+
1857
+ - `heartbeat STALLED, controller gone` — the run that stranded them is dead.
1858
+ Its claims without a PR come back through phase 0's stranded-claim step —
1859
+ this run's on your first tick, the next run's otherwise — and its open PRs
1860
+ through the fold-in.
1861
+ - `heartbeat not beating, controller alive (pid N)`, or `(this session's
1862
+ earlier run)` — a controller that stopped beating and kept going. Nothing
1863
+ died, so nothing is resumed; on a later tick of your own, that controller
1864
+ is you, and the fix is to beat.
1865
+ - `heartbeat STALLED` alone — no record says whether that controller lives.
1866
+ The line is detection only.
1867
+
1868
+ Read the line and carry on; nothing in the fleet releases, relabels or
1869
+ reaps the stranded tickets for you, and nothing restarts the run that stranded them.
1815
1870
 
1816
1871
  **Own the CI waits.** Members are turn-based and cannot hold across a ten-minute
1817
1872
  run — they rebase, push, stop. Arm a second persistent Monitor over open PRs'