@feigi/fleet-ctl 3.41.2 → 3.42.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.41.2",
3
+ "version": "3.42.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": {
@@ -437,8 +437,9 @@ export function liveOnLedger(rows, dispatched) {
437
437
 
438
438
  // A reviewer's runner name: `review-pr-<n>` for a PR's first, `-b`, `-c`, …
439
439
  // for each later one. The only runner names the grammar knows, so the only
440
- // ones a rotate retires; a launch under any other name retires nothing.
441
- const REVIEWER = /^review-pr-[1-9][0-9]*(-[b-z])?$/;
440
+ // ones a rotate retires; a launch under any other name retires nothing. The
441
+ // first group is the PR number the name is bound to.
442
+ export const REVIEWER = /^review-pr-([1-9][0-9]*)(-[b-z])?$/;
442
443
 
443
444
  /** Whether `name` is one a `## Retired` line may hold: a member's name or a
444
445
  * reviewer's, bare. */
@@ -0,0 +1,436 @@
1
+ #!/usr/bin/env node
2
+ // Reclaim: remove what a run left under its scratch root once nothing can
3
+ // still want it. Distinct from Reap, which authorizes on git's evidence, and
4
+ // from Release, which undoes a claim that never became a PR: Reclaim
5
+ // authorizes on GitHub state and on age.
6
+ //
7
+ // reclaim-scratch.mjs --root <abs> [--after-rotate] [--apply]
8
+ // reclaim-scratch.mjs --pr <N> --root <abs> [--apply]
9
+ //
10
+ // Dry run by default; `--apply` removes. `--root` is required, an absolute
11
+ // path to an existing directory: the controller passes the path
12
+ // scratch-root.mjs prints.
13
+ //
14
+ // THE ROOT SWEEP judges every entry directly under `--root`:
15
+ // pr<M>/, dispositions-fix-pr-<M>[-x].json
16
+ // removed when PR #M is MERGED or CLOSED on GitHub and no live
17
+ // ledger token names it — review-pr-<M>[-x], fix-pr-<M>[-x],
18
+ // finisher-pr-<M>[-x]. A live merge-bot-<n> token holds every one
19
+ // of them: a bot's token names no PR, and GitHub reads MERGED
20
+ // while the bot is still writing under pr<M>/merge-bot-<n>/. An
21
+ // OPEN PR's pr<M>/ is kept whole except its run-* roots, which
22
+ // follow the --pr rule below.
23
+ // impl-<N>/
24
+ // removed when issue #N is CLOSED, or OPEN with no live
25
+ // impl-<N>[-x] token and idle past the retention, so a bailed or
26
+ // released ticket's partition is not inherited by its next claim.
27
+ // anything else, and a keyed name whose number GitHub resolves to the
28
+ // other type (a pr<N> that is an issue, an impl-<N> that is a PR) or to
29
+ // nothing
30
+ // removed when idle past the retention and no live token's name
31
+ // appears in the entry's name.
32
+ // "Idle past the retention" is the newest mtime ANYWHERE under the entry
33
+ // older than 7 days — never the top-level mtime alone, which a write deep
34
+ // inside does not move. A directory that cannot be listed or searched counts
35
+ // its own mtime and is not descended into.
36
+ //
37
+ // The live tokens are `.fleet/ledger.md`'s, read through `ledger.mjs read`
38
+ // and ledger-grammar.mjs's liveOnLedger(), the file resolved by
39
+ // fleet-dir.mjs's fleetFile() from the cwd. An absent ledger REFUSES the root
40
+ // sweep, because nothing could then hold a live member's entry — unless
41
+ // `--after-rotate` is given: phase 0's rotate leaves no ledger behind when it
42
+ // carried nothing, so there an absent file is read as "no live token", which
43
+ // is rotate's own verdict. A ledger that is present is read as usual under
44
+ // either; only ENOENT is absence, and any other failure to read it refuses.
45
+ //
46
+ // GitHub is asked once per ≤100 numbers (`gh api graphql`, one aliased
47
+ // issueOrPullRequest per number, pr<N> and impl-<N> together). A number with
48
+ // no usable answer — a failed lookup, a partial failure included — keeps every
49
+ // keyed entry that names it, with that reason; the age rule still runs on
50
+ // unkeyed entries. A keyed entry is never judged by the ledger or by mtime
51
+ // alone in GitHub's place.
52
+ //
53
+ // `--pr <N>` MODE is the review snapshot's prune: every directory
54
+ // `<root>/pr<N>/run-*` idle past the retention is removed, and nothing else
55
+ // is looked at — no ledger, no gh (a live review's own run root is seconds
56
+ // old), no sibling under pr<N>/.
57
+ //
58
+ // EVERY REMOVAL, in either mode, goes through REMOVE below: owner rwx
59
+ // restored, darwin's user-immutable and append-only flags cleared where
60
+ // `chflags` exists, then `rm -rf` — so a fixture that dropped its own read bit
61
+ // or flagged a file cannot wedge it. Removal is best-effort per entry: a
62
+ // failure lands in `failed[]` and the sweep continues.
63
+ //
64
+ // Prints ONE JSON line on stdout once the sweep is done:
65
+ // {"applied":<bool>,"ledger":<abs path|null>,"removed":[{"path","reason"}],
66
+ // "kept":[{"path","reason"}],"failed":[{"path","error"}]}
67
+ // `ledger` is the file read, or null when none was (`--pr` mode, or
68
+ // `--after-rotate` with no file) — so "never read" stays distinct from "read
69
+ // and found empty". A dry run prints the same receipt with "applied":false,
70
+ // `removed` naming what --apply would remove.
71
+ // Exit 0 whenever the receipt is printed, failures included; 2 for a refused
72
+ // invocation — bad arguments, no --root, a root that is not a directory, a
73
+ // root sweep with no ledger and no --after-rotate, a ledger that cannot be
74
+ // read for any reason other than ENOENT. Nothing is removed before a refusal.
75
+
76
+ import { spawnSync } from "node:child_process";
77
+ import { lstatSync, readdirSync, statSync } from "node:fs";
78
+ import { dirname, isAbsolute, join, resolve } from "node:path";
79
+ import { fileURLToPath } from "node:url";
80
+ import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
81
+ import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
82
+ import { gitEnv } from "./git-env.mjs";
83
+ import { isCLI } from "./is-cli.mjs";
84
+ import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
85
+
86
+ const NAME = "reclaim-scratch";
87
+ const die = makeDie(NAME);
88
+ const DAY_MS = 24 * 60 * 60 * 1000;
89
+ export const RETENTION_MS = 7 * DAY_MS;
90
+ const BATCH = 100;
91
+ const GH_TIMEOUT_MS = 30_000;
92
+ const MAX_BUFFER = 64 * 1024 * 1024;
93
+
94
+ // The one removal sequence. `$1` is the entry. A symlink entry is unlinked
95
+ // before anything else runs, so no chmod or chflags ever sees it: whether a
96
+ // recursive chmod dereferences a link given as its operand differs between
97
+ // BSD and GNU, and either would change the mode or flags of a target outside
98
+ // the entry being removed. Links met inside a directory are left to `rm`,
99
+ // which unlinks them without following. `chmod -R` fails
100
+ // on a flagged directory, and `chflags -R` cannot read a mode-000 directory it
101
+ // has just unflagged, so when the first pass fails each directory's flag and
102
+ // mode come off together, top-down, before anything inside it is read.
103
+ const REMOVE = [
104
+ 'd=$1',
105
+ 'if [ -L "$d" ]; then rm -f "$d"; exit $?; fi',
106
+ 'chmod -R u+rwx "$d" 2>/dev/null; m=$?',
107
+ 'if command -v chflags >/dev/null 2>&1; then',
108
+ ' [ $m -eq 0 ] || { chflags nouchg,nouappnd "$d"; chmod u+rwx "$d"; find "$d" -type d -exec chflags nouchg,nouappnd {} ";" -exec chmod u+rwx {} ";"; } 2>/dev/null',
109
+ ' chflags -R nouchg,nouappnd "$d" 2>/dev/null',
110
+ 'fi',
111
+ 'rm -rf "$d"',
112
+ ].join("\n");
113
+
114
+ const PR_ENTRY = /^pr([1-9][0-9]*)$/;
115
+ const IMPL_ENTRY = /^impl-([1-9][0-9]*)$/;
116
+ const DISPOSITIONS_ENTRY = /^dispositions-fix-pr-([1-9][0-9]*)(?:-[a-z])?\.json$/;
117
+ const RUN_ROOT = /^run-/;
118
+
119
+ function how(r) {
120
+ if (r.error) return r.error.code ?? r.error.message;
121
+ if (r.signal) return `killed by ${r.signal}`;
122
+ const said = String(r.stderr ?? "").trim().split("\n").at(-1);
123
+ return said ? `exit ${r.status}: ${said}` : `exit ${r.status}`;
124
+ }
125
+
126
+ /** The path of something under `path` (itself included) modified at or after
127
+ * `cutoff`, or null when everything is older. Symlinks are not followed. A
128
+ * directory that cannot be listed counts its own mtime only, and so does one
129
+ * that can be listed but not searched: an entry inside it whose lstat is
130
+ * refused is skipped, its parent's mtime already counted. */
131
+ export function freshUnder(path, cutoff) {
132
+ const stack = [path];
133
+ while (stack.length) {
134
+ const p = stack.pop();
135
+ let st;
136
+ try {
137
+ st = lstatSync(p);
138
+ } catch (e) {
139
+ if (e.code === "ENOENT" || e.code === "EACCES" || e.code === "EPERM") continue;
140
+ throw e;
141
+ }
142
+ if (st.mtimeMs >= cutoff) return p;
143
+ if (!st.isDirectory()) continue;
144
+ let names;
145
+ try {
146
+ names = readdirSync(p);
147
+ } catch (e) {
148
+ if (e.code === "EACCES" || e.code === "EPERM" || e.code === "ENOENT") continue;
149
+ throw e;
150
+ }
151
+ for (const n of names) stack.push(join(p, n));
152
+ }
153
+ return null;
154
+ }
155
+
156
+ /** Remove `path` through REMOVE; null on success, else the reason. */
157
+ export function removeEntry(path) {
158
+ const r = spawnSync("sh", ["-c", REMOVE, "sh", path], { encoding: "utf8" });
159
+ return r.error || r.status !== 0 ? how(r) : null;
160
+ }
161
+
162
+ // The live tokens the ledger holds, by name, read through `ledger.mjs read`
163
+ // so the ledger keeps one parser. `--file` names it outright, so the read
164
+ // resolves no workspace and runs no git.
165
+ function liveNames(file) {
166
+ const script = join(dirname(fileURLToPath(import.meta.url)), "ledger.mjs");
167
+ const r = spawnSync(process.execPath, [script, "--file", file, "read"], { encoding: "utf8", maxBuffer: MAX_BUFFER });
168
+ if (r.error || r.status !== 0) die(`ledger.mjs read ${file} failed (${how(r)}) — which members are live is unknown, so nothing is reclaimed`);
169
+ let d;
170
+ try {
171
+ d = JSON.parse(r.stdout);
172
+ } catch (e) {
173
+ die(`could not parse ledger.mjs read output: ${e.message}`);
174
+ }
175
+ const strings = (xs) => Array.isArray(xs) && xs.every((x) => typeof x === "string");
176
+ if (!d || !strings(d.rows) || !strings(d.dispatched)) die("ledger.mjs read returned no {rows, dispatched}");
177
+ return liveOnLedger(d.rows, d.dispatched).tokens.map((t) => t.name);
178
+ }
179
+
180
+ // The ledger file, or null when it is absent. Only ENOENT is absence; a
181
+ // workspace that cannot be resolved, or a path that cannot be looked up,
182
+ // refuses. `lstat`, so a dangling symlink is a ledger that cannot be read.
183
+ function ledgerFile() {
184
+ let file;
185
+ try {
186
+ file = fleetFile("ledger.md");
187
+ } catch (e) {
188
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
189
+ die(`${e.message} — the ledger cannot be found, so which members are live is unknown`);
190
+ }
191
+ try {
192
+ lstatSync(file);
193
+ return file;
194
+ } catch (e) {
195
+ if (e.code === "ENOENT") return null;
196
+ die(`could not look for the ledger ${file}: ${e.message}`);
197
+ }
198
+ }
199
+
200
+ // `{type, state}` per number GitHub answered (type "Issue" or "PullRequest",
201
+ // or null for a number that names nothing), or `{unreachable}` for a number
202
+ // that has no usable answer. GitHub resolves every alias it can and nulls the
203
+ // rest, and gh exits 1 with the whole body, so a body carrying an object
204
+ // `data.repository` is read alias by alias at any exit status. An alias is
205
+ // answered by a node, or by null with a NOT_FOUND error naming it — GitHub's
206
+ // own "this number names nothing". Any other error naming an alias, a null
207
+ // no NOT_FOUND explains, and an error naming no alias (it may belong to any
208
+ // of the batch) leave the number unreachable: a failed lookup is not an
209
+ // answer.
210
+ function githubStates(numbers) {
211
+ const out = new Map();
212
+ for (let i = 0; i < numbers.length; i += BATCH) {
213
+ const batch = numbers.slice(i, i + BATCH);
214
+ const fields = batch.map((n) => `n${n}:issueOrPullRequest(number:${n}){__typename ... on Issue{state} ... on PullRequest{state}}`).join(" ");
215
+ const r = spawnSync("gh", ["api", "graphql", "-F", "owner={owner}", "-F", "name={repo}",
216
+ "-f", `query=query($owner:String!,$name:String!){repository(owner:$owner,name:$name){${fields}}}`], {
217
+ encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv({ GH_REPO: "" }),
218
+ });
219
+ let body;
220
+ let unparseable;
221
+ try {
222
+ body = JSON.parse(r.stdout);
223
+ } catch (e) {
224
+ body = undefined;
225
+ if (r.status === 0) unparseable = e.message;
226
+ }
227
+ const repo = body?.data?.repository;
228
+ const errors = body?.errors ?? [];
229
+ const answered = repo !== null && typeof repo === "object" && !Array.isArray(repo) && Array.isArray(errors);
230
+ const nothing = new Set();
231
+ const refused = new Map();
232
+ let batchWide;
233
+ if (answered) {
234
+ for (const e of errors) {
235
+ const path = e?.path;
236
+ const alias = Array.isArray(path) && path[0] === "repository" && typeof path[1] === "string" ? path[1] : null;
237
+ const said = `${e?.type ?? "error"}${e?.message ? `: ${e.message}` : ""}`;
238
+ if (alias === null) batchWide ??= said;
239
+ else if (e.type === "NOT_FOUND" && path.length === 2) nothing.add(alias);
240
+ else refused.set(alias, said);
241
+ }
242
+ }
243
+ for (const n of batch) {
244
+ const alias = `n${n}`;
245
+ const gone = (why) => out.set(n, { unreachable: `gh api graphql gave no answer for #${n} (${why})` });
246
+ if (!answered) gone(unparseable === undefined ? how(r) : `${how(r)}: unparseable body: ${unparseable}`);
247
+ else if (refused.has(alias)) gone(refused.get(alias));
248
+ else if (batchWide !== undefined) gone(batchWide);
249
+ else if (!Object.hasOwn(repo, alias)) gone(how(r));
250
+ else if (repo[alias] === null) {
251
+ if (nothing.has(alias)) out.set(n, { type: null });
252
+ else gone("null with no NOT_FOUND error");
253
+ } else out.set(n, { type: repo[alias].__typename, state: String(repo[alias].state).toUpperCase() });
254
+ }
255
+ }
256
+ return out;
257
+ }
258
+
259
+ // The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}]}`.
260
+ function judgeRoot(root, names, live, now) {
261
+ const cutoff = now - RETENTION_MS;
262
+ const remove = [];
263
+ const kept = [];
264
+ const liveMembers = live.map(parseMember).filter((m) => m !== null);
265
+ const bot = liveMembers.find((m) => m.family === "merge-bot");
266
+ const prHolder = (n) => live.find((name) => {
267
+ const m = parseMember(name);
268
+ if (m !== null) return (m.family === "fix-pr" || m.family === "finisher-pr") && m.number === n;
269
+ const r = REVIEWER.exec(name);
270
+ return r !== null && Number(r[1]) === n;
271
+ });
272
+ const implHolder = (n) => liveMembers.find((m) => m.family === "impl" && m.number === n)?.name;
273
+
274
+ const byAge = (path, name, young) => {
275
+ const holder = live.find((t) => name.includes(t));
276
+ if (holder !== undefined) return kept.push({ path, reason: `live token ${holder} appears in its name` });
277
+ const fresh = freshUnder(path, cutoff);
278
+ if (fresh === null) return remove.push({ path, reason: "idle past 7 days" });
279
+ kept.push({ path, reason: young ? `${young}; modified within 7 days` : "modified within 7 days" });
280
+ };
281
+
282
+ const keyed = [];
283
+ const numbers = new Set();
284
+ for (const name of names) {
285
+ const path = join(root, name);
286
+ let m;
287
+ if ((m = PR_ENTRY.exec(name))) keyed.push({ path, name, kind: "pr", n: Number(m[1]) });
288
+ else if ((m = IMPL_ENTRY.exec(name))) keyed.push({ path, name, kind: "impl", n: Number(m[1]) });
289
+ else if ((m = DISPOSITIONS_ENTRY.exec(name))) keyed.push({ path, name, kind: "pr", n: Number(m[1]) });
290
+ else {
291
+ byAge(path, name, null);
292
+ continue;
293
+ }
294
+ numbers.add(keyed.at(-1).n);
295
+ }
296
+ const states = githubStates([...numbers].sort((a, b) => a - b));
297
+
298
+ for (const { path, name, kind, n } of keyed) {
299
+ const s = states.get(n);
300
+ if (s.unreachable) {
301
+ kept.push({ path, reason: s.unreachable });
302
+ continue;
303
+ }
304
+ const want = kind === "pr" ? "PullRequest" : "Issue";
305
+ if (s.type !== want) {
306
+ byAge(path, name, s.type === null ? `#${n} names nothing on GitHub` : `#${n} is a ${s.type}, not ${kind === "pr" ? "a pull request" : "an issue"}`);
307
+ continue;
308
+ }
309
+ if (kind === "pr") {
310
+ if (bot !== undefined) {
311
+ kept.push({ path, reason: `live ${bot.name} holds every pr<N>` });
312
+ continue;
313
+ }
314
+ if (s.state === "OPEN") {
315
+ kept.push({ path, reason: `PR #${n} is OPEN` });
316
+ if (name === `pr${n}`) {
317
+ try {
318
+ remove.push(...staleRunRoots(path, cutoff, kept));
319
+ } catch (e) {
320
+ kept.push({ path, reason: `its run-* roots cannot be listed: ${e.message}` });
321
+ }
322
+ }
323
+ continue;
324
+ }
325
+ if (s.state !== "MERGED" && s.state !== "CLOSED") {
326
+ kept.push({ path, reason: `PR #${n} has an unrecognised state ${s.state}` });
327
+ continue;
328
+ }
329
+ const holder = prHolder(n);
330
+ if (holder !== undefined) kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
331
+ else remove.push({ path, reason: `PR #${n} is ${s.state}` });
332
+ continue;
333
+ }
334
+ if (s.state === "CLOSED") {
335
+ remove.push({ path, reason: `issue #${n} is CLOSED` });
336
+ continue;
337
+ }
338
+ const holder = implHolder(n);
339
+ if (holder !== undefined) {
340
+ kept.push({ path, reason: `issue #${n} is OPEN and live ${holder} names it` });
341
+ continue;
342
+ }
343
+ if (freshUnder(path, cutoff) === null) remove.push({ path, reason: `issue #${n} is OPEN, no live impl-${n} token, idle past 7 days` });
344
+ else kept.push({ path, reason: `issue #${n} is OPEN; modified within 7 days` });
345
+ }
346
+ return { remove, kept };
347
+ }
348
+
349
+ // The run-* directories directly under `parent` idle past the retention, as
350
+ // removals; young ones are pushed onto `kept`. An absent parent holds none; one
351
+ // that cannot be listed throws.
352
+ function staleRunRoots(parent, cutoff, kept) {
353
+ let entries;
354
+ try {
355
+ entries = readdirSync(parent, { withFileTypes: true });
356
+ } catch (e) {
357
+ if (e.code === "ENOENT" || e.code === "ENOTDIR") return [];
358
+ throw e;
359
+ }
360
+ const remove = [];
361
+ for (const e of entries) {
362
+ if (!e.isDirectory() || !RUN_ROOT.test(e.name)) continue;
363
+ const path = join(parent, e.name);
364
+ if (freshUnder(path, cutoff) === null) remove.push({ path, reason: "run root idle past 7 days" });
365
+ else kept.push({ path, reason: "run root modified within 7 days" });
366
+ }
367
+ return remove;
368
+ }
369
+
370
+ function main() {
371
+ const { arg, has, sweep, stray } = defineFlags(die, {
372
+ flags: { root: "value", pr: "value", "after-rotate": "bool", apply: "bool" },
373
+ });
374
+ sweep();
375
+ stray();
376
+ const rootArg = arg("root");
377
+ const pr = arg("pr");
378
+ const afterRotate = has("after-rotate");
379
+ const apply = has("apply");
380
+ const usage = "usage: reclaim-scratch.mjs --root <abs> [--after-rotate] [--apply] | --pr <N> --root <abs> [--apply]";
381
+ if (rootArg === null) die(`--root is required — ${usage}`);
382
+ if (!isAbsolute(rootArg)) die(`--root must be an absolute path, got ${JSON.stringify(rootArg)}`);
383
+ if (pr !== null && !isDigits(pr)) die(`--pr must be a PR number, got ${JSON.stringify(pr)}`);
384
+ if (pr !== null && afterRotate) die("--after-rotate is the root sweep's; --pr reads no ledger");
385
+ const root = resolve(rootArg);
386
+ try {
387
+ if (!statSync(root).isDirectory()) die(`--root ${root} is not a directory`);
388
+ } catch (e) {
389
+ die(`--root ${root} is not a directory: ${e.message}`);
390
+ }
391
+
392
+ const now = Date.now();
393
+ let ledger = null;
394
+ let remove;
395
+ let kept = [];
396
+ const failed = [];
397
+ if (pr !== null) {
398
+ const parent = join(root, `pr${Number(pr)}`);
399
+ try {
400
+ remove = staleRunRoots(parent, now - RETENTION_MS, kept);
401
+ } catch (e) {
402
+ remove = [];
403
+ failed.push({ path: parent, error: e.message });
404
+ }
405
+ } else {
406
+ ledger = ledgerFile();
407
+ 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`");
408
+ const live = ledger === null ? [] : liveNames(ledger);
409
+ let names;
410
+ try {
411
+ names = readdirSync(root).sort();
412
+ } catch (e) {
413
+ die(`could not list --root ${root}: ${e.message}`);
414
+ }
415
+ ({ remove, kept } = judgeRoot(root, names, live, now));
416
+ }
417
+
418
+ const removed = [];
419
+ for (const entry of remove) {
420
+ if (!apply) {
421
+ removed.push(entry);
422
+ continue;
423
+ }
424
+ let error;
425
+ try {
426
+ error = removeEntry(entry.path);
427
+ } catch (e) {
428
+ error = e.message;
429
+ }
430
+ if (error === null) removed.push(entry);
431
+ else failed.push({ path: entry.path, error });
432
+ }
433
+ writeAll(1, `${JSON.stringify({ applied: apply, ledger, removed, kept, failed })}\n`);
434
+ }
435
+
436
+ if (isCLI(import.meta.url)) main();
@@ -692,8 +692,9 @@ export function runnerPrRefusal(pr) {
692
692
  // `/pr${pr}` to the scratch it is given — so a scratch whose last component
693
693
  // is already `pr` plus digits is a caller that partitioned too, and its run
694
694
  // roots would nest at `<root>/pr<N>/pr<N>/run-*`, below the snapshot prompt's
695
- // `find <root>/pr<N> -maxdepth 1` prune. Refused whatever the digits, never
696
- // coerced: stripping the suffix would guess which directory the caller meant.
695
+ // prune, which looks only at the run-* directories directly under `pr<N>/`.
696
+ // Refused whatever the digits, never coerced: stripping the suffix would
697
+ // guess which directory the caller meant.
697
698
  //
698
699
  // "Last component" is the one the filesystem resolves, not the last text in
699
700
  // the string: `.` segments and repeated or trailing slashes are collapsed
@@ -841,7 +842,7 @@ export async function runReview(host, args) {
841
842
  mkdir -p "${runRootParent}" || { echo SNAPSHOT_RUNROOT_FAILED; exit 1; }
842
843
  RUN=$(mktemp -d "${runRootPrefix}XXXXXXXX") || { echo SNAPSHOT_RUNROOT_FAILED; exit 1; }
843
844
  echo SNAPSHOT_RUN_ROOT="$RUN"
844
- find "${runRootParent}" -maxdepth 1 -type d -name 'run-*' -mtime +7 -exec sh -c 'rc=0; ph="{""}"; for d; do chmod -R u+rwx "$d" 2>/dev/null; m=$?; if command -v chflags >/dev/null 2>&1; then [ $m -eq 0 ] || { chflags nouchg,nouappnd "$d"; chmod u+rwx "$d"; find "$d" -type d -exec chflags nouchg,nouappnd "$ph" ";" -exec chmod u+rwx "$ph" ";"; }; chflags -R nouchg,nouappnd "$d" 2>/dev/null; fi; rm -rf "$d" || rc=1; done; exit $rc' sh {} + || echo SNAPSHOT_PRUNE_FAILED
845
+ ~/.fleet/bin/fleet-run reclaim-scratch.mjs --pr ${pr} --root "${scratch}" --apply | grep -qF '"failed":[]' || echo SNAPSHOT_PRUNE_FAILED
845
846
  SHA=$(git -C ${worktree} rev-parse --short HEAD) || { echo SNAPSHOT_REVPARSE_FAILED; exit 1; }
846
847
  SNAP="$RUN/snapshot-$SHA"
847
848
  echo SNAPSHOT_DEST="$SNAP"
@@ -473,6 +473,17 @@ phase, or in any later one, asks the maintainer which tickets to take.
473
473
  tick, beat or ledger write, each of which writes a mark the fallback reads. Older
474
474
  archives, hand-named ones included, are left alone.
475
475
 
476
+ **Reclaim scratch straight after the rotation — every run.**
477
+ `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch>
478
+ --after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
479
+ so a run that merges nothing still reclaims the previous run's leftovers
480
+ (**Reclaim scratch after each merge pass** says what it removes).
481
+ `--after-rotate` goes on this call always and on no other: rotate leaves
482
+ no ledger behind when it carried nothing, and the flag reads that absence
483
+ as "no live token" — rotate's own verdict — where without it the script
484
+ refuses. A ledger rotate did write is read as usual. Record nothing on the
485
+ ledger and act on nothing in its receipt.
486
+
476
487
  **Derive the Recipe — the Recipe derivation step — before the fold-in below
477
488
  and before the first claim.** Every claim runs this repository's Install
478
489
  step and bakes its Test entrypoint into the member's runner, and every
@@ -1693,7 +1704,7 @@ ticket's line — never a hand edit.
1693
1704
  | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1694
1705
  | Label seen (persistent Monitor) | nothing to record |
1695
1706
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1696
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1707
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`; `reclaim-scratch.mjs --root <scratch> --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1697
1708
  | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1698
1709
  | Heartbeat | nothing to record |
1699
1710
 
@@ -1750,8 +1761,9 @@ owes beyond its row:
1750
1761
  into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
1751
1762
  and leaves nothing in the repo, so the row is the only place the tick can read
1752
1763
  it from — settle `merge-bot-<n>=done`, reap merged branches and worktrees with
1753
- `reap.sh --apply` (below) — always, even when the pass merged nothing — and
1754
- then run the tick. A label that landed at the last moment reads `DISPATCH
1764
+ `reap.sh --apply` (below) — always, even when the pass merged nothing — then
1765
+ reclaim their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1766
+ (below), and then run the tick. A label that landed at the last moment reads `DISPATCH
1755
1767
  merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
1756
1768
  on a conflict needs no record from you — the bot already appended
1757
1769
  `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
@@ -3624,6 +3636,33 @@ a row without a terminal state means someone may still be in that worktree, and
3624
3636
  the dirty check does not see a member that committed but has not pushed.
3625
3637
  See references/reaping.md.
3626
3638
 
3639
+ ### Reclaim scratch after each merge pass
3640
+
3641
+ Right after `reap.sh --apply`, every pass:
3642
+ `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch> --apply`,
3643
+ `<scratch>` the path `scratch-root.mjs` prints. Reap authorizes on git's
3644
+ evidence and never removes scratch; Reclaim authorizes on GitHub state and
3645
+ age, reading which members are live off `.fleet/ledger.md`:
3646
+
3647
+ - **`pr<M>/` and `dispositions-fix-pr-<M>*.json`** go once PR #M is MERGED
3648
+ or CLOSED and no live `review-pr-<M>`, `fix-pr-<M>` or `finisher-pr-<M>`
3649
+ token names it. A live `merge-bot-<n>` holds every one of them for that
3650
+ sweep — its token names no PR. An OPEN PR's `pr<M>/` stays, all but its
3651
+ `run-*` roots idle past 7 days.
3652
+ - **`impl-<N>/`** goes once issue #N is CLOSED, or when it is OPEN, no live
3653
+ `impl-<N>` token names it and nothing under it has changed in 7 days.
3654
+ - **Anything else at the root** — your own ad-hoc files included — goes
3655
+ once nothing under it has changed in 7 days and no live token's name
3656
+ appears in its name.
3657
+
3658
+ No ledger refuses this call (exit 2, nothing removed): mid-run there is
3659
+ always one, so its absence is a fault to look at, never permission. A `gh`
3660
+ that cannot answer keeps every PR- and ticket-keyed entry. It prints one
3661
+ JSON receipt — `removed`, `kept` and `failed`, each entry with its reason —
3662
+ and exits 0 even when a removal failed; record nothing on the ledger. The
3663
+ review snapshot runs the same script as `--pr <N>` on its own PR's stale
3664
+ `run-*` roots.
3665
+
3627
3666
  ### Release the claims that never became PRs — at end of run, and on drain
3628
3667
 
3629
3668
  Phase 1 is serial and claims ahead of dispatch, so a ticket can be legitimately