@feigi/fleet-ctl 3.72.4 → 3.73.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.
@@ -48,8 +48,14 @@ human hands you do not have → bail, name the cause, do not implement.
48
48
  **Re-derive the ticket's claims against `origin/main` before implementing** —
49
49
  not the working tree, and not the ticket's line numbers, which drift. The Pull
50
50
  runs a cheap version of this check, so what reaches you is what a `grep` could
51
- not settle; you have the tree, so you are the backstop. Already fixed → report
52
- that with the commit and do NOT invent work. An acceptance criterion the tree
51
+ not settle; you have the tree, so you are the backstop. Already fixed on
52
+ `origin/main` → bail with `bailCause` `fixed` and do NOT invent work:
53
+ `bailDetail` is `<sha> — <how origin/main's tree meets the acceptance>`, `<sha>`
54
+ the commit that fixed it. Already covered by an open PR M you find → bail with
55
+ `bailCause` `covered`: `bailDetail` is `PR#M — <how M's diff meets N's
56
+ acceptance>`, and PR M is never edited. What the controller does with each
57
+ cause is the *Implementer bails before implementing* table in run-team's
58
+ SKILL.md. An acceptance criterion the tree
53
59
  now **contradicts** is a bail, not a thing to implement: say which, and stop.
54
60
 
55
61
  **Claim discipline, on every ticket:**
@@ -48,8 +48,14 @@ human hands you do not have → bail, name the cause, do not implement.
48
48
  **Re-derive the ticket's claims against `origin/main` before implementing** —
49
49
  not the working tree, and not the ticket's line numbers, which drift. The Pull
50
50
  runs a cheap version of this check, so what reaches you is what a `grep` could
51
- not settle; you have the tree, so you are the backstop. Already fixed → report
52
- that with the commit and do NOT invent work. An acceptance criterion the tree
51
+ not settle; you have the tree, so you are the backstop. Already fixed on
52
+ `origin/main` → bail with `bailCause` `fixed` and do NOT invent work:
53
+ `bailDetail` is `<sha> — <how origin/main's tree meets the acceptance>`, `<sha>`
54
+ the commit that fixed it. Already covered by an open PR M you find → bail with
55
+ `bailCause` `covered`: `bailDetail` is `PR#M — <how M's diff meets N's
56
+ acceptance>`, and PR M is never edited. What the controller does with each
57
+ cause is the *Implementer bails before implementing* table in run-team's
58
+ SKILL.md. An acceptance criterion the tree
53
59
  now **contradicts** is a bail, not a thing to implement: say which, and stop.
54
60
 
55
61
  **Claim discipline, on every ticket:**
@@ -48,8 +48,14 @@ human hands you do not have → bail, name the cause, do not implement.
48
48
  **Re-derive the ticket's claims against `origin/main` before implementing** —
49
49
  not the working tree, and not the ticket's line numbers, which drift. The Pull
50
50
  runs a cheap version of this check, so what reaches you is what a `grep` could
51
- not settle; you have the tree, so you are the backstop. Already fixed → report
52
- that with the commit and do NOT invent work. An acceptance criterion the tree
51
+ not settle; you have the tree, so you are the backstop. Already fixed on
52
+ `origin/main` → bail with `bailCause` `fixed` and do NOT invent work:
53
+ `bailDetail` is `<sha> — <how origin/main's tree meets the acceptance>`, `<sha>`
54
+ the commit that fixed it. Already covered by an open PR M you find → bail with
55
+ `bailCause` `covered`: `bailDetail` is `PR#M — <how M's diff meets N's
56
+ acceptance>`, and PR M is never edited. What the controller does with each
57
+ cause is the *Implementer bails before implementing* table in run-team's
58
+ SKILL.md. An acceptance criterion the tree
53
59
  now **contradicts** is a bail, not a thing to implement: say which, and stop.
54
60
 
55
61
  **Claim discipline, on every ticket:**
@@ -48,8 +48,14 @@ human hands you do not have → bail, name the cause, do not implement.
48
48
  **Re-derive the ticket's claims against `origin/main` before implementing** —
49
49
  not the working tree, and not the ticket's line numbers, which drift. The Pull
50
50
  runs a cheap version of this check, so what reaches you is what a `grep` could
51
- not settle; you have the tree, so you are the backstop. Already fixed → report
52
- that with the commit and do NOT invent work. An acceptance criterion the tree
51
+ not settle; you have the tree, so you are the backstop. Already fixed on
52
+ `origin/main` → bail with `bailCause` `fixed` and do NOT invent work:
53
+ `bailDetail` is `<sha> — <how origin/main's tree meets the acceptance>`, `<sha>`
54
+ the commit that fixed it. Already covered by an open PR M you find → bail with
55
+ `bailCause` `covered`: `bailDetail` is `PR#M — <how M's diff meets N's
56
+ acceptance>`, and PR M is never edited. What the controller does with each
57
+ cause is the *Implementer bails before implementing* table in run-team's
58
+ SKILL.md. An acceptance criterion the tree
53
59
  now **contradicts** is a bail, not a thing to implement: say which, and stop.
54
60
 
55
61
  **Claim discipline, on every ticket:**
@@ -48,8 +48,14 @@ human hands you do not have → bail, name the cause, do not implement.
48
48
  **Re-derive the ticket's claims against `origin/main` before implementing** —
49
49
  not the working tree, and not the ticket's line numbers, which drift. The Pull
50
50
  runs a cheap version of this check, so what reaches you is what a `grep` could
51
- not settle; you have the tree, so you are the backstop. Already fixed → report
52
- that with the commit and do NOT invent work. An acceptance criterion the tree
51
+ not settle; you have the tree, so you are the backstop. Already fixed on
52
+ `origin/main` → bail with `bailCause` `fixed` and do NOT invent work:
53
+ `bailDetail` is `<sha> — <how origin/main's tree meets the acceptance>`, `<sha>`
54
+ the commit that fixed it. Already covered by an open PR M you find → bail with
55
+ `bailCause` `covered`: `bailDetail` is `PR#M — <how M's diff meets N's
56
+ acceptance>`, and PR M is never edited. What the controller does with each
57
+ cause is the *Implementer bails before implementing* table in run-team's
58
+ SKILL.md. An acceptance criterion the tree
53
59
  now **contradicts** is a bail, not a thing to implement: say which, and stop.
54
60
 
55
61
  **Claim discipline, on every ticket:**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.72.4",
3
+ "version": "3.73.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": {
@@ -8,7 +8,7 @@
8
8
  // recipe-deriver, relabel (the comment a Pull posts on a ticket it returns,
9
9
  // not a member's brief). A role with kinds (fix-applier: review, conflict,
10
10
  // dispositions-retry, red-check; finisher: fresh, repair; relabel:
11
- // needs-triage, fork, hands) requires --kind; a role without them refuses it
11
+ // needs-triage, fork, hands, covered, fixed) requires --kind; a role without them refuses it
12
12
  // as an unknown flag.
13
13
  //
14
14
  // OUTPUT. The brief on stdout and nothing else. With --json the payload
@@ -19,14 +19,15 @@
19
19
  //
20
20
  // impl-report <impl-N[-x]>
21
21
  // `ledger.mjs settle <member> --from-report`, which runs `verify-sha.sh` and reads the PR itself. Settled `bailed`: the
22
- // report's `bailCause` names the label (undecided `needs-triage`, fork
23
- // and hands `ready-for-human`), then:
22
+ // report's `bailCause` names the label (undecided `needs-triage`, fork,
23
+ // hands and covered `ready-for-human`), then:
24
24
  // `gh issue edit <N> --remove-label ready-for-agent --remove-label
25
25
  // in-progress --add-label <label>`, skipped when the issue already
26
26
  // carries the label and neither of the others;
27
27
  // `gh issue comment <N>` with the comment `dispatch-prompt.mjs render
28
28
  // relabel` renders from the report's `bailDetail` — kind
29
- // `needs-triage` (`--line`), `fork` (`--options`), or `hands`, whose
29
+ // `needs-triage` (`--line`), `fork` (`--options`), `covered`
30
+ // (`--detail`, `PR#M — <how>`), or `hands`, whose
30
31
  // detail opens with the cause the Pull's answer names (`external
31
32
  // access`, `manual testing`, `judgment`) and goes on with the line —
32
33
  // skipped when the issue already carries that comment;
@@ -37,6 +38,16 @@
37
38
  // `NEED hand-release #<N> <blocker>` and is never forced.
38
39
  // Dropping `in-progress` is the load-bearing half: phase 1 applied it and `candidates.mjs` excludes it, so leaving it makes the ticket invisible to the controller's scans and the maintainer's. It does not loop; it disappears.
39
40
  // `reap.sh` declines a claim that never became a PR, so the release of a bailed claim is `release-ticket.sh`'s.
41
+ // A `fixed` bail takes no label. Its `bailDetail` is `<sha> — <how>`,
42
+ // and `verify-sha.sh main <sha>` decides: exit 0 closes N, `gh issue
43
+ // close <N> --comment` with the kind `fixed` render (`--detail`, the
44
+ // whole `bailDetail`) — no comment when the issue already carries it,
45
+ // no close when it is already closed — then drops whichever of
46
+ // `ready-for-agent` and `in-progress` it carries and releases as above;
47
+ // exit 1 relabels `needs-triage` as above, its comment naming `<sha>`
48
+ // not on origin/main, and releases; any other answer, or a detail that
49
+ // opens with no sha, is a NEED and N is left untouched, claim and all.
50
+ // The PR a `covered` detail names is never written to.
40
51
  // fix-report <fix-pr-M[-x]>
41
52
  // `settle --from-report`, which records the filings and rulings the
42
53
  // report carries. Settled `applied:`/`no-op`, on a PR whose rows carry
@@ -176,11 +187,17 @@ const USAGE = `usage: ${NAME}.mjs <kind> <args> [--in-flight <n>] — kinds: `
176
187
  + Object.entries(KINDS).map(([k, { args, flag }]) => [k, ...args, ...(flag ? [flag] : [])].join(" ")).join(", ");
177
188
 
178
189
  // The label each `bailCause` demotes to, and the relabel template's kind.
179
- const BAILS = {
190
+ // `fixed` takes no label: it closes the ticket once `verify-sha.sh` finds the
191
+ // commit on origin/main, and demotes to `needs-triage` when it does not.
192
+ export const BAILS = {
180
193
  undecided: { label: "needs-triage", kind: "needs-triage", flag: "line" },
181
194
  fork: { label: "ready-for-human", kind: "fork", flag: "options" },
182
195
  hands: { label: "ready-for-human", kind: "hands" },
196
+ covered: { label: "ready-for-human", kind: "covered", flag: "detail" },
197
+ fixed: { kind: "fixed", flag: "detail" },
183
198
  };
199
+ // The commit a `fixed` bail's detail opens with.
200
+ const FIXED_SHA = /^([0-9a-f]{7,40})(?![0-9A-Za-z])/;
184
201
  // The causes a `hands` detail opens with — the Pull's answer grammar — and the
185
202
  // words each puts in the comment.
186
203
  const HANDS = { "external access": "external access", "manual testing": "manual testing", judgment: "judgment during the work" };
@@ -303,10 +320,11 @@ class Event {
303
320
  return outcome;
304
321
  }
305
322
 
306
- // The bodies of the comments on issue or PR `n`, trimmed, or null when gh
307
- // could not answer (the NEED is printed here).
323
+ // The labels, comments and state of issue `n`, or the comments of PR `n`,
324
+ // each comment trimmed, or null when gh could not answer (the NEED is
325
+ // printed here).
308
326
  comments(noun, n, what) {
309
- const r = gh([noun, "view", String(n), "--json", noun === "issue" ? "labels,comments" : "comments"]);
327
+ const r = gh([noun, "view", String(n), "--json", noun === "issue" ? "labels,comments,state" : "comments"]);
310
328
  let v = null;
311
329
  if (r.status === 0) {
312
330
  try {
@@ -319,7 +337,7 @@ class Event {
319
337
  this.need(`${what} — gh ${noun} view ${n} did not answer (${r.status === 0 ? "no JSON" : said(r)})`);
320
338
  return null;
321
339
  }
322
- return { labels: (v.labels ?? []).map((l) => l?.name), bodies: v.comments.map((c) => String(c?.body ?? "").trim()) };
340
+ return { labels: (v.labels ?? []).map((l) => l?.name), bodies: v.comments.map((c) => String(c?.body ?? "").trim()), state: v.state ?? null };
323
341
  }
324
342
 
325
343
  // `gh <noun> comment <n> --body <body>` unless `seen` already holds it.
@@ -352,35 +370,95 @@ function relabelArgs(cause, detail) {
352
370
  return { args: ["--kind", "hands", "--hands", HANDS[opener], "--line", line] };
353
371
  }
354
372
 
355
- function bailed(ev, member) {
356
- const ticket = parseMember(member).number;
357
- const read = ev.report(member);
358
- const cause = read.state === "ok" ? read.report.bailCause : null;
359
- if (!Object.hasOwn(BAILS, cause ?? "")) {
360
- ev.need(`relabel #${ticket} — ${member}'s report ${read.path} is ${read.state === "ok" ? `missing a bailCause` : read.state}: relabel by its cause by hand`);
361
- return;
373
+ // The comment `dispatch-prompt.mjs render relabel` renders for a bail, or null
374
+ // when there is none (the NEED, named `what`, is printed here).
375
+ function rendered(ev, ticket, cause, detail, what) {
376
+ const relabel = relabelArgs(cause, detail);
377
+ if (relabel.why !== undefined) {
378
+ ev.need(`${what} #${ticket} — ${relabel.why}: comment the cause by hand`);
379
+ return null;
362
380
  }
363
- const { label } = BAILS[cause];
381
+ const r = node("dispatch-prompt.mjs", ["render", "relabel", ...relabel.args]);
382
+ if (r.status !== 0) {
383
+ ev.need(`${what} #${ticket} — dispatch-prompt.mjs render relabel refused: ${said(r)}`);
384
+ return null;
385
+ }
386
+ return r.stdout;
387
+ }
388
+
389
+ // Moves #ticket to `label`, then posts the comment `body()` returns, if any.
390
+ // False when the move could not be made, so nothing after it may run.
391
+ function demote(ev, ticket, label, cause, body) {
364
392
  const seen = ev.comments("issue", ticket, `relabel #${ticket} ${label}`);
365
- if (seen === null) return;
393
+ if (seen === null) return false;
366
394
  if (seen.labels.includes(label) && !seen.labels.includes("ready-for-agent") && !seen.labels.includes("in-progress")) {
367
395
  ev.note(`#${ticket} already ${label}`);
368
396
  } else {
369
397
  const e = gh(["issue", "edit", String(ticket), "--remove-label", "ready-for-agent", "--remove-label", "in-progress", "--add-label", label]);
370
398
  if (e.status !== 0) {
371
399
  ev.need(`relabel #${ticket} ${label} — gh issue edit failed: ${said(e)}`);
372
- return;
400
+ return false;
373
401
  }
374
402
  ev.note(`relabelled #${ticket} ${label} (${cause})`);
375
403
  }
376
- const relabel = relabelArgs(cause, read.report.bailDetail);
377
- if (relabel.why !== undefined) {
378
- ev.need(`relabel-comment #${ticket} — ${relabel.why}: comment the cause by hand`);
404
+ const text = body();
405
+ if (text !== null) ev.comment("issue", ticket, text, seen, "relabel comment");
406
+ return true;
407
+ }
408
+
409
+ // A `fixed` bail: closed when its commit is on origin/main, demoted to
410
+ // `needs-triage` when it is not, untouched when that cannot be told. False
411
+ // when the claim must not be released.
412
+ function fixed(ev, ticket, detail) {
413
+ const sha = FIXED_SHA.exec(String(detail ?? "").trim())?.[1];
414
+ if (sha === undefined) {
415
+ ev.need(`close #${ticket} — the report's bailDetail opens with no commit sha: check the fix on origin/main and close or relabel by hand`);
416
+ return false;
417
+ }
418
+ const v = run("sh", [join(SCRIPTS, "verify-sha.sh"), "main", sha]);
419
+ if (v.status === 1) {
420
+ return demote(ev, ticket, "needs-triage", "fixed", () => `*Relabelled by the fleet controller.* Pulled for implementation and returned as already fixed by ${sha}: ${sha} not on origin/main.`);
421
+ }
422
+ if (v.status !== 0) {
423
+ ev.need(`close #${ticket} — verify-sha.sh main ${sha} could not answer (${v.how}): ${said(v)}`);
424
+ return false;
425
+ }
426
+ const body = rendered(ev, ticket, "fixed", detail, "close-comment");
427
+ if (body === null) return false;
428
+ const seen = ev.comments("issue", ticket, `close #${ticket}`);
429
+ if (seen === null) return false;
430
+ if (seen.state === "CLOSED") {
431
+ ev.note(`#${ticket} already closed`);
379
432
  } else {
380
- const r = node("dispatch-prompt.mjs", ["render", "relabel", ...relabel.args]);
381
- if (r.status !== 0) ev.need(`relabel-comment #${ticket} — dispatch-prompt.mjs render relabel refused: ${said(r)}`);
382
- else ev.comment("issue", ticket, r.stdout, seen, "relabel comment");
433
+ // A comment that landed before its close failed is not posted twice.
434
+ const c = gh(["issue", "close", String(ticket), ...(seen.bodies.includes(body.trim()) ? [] : ["--comment", body])]);
435
+ if (c.status !== 0) {
436
+ ev.need(`close #${ticket} — gh issue close failed: ${said(c)}`);
437
+ return false;
438
+ }
439
+ ev.note(`closed #${ticket}: fixed by ${sha}`);
440
+ }
441
+ const stale = ["ready-for-agent", "in-progress"].filter((l) => seen.labels.includes(l));
442
+ if (stale.length > 0) {
443
+ const e = gh(["issue", "edit", String(ticket), ...stale.flatMap((l) => ["--remove-label", l])]);
444
+ if (e.status !== 0) ev.need(`unlabel #${ticket} ${stale.join(" ")} — gh issue edit failed: ${said(e)}`);
445
+ }
446
+ return true;
447
+ }
448
+
449
+ function bailed(ev, member) {
450
+ const ticket = parseMember(member).number;
451
+ const read = ev.report(member);
452
+ const cause = read.state === "ok" ? read.report.bailCause : null;
453
+ if (!Object.hasOwn(BAILS, cause ?? "")) {
454
+ ev.need(`relabel #${ticket} — ${member}'s report ${read.path} is ${read.state === "ok" ? `missing a bailCause` : read.state}: relabel by its cause by hand`);
455
+ return;
383
456
  }
457
+ const detail = read.report.bailDetail;
458
+ const moved = cause === "fixed"
459
+ ? fixed(ev, ticket, detail)
460
+ : demote(ev, ticket, BAILS[cause].label, cause, () => rendered(ev, ticket, cause, detail, "relabel-comment"));
461
+ if (!moved) return;
384
462
  const release = run("sh", [join(SCRIPTS, "release-ticket.sh"), String(ticket), `impl-${ticket}`, "implementer", "--apply"]);
385
463
  if (release.status === 0) ev.note(`released #${ticket}`);
386
464
  else ev.need(`hand-release #${ticket} ${blocker(release)}`);
@@ -30,8 +30,15 @@
30
30
  // follow the --pr rule below.
31
31
  // impl-<N>/
32
32
  // removed when issue #N is CLOSED, or OPEN with no live
33
- // impl-<N>[-x] token and idle past the retention, so a bailed or
34
- // released ticket's partition is not inherited by its next claim.
33
+ // impl-<N>[-x] token, no claim worktree standing, and idle past
34
+ // the retention, so a bailed or released ticket's partition is not
35
+ // inherited by its next claim. A claim worktree stands when a
36
+ // worktree directly under this checkout's .worktrees/ names N as a
37
+ // whole segment of its directory name and that directory is there:
38
+ // an OPEN ticket's partition is kept while one stands, however idle.
39
+ // A claim worktree that cannot be checked — `git worktree list`
40
+ // failing, a .worktrees/ that cannot be read, or a directory there
41
+ // named for N that git does not list — keeps it, with that reason.
35
42
  // reports/<member>.json
36
43
  // a member's report file. `reports/` itself is never removed, and
37
44
  // is not aged out whole: each file is judged on its own, by the
@@ -93,7 +100,7 @@
93
100
  // read for any reason other than ENOENT. Nothing is removed before a refusal.
94
101
 
95
102
  import { spawnSync } from "node:child_process";
96
- import { lstatSync, readdirSync, statSync } from "node:fs";
103
+ import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
97
104
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
98
105
  import { fileURLToPath } from "node:url";
99
106
  import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
@@ -205,26 +212,90 @@ function liveNames(file) {
205
212
  return liveOnLedger(d.rows, d.dispatched).tokens.map((t) => t.name);
206
213
  }
207
214
 
208
- // The ledger file, or null when it is absent. Only ENOENT is absence; a
209
- // workspace that cannot be resolved, or a path that cannot be looked up,
210
- // refuses. `lstat`, so a dangling symlink is a ledger that cannot be read.
215
+ // The checkout the fleet dir sits in, and its ledger file — `file` null when it
216
+ // is absent. Only ENOENT is absence; a workspace that cannot be resolved, or a
217
+ // path that cannot be looked up, refuses. `lstat`, so a dangling symlink is a
218
+ // ledger that cannot be read.
211
219
  function ledgerFile() {
212
- let file;
220
+ let dir;
213
221
  try {
214
- file = fleetFile("ledger.md");
222
+ dir = fleetFile(null);
215
223
  } catch (e) {
216
224
  if (!(e instanceof FleetDirUnresolvable)) throw e;
217
225
  die(`${e.message} — the ledger cannot be found, so which members are live is unknown`);
218
226
  }
227
+ const file = join(dir, "ledger.md");
219
228
  try {
220
229
  lstatSync(file);
221
- return file;
230
+ return { checkout: dirname(dir), file };
222
231
  } catch (e) {
223
- if (e.code === "ENOENT") return null;
232
+ if (e.code === "ENOENT") return { checkout: dirname(dir), file: null };
224
233
  die(`could not look for the ledger ${file}: ${e.message}`);
225
234
  }
226
235
  }
227
236
 
237
+ // The linked worktrees under `checkout`'s `.worktrees/`, read the way
238
+ // stranded.mjs reads them. `paths` is every path git lists; `home` is that
239
+ // directory's realpath, or null when it does not exist, so no worktree sits
240
+ // inside it. `{unknown}` when git's registry cannot be read or the directory
241
+ // cannot be resolved; what stands inside it is read in claimWorktree(). An
242
+ // unknown is never read as no worktree.
243
+ function worktreeListing(checkout) {
244
+ const r = spawnSync("git", ["worktree", "list", "--porcelain", "-z"], {
245
+ cwd: checkout, encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv(),
246
+ });
247
+ if (r.error || r.status !== 0) return { unknown: `git worktree list failed (${how(r)})` };
248
+ const paths = r.stdout.split("\0").filter((f) => f.startsWith("worktree ")).map((f) => f.slice("worktree ".length));
249
+ const dir = join(checkout, ".worktrees");
250
+ try {
251
+ return { paths, home: realpathSync(dir) };
252
+ } catch (e) {
253
+ if (e.code === "ENOENT") return { paths, home: null };
254
+ return { unknown: `cannot resolve ${dir} (${e.code ?? e.message})` };
255
+ }
256
+ }
257
+
258
+ // Whether a claim worktree stands for issue `n`: a listed worktree directly under
259
+ // `.worktrees/` whose directory name names `n` as a whole segment, and whose
260
+ // directory is still there. `{stands}` is true or false; `{unknown}`
261
+ // when a candidate's presence cannot be told. A registration whose directory is
262
+ // gone stands for nothing. A directory under `.worktrees/` named for `n` that git
263
+ // does not list is an unknown, never none: git drops a worktree whose
264
+ // registration it cannot read — an unreadable `.git/worktrees/`, an empty
265
+ // `gitdir` file — from the list and still exits 0. The segment rule is
266
+ // stranded.mjs's, for a claim's own worktree.
267
+ function claimWorktree(listing, n) {
268
+ if (listing.unknown !== undefined) return { unknown: listing.unknown };
269
+ if (listing.home === null) return { stands: false };
270
+ const named = new RegExp(`(^|[/-])${n}([-/]|$)`);
271
+ for (const p of listing.paths) {
272
+ if (!named.test(basename(p))) continue;
273
+ try {
274
+ if (realpathSync(dirname(p)) !== listing.home) continue;
275
+ } catch (e) {
276
+ if (e.code === "ENOENT") continue;
277
+ return { unknown: `cannot resolve ${dirname(p)} (${e.code ?? e.message})` };
278
+ }
279
+ try {
280
+ statSync(p);
281
+ } catch (e) {
282
+ if (e.code === "ENOENT") continue;
283
+ return { unknown: `cannot tell whether ${p} exists (${e.code ?? e.message})` };
284
+ }
285
+ return { stands: true };
286
+ }
287
+ let names;
288
+ try {
289
+ names = readdirSync(listing.home);
290
+ } catch (e) {
291
+ if (e.code === "ENOENT") return { stands: false };
292
+ return { unknown: `cannot read ${listing.home} (${e.code ?? e.message})` };
293
+ }
294
+ const unlisted = names.find((name) => named.test(name));
295
+ if (unlisted !== undefined) return { unknown: `${join(listing.home, unlisted)} is there but git does not list it as a worktree` };
296
+ return { stands: false };
297
+ }
298
+
228
299
  // `{type, state}` per number GitHub answered (type "Issue" or "PullRequest",
229
300
  // or null for a number that names nothing), or `{unreachable}` for a number
230
301
  // that has no usable answer. GitHub resolves every alias it can and nulls the
@@ -285,7 +356,7 @@ function githubStates(numbers) {
285
356
  }
286
357
 
287
358
  // The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}]}`.
288
- function judgeRoot(root, names, live, now) {
359
+ function judgeRoot(root, names, live, now, listing) {
289
360
  const cutoff = now - RETENTION_MS;
290
361
  const remove = [];
291
362
  const kept = [];
@@ -406,6 +477,15 @@ function judgeRoot(root, names, live, now) {
406
477
  kept.push({ path, reason: `issue #${n} is OPEN and live ${holder} names it` });
407
478
  continue;
408
479
  }
480
+ const claim = claimWorktree(listing, n);
481
+ if (claim.unknown !== undefined) {
482
+ kept.push({ path, reason: `its claim worktree cannot be checked: ${claim.unknown}` });
483
+ continue;
484
+ }
485
+ if (claim.stands) {
486
+ kept.push({ path, reason: "claim worktree stands" });
487
+ continue;
488
+ }
409
489
  if (freshUnder(path, cutoff) === null) remove.push({ path, reason: `issue #${n} is OPEN, no live impl-${n} token, idle past 7 days` });
410
490
  else kept.push({ path, reason: `issue #${n} is OPEN; modified within 7 days` });
411
491
  }
@@ -530,7 +610,8 @@ function main() {
530
610
  failed.push({ path: dirname(root), error: e.message });
531
611
  }
532
612
  } else {
533
- ledger = ledgerFile();
613
+ const found = ledgerFile();
614
+ ledger = found.file;
534
615
  if (ledger === null && !afterRotate) die("no .fleet/ledger.md — without it no live member can hold its scratch, so nothing is reclaimed; pass --after-rotate only straight after `ledger.mjs rotate`");
535
616
  const live = ledger === null ? [] : liveNames(ledger);
536
617
  let names;
@@ -539,7 +620,8 @@ function main() {
539
620
  } catch (e) {
540
621
  die(`could not list --root ${root}: ${e.message}`);
541
622
  }
542
- ({ remove, kept } = judgeRoot(root, names, live, now));
623
+ const listing = worktreeListing(found.checkout);
624
+ ({ remove, kept } = judgeRoot(root, names, live, now, listing));
543
625
  }
544
626
 
545
627
  const removed = [];
@@ -109,7 +109,7 @@ export const SCHEMAS = {
109
109
  { verdict: { type: "string", enum: ["light", "heavy"] }, signal: str, ranBeforePr: { type: "boolean" } },
110
110
  ["object", "null"],
111
111
  ),
112
- bailCause: { type: ["string", "null"], enum: ["undecided", "fork", "hands", null] },
112
+ bailCause: { type: ["string", "null"], enum: ["undecided", "fork", "hands", "fixed", "covered", null] },
113
113
  bailDetail: { type: ["string", "null"] },
114
114
  confirmation: strings,
115
115
  }),
@@ -1079,23 +1079,18 @@ Each rule here is a judgement a driver stops for: answer it by the cause it name
1079
1079
  ### Relabel causes
1080
1080
 
1081
1081
  - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`
1082
- settles `impl-<N>=bailed` and demotes by cause:
1082
+ settles `impl-<N>=bailed` and acts by `bailCause`, never by parsing `bailDetail`; no cause opens a PR:
1083
1083
 
1084
- | Cause | Label |
1085
- |---|---|
1086
- | brief does not decide *what* to build | `needs-triage` |
1087
- | genuine fork — options named, none ruled | `ready-for-human` |
1088
- | needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
1084
+ | Cause | `bailCause` | `bailDetail` format | Issue action | Ledger |
1085
+ |---|---|---|---|---|
1086
+ | brief does not decide *what* to build | `undecided` | `<one line>` | relabel `needs-triage` | `=bailed` |
1087
+ | genuine fork — options named, none ruled | `fork` | `<options>` | relabel `ready-for-human` | `=bailed` |
1088
+ | needs human hands — external access, manual testing, judgment during the work | `hands` | `<cause>: <line>` | relabel `ready-for-human` | `=bailed` |
1089
+ | already fixed on main | `fixed` | `<sha> — <how origin/main's tree meets the acceptance>` | `verify-sha.sh main <sha>` first. Exit 0: close N with the `fixed` comment (quotes `bailDetail`), drop `ready-for-agent`, release the claim (drops `in-progress`); no label. Exit 1: relabel `needs-triage`, comment `<sha> not on origin/main`. Exit 2: `NEED`, N untouched. | `=bailed` |
1090
+ | covered by an open PR M | `covered` | `PR#M — <how M's diff meets N's acceptance>` | relabel `ready-for-human` with the `covered` comment: close N when M merges, or restore `ready-for-agent` if M closes unmerged. PR M's body is never edited. | `=bailed` |
1089
1091
 
1090
- The call relabels, comments the cause and releases the claim, then ticks:
1092
+ The call comments the cause and releases the claim — never when `fixed` neither closes nor relabels N — then ticks:
1091
1093
  the head the tick names next is a *different* ticket.
1092
- `needs-triage` routes back to `/triage`, which can return it as
1093
- `ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
1094
- brief that names no *what*.
1095
-
1096
- The same causes relabel an unclaimed ticket at the Pull (phase 1), where there
1097
- is no `in-progress` to drop — the causes and labels are one table, applied at
1098
- whichever point the ticket fails them.
1099
1094
 
1100
1095
  ### Resolving a finisher halt
1101
1096
 
@@ -1303,7 +1298,7 @@ owes beyond its call:
1303
1298
  and the tick prints no dispatch for it. The cockpit flags the PR
1304
1299
  `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand
1305
1300
  (**Resolving a finisher that died**, above), then run the tick.
1306
- - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`; the causes and the labels they take are under **Relabel causes**.
1301
+ - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`; the causes and the issue action each takes are under **Relabel causes**.
1307
1302
  - **A review result lands** → see the result file written (by you or by the
1308
1303
  runner — **Reviewers** says which, per harness), then
1309
1304
  `fleet-event.mjs review-result <pr> <path>`: a PR with survived or unverified findings prints as
@@ -2027,18 +2022,15 @@ age, reading which members are live off `.fleet/ledger.md`:
2027
2022
  sweep — its token names no PR. An OPEN PR's `pr<M>/` stays, all but its
2028
2023
  `run-*` roots idle past 7 days.
2029
2024
  - **`impl-<N>/`** goes once issue #N is CLOSED, or when it is OPEN, no live
2030
- `impl-<N>` token names it and nothing under it has changed in 7 days.
2025
+ `impl-<N>` token names it, no claim worktree under `.worktrees/` still stands
2026
+ for it, and nothing under it has changed in 7 days.
2031
2027
  - **Anything else at the root** — your own ad-hoc files included — goes
2032
2028
  once nothing under it has changed in 7 days and no live token's name
2033
2029
  appears in its name.
2034
2030
 
2035
- No ledger refuses this call (exit 2, nothing removed): mid-run there is
2036
- always one, so its absence is a fault to look at, never permission. A `gh`
2037
- that cannot answer keeps every PR- and ticket-keyed entry. It prints one
2038
- JSON receipt — `removed`, `kept` and `failed`, each entry with its reason —
2039
- and exits 0 even when a removal failed; record nothing on the ledger. The
2040
- review snapshot runs the same script as `--pr <N>` on its own PR's stale
2041
- `run-*` roots.
2031
+ The review snapshot runs the same script as `--pr <N>` on its own PR's stale
2032
+ `run-*` roots. What this sweep does with no ledger, or with a `gh` that cannot
2033
+ answer, is in references/phase-0.md, under **Reclaim scratch**.
2042
2034
 
2043
2035
  ### Release the claims that never became PRs — at end of run, and on drain
2044
2036
 
@@ -2341,17 +2333,6 @@ or even see it — `worktree-audit.sh`'s committed-vs-uncommitted split is exact
2341
2333
  what decides whether a replacement redoes or destroys work. Observed twice in
2342
2334
  one run.
2343
2335
 
2344
- **The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
2345
- That skill conditions its heavy-row process on the reader being a fleet member;
2346
- a solo reader settles the open design choices with its user before planning,
2347
- while a fleet member's `## Agent Brief` already is that settlement. A member
2348
- that takes itself for a solo session waits on a user to settle design — a user
2349
- no unattended member has, so it parks rather
2350
- than fails. Nothing else you carry says what the member is — an incidental
2351
- mention of the controller is not a statement that the reader is one of its
2352
- members. That skill keeps its condition, so a solo session still runs the
2353
- interactive path; this block is what puts a member on the fleet side of it.
2354
-
2355
2336
  A member that bails demotes nothing itself; demotion by cause is yours
2356
2337
  (**Implementer bails before implementing**).
2357
2338
 
@@ -2609,7 +2590,7 @@ Match the failure to its row in the table below and run that response; where the
2609
2590
  | Failure | Response |
2610
2591
  |---|---|
2611
2592
  | SHA not on expected branch | Flag, do not enqueue, report |
2612
- | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
2593
+ | Implementer bails before implementing | Act by the report's `bailCause` as the **Relabel causes** table says, then refill (phase 3) |
2613
2594
  | Implementer blocked or ambiguous *mid-implementation* | Free the slot, `ledger.mjs settle impl-<N> blocked`, leave `in-progress`, report — the ticket is not In flight and waits for a human; the row above is the pre-code bail, not this one |
2614
2595
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
2615
2596
  | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — a fix-applier or red-check fixer settles `failed` |
@@ -2,6 +2,7 @@
2
2
  arg line one line
3
3
  arg options options
4
4
  arg hands hands
5
+ arg detail detail
5
6
  ---
6
7
  ## kind: needs-triage
7
8
  *Relabelled by the fleet controller.* Pulled for implementation and
@@ -13,3 +14,11 @@ returned: the brief leaves a decision open. Open fork: <options>.
13
14
  ## kind: hands
14
15
  *Relabelled by the fleet controller.* Pulled for implementation and
15
16
  returned: needs human hands — <hands>: <one line>.
17
+ ## kind: covered
18
+ *Relabelled by the fleet controller.* Pulled for implementation and
19
+ returned: an open pull request already covers it — <detail>. Close this
20
+ issue when that pull request merges, or restore `ready-for-agent` if it
21
+ closes unmerged.
22
+ ## kind: fixed
23
+ *Closed by the fleet controller.* Pulled for implementation and found
24
+ already fixed on origin/main: <detail>.
@@ -265,6 +265,14 @@ as "no live token" — rotate's own verdict — where without it the script
265
265
  refuses. A ledger rotate did write is read as usual. Record nothing on the
266
266
  ledger and act on nothing in its receipt.
267
267
 
268
+ Without `--after-rotate` — the per-pass sweep **Reclaim scratch after each
269
+ merge pass** runs — no ledger refuses the call (exit 2, nothing removed):
270
+ mid-run there is always one, so its absence is a fault to look at, never
271
+ permission. A `gh` that cannot answer keeps every PR- and ticket-keyed entry.
272
+ It prints one JSON receipt — `removed`, `kept` and `failed`, each entry with
273
+ its reason — and exits 0 even when a removal failed; record nothing on the
274
+ ledger.
275
+
268
276
  Straight after that, the same step reclaims the other keys under the scratch parent:
269
277
  `~/.fleet/bin/fleet-run reclaim-scratch.mjs --siblings --root <scratch> --apply`. A key
270
278
  goes whole when nothing under it has changed in 7 days, and stays whole otherwise. The
@@ -390,6 +390,17 @@ own ticket** — one's acceptance criterion went unmet, and the other three left
390
390
  the named defect reachable by a sibling spelling. Every one was caught by
391
391
  review, at review cost, which runs 3-5x the implementation it checks.
392
392
 
393
+ **The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
394
+ That skill conditions its heavy-row process on the reader being a fleet member;
395
+ a solo reader settles the open design choices with its user before planning,
396
+ while a fleet member's `## Agent Brief` already is that settlement. A member
397
+ that takes itself for a solo session waits on a user to settle design — a user
398
+ no unattended member has, so it parks rather
399
+ than fails. Nothing else you carry says what the member is — an incidental
400
+ mention of the controller is not a statement that the reader is one of its
401
+ members. That skill keeps its condition, so a solo session still runs the
402
+ interactive path; this block is what puts a member on the fleet side of it.
403
+
393
404
  ## Default: In-flight bound 5
394
405
 
395
406
  **Default: In-flight bound 5, fixed for the run.** The level is set by load, not