@feigi/fleet-ctl 3.132.2 → 3.133.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.132.2",
3
+ "version": "3.133.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": {
@@ -23,8 +23,16 @@
23
23
  // stdout: a missing, unknown or relative argument, a template that carries a
24
24
  // placeholder it never declared or no text at all for the kind, a leftover
25
25
  // declared placeholder in the output, a ticket the ledger names whose saved
26
- // issue file is missing or unreadable, or instruments.sh answering anything
27
- // but 0.
26
+ // issue file is missing or unreadable, an evicted worktree (below), or
27
+ // instruments.sh answering anything but 0.
28
+ //
29
+ // AN EVICTED WORKTREE. `render implementer` and `render fix-applier`, every
30
+ // kind, refuse a `--worktree` that carries evict.mjs's mark, naming the
31
+ // restore command: those members run code in the tree, and an evicted one has
32
+ // no installed dependencies. A worktree whose mark cannot be looked for
33
+ // refuses too; one that does not exist carries none. `render review-runner`
34
+ // and `render finisher` read no mark: the review works in its own snapshot,
35
+ // the finisher in its own detached tree.
28
36
  //
29
37
  // INSTRUMENTS. After the command line has parsed and before anything is
30
38
  // validated or rendered, instruments.sh runs from the main checkout — the
@@ -82,10 +90,11 @@
82
90
 
83
91
  import { spawnSync } from "node:child_process";
84
92
  import { createHash } from "node:crypto";
85
- import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
93
+ import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
86
94
  import { dirname, isAbsolute, join } from "node:path";
87
95
  import { fileURLToPath } from "node:url";
88
96
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
97
+ import { evictionMark, restoreCommand } from "./evict-mark.mjs";
89
98
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
90
99
  import { gitEnv } from "./git-env.mjs";
91
100
  import { ROWS, ledgerSection, memberTokens } from "./ledger-grammar.mjs";
@@ -241,6 +250,25 @@ function runInstruments() {
241
250
  die(`instruments.sh refused: ${verdict}${said ? ` — ${said}` : ""}`);
242
251
  }
243
252
 
253
+ // --- the evicted worktree ----------------------------------------------------
254
+
255
+ // The roles whose member runs code in its `--worktree`.
256
+ const RUNS_IN_TREE = ["implementer", "fix-applier"];
257
+
258
+ // Why a brief for `tree` is refused (AN EVICTED WORKTREE above), or null.
259
+ function evictedRefusal(tree) {
260
+ try {
261
+ statSync(tree);
262
+ } catch (e) {
263
+ if (e.code === "ENOENT") return null;
264
+ return `cannot tell whether ${tree} is evicted (${e.code ?? e.message})`;
265
+ }
266
+ const mark = evictionMark(tree);
267
+ if (mark.unknown !== undefined) return `cannot tell whether ${tree} is evicted: ${mark.unknown}`;
268
+ if (!mark.marked) return null;
269
+ return `${tree} is evicted — its installed dependencies are gone, so no member runs code there until it is restored: run \`${restoreCommand(tree)}\`, then render again`;
270
+ }
271
+
244
272
  // --- main --------------------------------------------------------------------
245
273
 
246
274
  const argv = process.argv.slice(2);
@@ -297,6 +325,12 @@ for (const a of required) {
297
325
  values.set(a.placeholder, value);
298
326
  }
299
327
 
328
+ const tree = required.find((a) => a.flag === "worktree");
329
+ if (RUNS_IN_TREE.includes(role) && tree !== undefined) {
330
+ const refusal = evictedRefusal(values.get(tree.placeholder));
331
+ if (refusal !== null) die(refusal);
332
+ }
333
+
300
334
  // THE TICKET, once every argument has passed: only for a kind whose text
301
335
  // carries the placeholder, found by that kind's own --pr and --scratch.
302
336
  const carriesTicket = template.ticket !== null && body.includes(`<${template.ticket}>`);
@@ -0,0 +1,62 @@
1
+ // The mark an Evict leaves on a claim tree, and the restore time a restore
2
+ // leaves beside it, both files in the tree's git admin dir: evict.mjs writes
3
+ // and reads them, and dispatch-prompt.mjs reads the mark before it renders a
4
+ // brief for a member that runs code in the tree. A module of its own so the
5
+ // renderer reads the mark without loading the sweep.
6
+ //
7
+ // The admin dir is the one `git -C <tree> rev-parse --absolute-git-dir`
8
+ // names, asked only once `<tree>/.git` is there: without it git walks up and
9
+ // answers for the enclosing repository, whose admin dir is not the tree's.
10
+
11
+ import { spawnSync } from "node:child_process";
12
+ import { lstatSync } from "node:fs";
13
+ import { join } from "node:path";
14
+ import { gitEnv } from "./git-env.mjs";
15
+
16
+ export const EVICTED = "fleet-evicted";
17
+ export const RESTORED = "fleet-restored";
18
+ const GIT_TIMEOUT_MS = 30_000;
19
+
20
+ // A path outside the plain charset is single-quoted, its own quotes closed,
21
+ // escaped and reopened, so a tree with a space in its path stays one word.
22
+ const shellWord = (s) => (/^[\w/.@%+=:,-]+$/.test(s) ? s : `'${s.replaceAll("'", "'\\''")}'`);
23
+
24
+ /** The command that restores an evicted tree, as the controller runs it. */
25
+ export const restoreCommand = (tree) => `~/.fleet/bin/fleet-run evict.mjs --restore ${shellWord(tree)} --apply`;
26
+
27
+ /** Why a spawnSync result failed, in one phrase: its error, its signal, or its exit and last stderr line. */
28
+ export const how = (r) => {
29
+ if (r.error) return r.error.code ?? r.error.message;
30
+ if (r.signal) return `killed by ${r.signal}`;
31
+ const said = String(r.stderr ?? "").trim().split("\n").at(-1);
32
+ return said ? `exit ${r.status}: ${said}` : `exit ${r.status}`;
33
+ };
34
+
35
+ /** `{dir}`, the tree's git admin dir, or `{unknown}`, why it cannot be told. */
36
+ export function adminDir(tree) {
37
+ try {
38
+ lstatSync(join(tree, ".git"));
39
+ } catch (e) {
40
+ return { unknown: `cannot read ${join(tree, ".git")} (${e.code ?? e.message}) — git would answer for the enclosing repository` };
41
+ }
42
+ const r = spawnSync("git", ["-C", tree, "rev-parse", "--absolute-git-dir"], {
43
+ encoding: "utf8", timeout: GIT_TIMEOUT_MS, env: gitEnv(),
44
+ });
45
+ const dir = String(r.stdout ?? "").replace(/\n$/, "");
46
+ if (r.error || r.status !== 0 || dir === "") return { unknown: `git rev-parse --absolute-git-dir in ${tree} failed (${how(r)})` };
47
+ return { dir };
48
+ }
49
+
50
+ /** `{marked, dir}` for a tree whose admin dir can be read, else `{unknown}`. */
51
+ export function evictionMark(tree) {
52
+ const admin = adminDir(tree);
53
+ if (admin.unknown !== undefined) return admin;
54
+ const mark = join(admin.dir, EVICTED);
55
+ try {
56
+ lstatSync(mark);
57
+ return { marked: true, dir: admin.dir };
58
+ } catch (e) {
59
+ if (e.code === "ENOENT") return { marked: false, dir: admin.dir };
60
+ return { unknown: `cannot look for ${mark} (${e.code ?? e.message})` };
61
+ }
62
+ }
@@ -0,0 +1,450 @@
1
+ #!/usr/bin/env node
2
+ // Evict: remove a claim tree's installed dependencies — every path git
3
+ // ignores in it except the `agent-test` runner — once IDLE_MS pass with
4
+ // neither a HEAD move nor a restore in it. The claim, its tree, its branch and
5
+ // its commits stay; the Install step runs again, through `--restore`, before a
6
+ // member runs code there. Not Reap, Release or Reclaim, which remove things.
7
+ //
8
+ // evict.mjs [--after-rotate] [--apply]
9
+ // evict.mjs --restore <abs tree> [--apply]
10
+ //
11
+ // Dry run by default; `--apply` mutates.
12
+ //
13
+ // THE SWEEP judges every worktree git lists directly under this checkout's
14
+ // `.worktrees/`, the checkout being the one fleet-dir.mjs's fleetFile()
15
+ // resolves from the cwd. A candidate is a claim tree: its directory and its
16
+ // branch match stranded.mjs's CLAIM_WORKTREE and CLAIM_BRANCH
17
+ // (`<N>-impl-<N>[-x]` on `implementer/<N>-impl-<N>[-x]`), whatever its PR's
18
+ // state; nothing here calls `gh`. A tree is KEPT, with its reason, when:
19
+ // - it is no claim tree (another name, or another branch);
20
+ // - a git operation is in progress in it — the state worktree.sh's
21
+ // `wt_op_state` reads, which reap.sh reads too;
22
+ // - this script's own cwd is inside it;
23
+ // - a live member token holds it (below);
24
+ // - it carries the mark already;
25
+ // - `git status --porcelain -uall` in it is non-empty;
26
+ // - HEAD moved or a restore ran in it within IDLE_MS: the newer of the
27
+ // newest entry of the tree's own HEAD reflog (`logs/HEAD` in its admin
28
+ // dir, or git's answer in a reftable repository; HEAD's commit date when
29
+ // that reflog is empty) and the time RESTORED records;
30
+ // - it ignores nothing but the runner;
31
+ // - anything about it cannot be read — its `.git`, its admin dir, a status,
32
+ // a reflog. A worktree listing that cannot be read keeps the whole
33
+ // `.worktrees/` directory, with that reason.
34
+ // Every other candidate is evicted.
35
+ //
36
+ // LIVE TOKENS. The ledger's live tokens (ledger-grammar.mjs's liveOnLedger())
37
+ // of the members that work a claim tree's ticket or PR — `impl-<N>`,
38
+ // `review-pr-<M>`, `fix-pr-<M>`, `finisher-pr-<M>`, any retry suffix — hold
39
+ // trees. `impl-<N>` holds tree N. Any other holds the trees of the tickets the
40
+ // row carrying it names: a row keyed `#<N>` names ticket N, and a fold-in row
41
+ // `PR#<M> · inherited (closes #<N>, …)` names the tickets its list does. One
42
+ // on a row naming no ticket with a claim tree here (`closes no issue`, or only
43
+ // other issues), or on no row at all, holds every candidate: the tree its
44
+ // member works in cannot be told.
45
+ //
46
+ // THE LEDGER is read as reclaim-scratch.mjs reads it: `.fleet/ledger.md`
47
+ // through `ledger.mjs read`. An absent one refuses, except under
48
+ // `--after-rotate`, which phase 0 passes straight after its rotation: there
49
+ // an absent ledger is no live token. Only ENOENT is absence.
50
+ //
51
+ // `--apply` judges each tree to evict again, writes the mark (EVICTED, a file
52
+ // in the tree's git admin dir), then removes every ignored path but the
53
+ // runner through reclaim-scratch.mjs's one removal sequence. Tracked files,
54
+ // HEAD, the branch and the registration are not touched. Best-effort per
55
+ // tree: a tree whose mark cannot be written, or a path in it that cannot be
56
+ // removed, lands in `failed` and keeps its mark; the sweep goes on.
57
+ //
58
+ // Prints ONE JSON line:
59
+ // {"applied","ledger":<abs path|null>,"evicted":[{"path","reason","ignored"}],
60
+ // "kept":[{"path","reason"}],"failed":[{"path","error"}]}
61
+ // `ledger` is null when none was read (`--after-rotate` with no file); a dry
62
+ // run's `evicted` names what `--apply` would evict. Exit 0 whenever the receipt
63
+ // is printed; 2 for a refused invocation, before anything is touched.
64
+ //
65
+ // RESTORE. `--restore <abs tree>` runs the Install step in an evicted tree as
66
+ // claim-ticket.sh runs it after `worktree add`: the command `derive-testcmd.sh
67
+ // <tree> install --at origin/main` prints, through `sh -c` in the tree with `CI` unset. Exit 126
68
+ // or 127 refuses as a Recipe that no longer runs, any other non-zero as a
69
+ // failed install, and a `git status --porcelain -uall` that is not empty
70
+ // after it as an Install step that changed the tree — each with the claim's
71
+ // own words. A status that is not empty BEFORE it refuses in words of its
72
+ // own, before anything runs: that change is no Install step's. Only once the
73
+ // status after it is empty does it write the restore time (RESTORED) and then
74
+ // remove the mark; every refusal leaves the mark. A tree with no mark refuses:
75
+ // there is nothing to restore. Without `--apply` it runs nothing and prints
76
+ // the command it would run. Prints
77
+ // `{"applied","worktree","install"}`; exit 0 restored (or would), 2 refused.
78
+
79
+ import { spawnSync } from "node:child_process";
80
+ import { readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
81
+ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
82
+ import { fileURLToPath } from "node:url";
83
+ import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
84
+ import { adminDir, EVICTED, evictionMark, how, RESTORED } from "./evict-mark.mjs";
85
+ import { gitEnv } from "./git-env.mjs";
86
+ import { isCLI } from "./is-cli.mjs";
87
+ import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
88
+ import { ledgerFile, readLedger, removeEntry } from "./reclaim-scratch.mjs";
89
+ import { CLAIM_BRANCH, CLAIM_WORKTREE } from "./stranded.mjs";
90
+
91
+ const NAME = "evict";
92
+ const die = makeDie(NAME);
93
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
94
+ const DAY_MS = 24 * 60 * 60 * 1000;
95
+ // How long a claim tree sits with neither a HEAD move nor a restore before it
96
+ // is evicted.
97
+ export const IDLE_MS = 7 * DAY_MS;
98
+ /** Whether a tree whose HEAD last moved, or which was last restored, at `last` is idle at `now`. */
99
+ export const isIdle = (now, last) => now - last >= IDLE_MS;
100
+ const RUNNER = "agent-test";
101
+ const GIT_TIMEOUT_MS = 30_000;
102
+ const MAX_BUFFER = 64 * 1024 * 1024;
103
+ // claim-ticket.sh's `rederive`, word for word: a restore refuses as the claim
104
+ // does.
105
+ export const REDERIVE = "the Recipe cache is invalid; run the Recipe derivation step (run-team phase 0, before the first claim) to re-derive it";
106
+ // worktree.sh's `wt_op_state`, sourced: `$wt_op` names the operation in
107
+ // progress, empty for none; a non-zero exit is an admin dir it cannot read.
108
+ const OP_STATE = '. "$1" || exit 3; wt_op_state "$2" || exit 1; printf "%s" "$wt_op"';
109
+
110
+ // Every child this script starts, with GIT_DIR and GIT_WORK_TREE scrubbed so
111
+ // an ambient pair cannot answer for another repository; `drop` names more
112
+ // variables to leave out.
113
+ function run(cmd, args, { cwd, drop = [], stdio, timeout = GIT_TIMEOUT_MS } = {}) {
114
+ const env = gitEnv();
115
+ for (const k of drop) delete env[k];
116
+ return spawnSync(cmd, args, { cwd, encoding: "utf8", maxBuffer: MAX_BUFFER, env, stdio, timeout });
117
+ }
118
+
119
+ const git = (tree, args) => run("git", ["-C", tree, ...args]);
120
+
121
+ // --- live tokens ------------------------------------------------------------
122
+
123
+ const FOLD_IN = /· inherited \(closes ([^)]*)\)/;
124
+
125
+ /** The tickets a ledger row names: a fold-in row's `closes` list, else its `#<N>` key. */
126
+ export function rowTickets(text) {
127
+ const fold = FOLD_IN.exec(text);
128
+ if (fold) return [...fold[1].matchAll(/#([1-9][0-9]*)/g)].map((m) => Number(m[1]));
129
+ const key = text.split(/\s/)[0];
130
+ return /^#[1-9][0-9]*$/.test(key) ? [Number(key.slice(1))] : [];
131
+ }
132
+
133
+ /**
134
+ * Which claim trees the ledger's live tokens hold: `{all, byTicket}`, `all`
135
+ * the reason every candidate is held (null when none is), `byTicket` ticket
136
+ * number → reason. `here` is the set of ticket numbers a claim tree here is
137
+ * named for.
138
+ */
139
+ export function liveHolds(rows, dispatched, here) {
140
+ const byTicket = new Map();
141
+ let all = null;
142
+ const hold = (n, why) => {
143
+ if (!byTicket.has(n)) byTicket.set(n, why);
144
+ };
145
+ for (const t of liveOnLedger(rows, dispatched).tokens) {
146
+ const member = parseMember(t.name);
147
+ // The members that run in a claim tree, or review or finish its PR.
148
+ if ((member === null || member.family === "merge-bot") && !REVIEWER.test(t.name)) continue;
149
+ if (member?.family === "impl") {
150
+ hold(member.number, `held by the live ${t.name}`);
151
+ continue;
152
+ }
153
+ const carrying = rows.filter((text) => text.split(/\s+/).includes(t.token));
154
+ if (carrying.length === 0) all ??= `held by the live ${t.name}, which is on no row, so the tree its member works in cannot be told`;
155
+ for (const text of carrying) {
156
+ const key = text.split(/\s/)[0];
157
+ const named = rowTickets(text).filter((n) => here.has(n));
158
+ if (named.length === 0) all ??= `held by the live ${t.name} on row ${key}, which names no ticket with a claim tree here, so the tree its member works in cannot be told`;
159
+ for (const n of named) hold(n, `held by the live ${t.name} on row ${key}`);
160
+ }
161
+ }
162
+ return { all, byTicket };
163
+ }
164
+
165
+ // --- the worktrees ----------------------------------------------------------
166
+
167
+ // Every worktree git lists directly under `checkout`'s `.worktrees/`, as
168
+ // `{path, branch, prunable}`, `branch` the short name or null when detached.
169
+ // `{unknown}` when the listing or the directory cannot be read.
170
+ function listing(checkout) {
171
+ const r = git(checkout, ["worktree", "list", "--porcelain", "-z"]);
172
+ if (r.error || r.status !== 0) return { unknown: `git worktree list failed (${how(r)})` };
173
+ const home = join(checkout, ".worktrees");
174
+ let real;
175
+ try {
176
+ real = realpathSync(home);
177
+ } catch (e) {
178
+ if (e.code === "ENOENT") return { trees: [] };
179
+ return { unknown: `cannot resolve ${home} (${e.code ?? e.message})` };
180
+ }
181
+ const all = [];
182
+ let cur = null;
183
+ for (const field of r.stdout.split("\0")) {
184
+ if (field === "") cur = null;
185
+ else if (field.startsWith("worktree ")) all.push((cur = { path: field.slice("worktree ".length), branch: null, prunable: false }));
186
+ else if (cur !== null && field.startsWith("branch refs/heads/")) cur.branch = field.slice("branch refs/heads/".length);
187
+ else if (cur !== null && (field === "prunable" || field.startsWith("prunable "))) cur.prunable = true;
188
+ }
189
+ const trees = [];
190
+ for (const w of all) {
191
+ try {
192
+ if (realpathSync(dirname(w.path)) === real) trees.push(w);
193
+ } catch (e) {
194
+ if (e.code !== "ENOENT") return { unknown: `cannot resolve ${dirname(w.path)} (${e.code ?? e.message})` };
195
+ }
196
+ }
197
+ return { trees };
198
+ }
199
+
200
+ // The newest entry of the tree's own HEAD reflog, in ms, or null when that
201
+ // reflog holds none; throws what cannot be read. The files ref backend keeps
202
+ // it as `logs/HEAD` in the admin dir, read here directly. A reftable
203
+ // repository keeps no such file, so there git answers: `reflog exists HEAD`,
204
+ // then the newest entry's time. Never `git log -g` alone: for a HEAD whose
205
+ // reflog holds nothing it walks the branch's reflog instead.
206
+ function reflogNewest(tree, dir) {
207
+ const format = git(tree, ["rev-parse", "--show-ref-format"]);
208
+ if (format.error || format.status !== 0) throw new Error(`cannot tell how its refs are stored (${how(format)})`);
209
+ if (format.stdout.trim() === "reftable") {
210
+ const exists = git(tree, ["reflog", "exists", "HEAD"]);
211
+ if (!exists.error && exists.signal === null && exists.status === 1) return null;
212
+ if (exists.error || exists.status !== 0) throw new Error(`cannot read its HEAD reflog (${how(exists)})`);
213
+ const r = git(tree, ["log", "-g", "-1", "--date=unix", "--format=%gd", "HEAD"]);
214
+ const at = /^HEAD@\{([0-9]+)\}$/.exec(String(r.stdout ?? "").trim());
215
+ if (r.error || r.status !== 0 || !at) throw new Error(`cannot read its HEAD reflog's newest entry (${how(r)})`);
216
+ return Number(at[1]) * 1000;
217
+ }
218
+ let text;
219
+ try {
220
+ text = readFileSync(join(dir, "logs", "HEAD"), "utf8");
221
+ } catch (e) {
222
+ if (e.code === "ENOENT") return null;
223
+ throw new Error(`cannot read its HEAD reflog (${e.code ?? e.message})`);
224
+ }
225
+ const last = text.split("\n").filter(Boolean).at(-1);
226
+ if (last === undefined) return null;
227
+ const m = / ([0-9]+) [+-][0-9]{4}$/.exec(last.split("\t")[0]);
228
+ if (!m) throw new Error("cannot read its HEAD reflog's newest entry");
229
+ return Number(m[1]) * 1000;
230
+ }
231
+
232
+ // When HEAD last moved in the tree, in ms: its reflog's newest entry, else
233
+ // HEAD's commit date.
234
+ function headMoved(tree, dir) {
235
+ const logged = reflogNewest(tree, dir);
236
+ if (logged !== null) return logged;
237
+ const r = git(tree, ["log", "-1", "--format=%ct", "HEAD"]);
238
+ const s = String(r.stdout ?? "").trim();
239
+ if (r.error || r.status !== 0 || !isDigits(s)) throw new Error(`cannot read HEAD's commit date (${how(r)})`);
240
+ return Number(s) * 1000;
241
+ }
242
+
243
+ // The restore time RESTORED records, in ms, or null when none was.
244
+ function restoredAt(dir) {
245
+ const file = join(dir, RESTORED);
246
+ let text;
247
+ try {
248
+ text = readFileSync(file, "utf8").trim();
249
+ } catch (e) {
250
+ if (e.code === "ENOENT") return null;
251
+ throw new Error(`cannot read ${file} (${e.code ?? e.message})`);
252
+ }
253
+ const at = Date.parse(text);
254
+ if (Number.isNaN(at)) throw new Error(`${file} holds no time: ${JSON.stringify(text)}`);
255
+ return at;
256
+ }
257
+
258
+ // Every path the tree ignores, relative to it, but the runner — a directory
259
+ // git lists whole once, and nothing listed inside one already listed.
260
+ function ignoredPaths(tree) {
261
+ const r = git(tree, ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory"]);
262
+ if (r.error || r.status !== 0) throw new Error(`git ls-files --ignored failed (${how(r)})`);
263
+ const out = [];
264
+ for (const p of r.stdout.split("\0").filter(Boolean).sort()) {
265
+ const bare = p.replace(/\/$/, "");
266
+ if (bare === RUNNER) continue;
267
+ if (out.some((q) => q.endsWith("/") && p.startsWith(q))) continue;
268
+ out.push(p);
269
+ }
270
+ return out;
271
+ }
272
+
273
+ const within = (path, root) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
274
+
275
+ /**
276
+ * One tree's verdict: `{evict: {reason, ignored, dir}}` or `{kept}`, a reason.
277
+ * `ctx` is `{cwd, holds, now}`.
278
+ */
279
+ function judge(w, ctx) {
280
+ const name = CLAIM_WORKTREE.exec(basename(w.path));
281
+ if (!name) return { kept: `not a claim tree: its directory is not named <N>-impl-<N>[-x]` };
282
+ if (w.prunable) return { kept: "git lists it as prunable: its directory is gone or cannot be read" };
283
+ const admin = adminDir(w.path);
284
+ if (admin.unknown !== undefined) return { kept: admin.unknown };
285
+ const op = run("sh", ["-c", OP_STATE, "sh", join(SCRIPT_DIR, "worktree.sh"), w.path]);
286
+ if (op.error || op.status !== 0) return { kept: `cannot tell whether a git operation is in progress in it (${how(op)})` };
287
+ if (op.stdout !== "") return { kept: `a git operation is in progress in it (${op.stdout})` };
288
+ const branch = w.branch === null ? null : CLAIM_BRANCH.exec(w.branch);
289
+ if (branch === null || branch[2] !== name[2] || branch[1] !== name[1]) {
290
+ return { kept: `not a claim tree: it is on ${w.branch === null ? "a detached HEAD" : w.branch}, not implementer/${basename(w.path)}` };
291
+ }
292
+ let real;
293
+ try {
294
+ real = realpathSync(w.path);
295
+ } catch (e) {
296
+ return { kept: `cannot resolve it (${e.code ?? e.message})` };
297
+ }
298
+ if (ctx.cwd !== null && within(ctx.cwd, real)) return { kept: "this script's own cwd is inside it" };
299
+ const n = Number(name[1]);
300
+ const held = ctx.holds.byTicket.get(n) ?? ctx.holds.all;
301
+ if (held !== null) return { kept: held };
302
+ const mark = evictionMark(w.path);
303
+ if (mark.unknown !== undefined) return { kept: mark.unknown };
304
+ if (mark.marked) return { kept: `already evicted: ${join(mark.dir, EVICTED)} is there` };
305
+ const status = git(w.path, ["status", "--porcelain", "-uall"]);
306
+ if (status.error || status.status !== 0) return { kept: `cannot read its status (${how(status)})` };
307
+ if (status.stdout !== "") return { kept: `git status is not clean (first: ${status.stdout.split("\n")[0]})` };
308
+ let moved;
309
+ let restored;
310
+ try {
311
+ moved = headMoved(w.path, admin.dir);
312
+ restored = restoredAt(admin.dir);
313
+ } catch (e) {
314
+ return { kept: e.message };
315
+ }
316
+ const last = Math.max(moved, restored ?? 0);
317
+ const what = restored !== null && restored >= moved ? "restored" : "HEAD last moved";
318
+ if (!isIdle(ctx.now, last)) return { kept: `${what} ${new Date(last).toISOString()}, within ${IDLE_MS / DAY_MS} days` };
319
+ let ignored;
320
+ try {
321
+ ignored = ignoredPaths(w.path);
322
+ } catch (e) {
323
+ return { kept: e.message };
324
+ }
325
+ if (ignored.length === 0) return { kept: `it ignores nothing but ${RUNNER}` };
326
+ return { evict: { reason: `${what} ${new Date(last).toISOString()}, over ${IDLE_MS / DAY_MS} days ago`, ignored, dir: admin.dir } };
327
+ }
328
+
329
+ // Mark the tree, then remove each ignored path in it; null, or the error.
330
+ function evictTree(path, verdict, now) {
331
+ try {
332
+ writeFileSync(join(verdict.dir, EVICTED), `${new Date(now).toISOString()}\n`);
333
+ } catch (e) {
334
+ return `could not write ${join(verdict.dir, EVICTED)} (${e.code ?? e.message}), so nothing was removed`;
335
+ }
336
+ const errors = [];
337
+ for (const p of verdict.ignored) {
338
+ const error = removeEntry(join(path, p.replace(/\/$/, "")));
339
+ if (error !== null) errors.push(`${p}: ${error}`);
340
+ }
341
+ return errors.length ? `could not remove ${errors.join("; ")}` : null;
342
+ }
343
+
344
+ function sweep({ afterRotate, apply }) {
345
+ const found = ledgerFile(die);
346
+ if (found.file === null && !afterRotate) {
347
+ die("no .fleet/ledger.md — without it no live member can hold its claim tree, so nothing is evicted; pass --after-rotate only straight after `ledger.mjs rotate`");
348
+ }
349
+ const ledger = found.file === null ? { rows: [], dispatched: [] } : readLedger(found.file, die, "evicted");
350
+ let cwd;
351
+ try {
352
+ cwd = realpathSync(process.cwd());
353
+ } catch {
354
+ cwd = null;
355
+ }
356
+ const now = Date.now();
357
+ const evicted = [];
358
+ const kept = [];
359
+ const failed = [];
360
+ const list = listing(found.checkout);
361
+ if (list.unknown !== undefined) {
362
+ kept.push({ path: join(found.checkout, ".worktrees"), reason: list.unknown });
363
+ } else {
364
+ const here = new Set(list.trees.map((w) => CLAIM_WORKTREE.exec(basename(w.path))).filter(Boolean).map((m) => Number(m[1])));
365
+ const ctx = { cwd, holds: liveHolds(ledger.rows, ledger.dispatched, here), now };
366
+ for (const w of [...list.trees].sort((a, b) => a.path.localeCompare(b.path))) {
367
+ let v = judge(w, ctx);
368
+ // Judged again just before anything is touched: the dry verdict is a
369
+ // moment old, and a member may have moved HEAD or dirtied it since.
370
+ if (apply && v.kept === undefined) v = judge(w, ctx);
371
+ if (v.kept !== undefined) {
372
+ kept.push({ path: w.path, reason: v.kept });
373
+ continue;
374
+ }
375
+ const error = apply ? evictTree(w.path, v.evict, now) : null;
376
+ if (error === null) evicted.push({ path: w.path, reason: v.evict.reason, ignored: v.evict.ignored });
377
+ else failed.push({ path: w.path, error });
378
+ }
379
+ }
380
+ writeAll(1, `${JSON.stringify({ applied: apply, ledger: found.file, evicted, kept, failed })}\n`);
381
+ }
382
+
383
+ function restore(tree, apply) {
384
+ try {
385
+ if (!statSync(tree).isDirectory()) die(`--restore ${tree} is not a directory`);
386
+ } catch (e) {
387
+ die(`--restore ${tree} is not a directory: ${e.message}`);
388
+ }
389
+ const mark = evictionMark(tree);
390
+ if (mark.unknown !== undefined) die(`cannot tell whether ${tree} is evicted: ${mark.unknown}`);
391
+ if (!mark.marked) die(`${tree} is not evicted (no ${join(mark.dir, EVICTED)}) — nothing to restore`);
392
+ const derived = run("sh", [join(SCRIPT_DIR, "derive-testcmd.sh"), tree, "install", "--at", "origin/main"]);
393
+ const install = String(derived.stdout ?? "").replace(/\n$/, "");
394
+ if (derived.error || derived.status !== 0 || install === "") {
395
+ die(`${String(derived.stderr ?? "").trim() || `derive-testcmd.sh ${tree} install failed (${how(derived)})`}`);
396
+ }
397
+ // Dirty before anything runs is no Install step's doing: said in its own
398
+ // words, so the dirty-after refusal below never blames the Recipe for it.
399
+ const before = git(tree, ["status", "--porcelain", "-uall"]);
400
+ if (before.error || before.status !== 0) die(`could not read the tree state in ${tree} before the Install step (${how(before)})`);
401
+ if (before.stdout !== "") die(`${tree} is not clean before the restore (first: ${before.stdout.split("\n")[0]}) — the Install step did not run; clear that change, then restore again`);
402
+ if (apply) {
403
+ // Through `sh -c` with `CI` unset and the output dropped, as claim-ticket.sh
404
+ // runs it; no timeout, as there.
405
+ const r = run("sh", ["-c", install], { cwd: tree, drop: ["CI"], stdio: "ignore", timeout: 0 });
406
+ if (r.error) die(`the Install step '${install}' did not run in ${tree} (${how(r)}) — ${REDERIVE}`);
407
+ if (r.signal) die(`install failed in ${tree} (${how(r)})`);
408
+ if (r.status === 126 || r.status === 127) {
409
+ die(`the Install step '${install}' did not run in ${tree} (exit ${r.status}: not executable or not found) — ${REDERIVE}`);
410
+ }
411
+ if (r.status !== 0) die(`install failed in ${tree} (exit ${r.status})`);
412
+ const status = git(tree, ["status", "--porcelain", "-uall"]);
413
+ if (status.error || status.status !== 0) die(`could not verify the tree state in ${tree} after the Install step`);
414
+ if (status.stdout !== "") die(`the Install step '${install}' changed the tree in ${tree} (first: ${status.stdout.split("\n")[0]}) — ${REDERIVE}`);
415
+ // The restore time first: a mark removed with no time beside it would read
416
+ // the tree idle by its HEAD alone and evict it again at once.
417
+ const restored = join(mark.dir, RESTORED);
418
+ try {
419
+ writeFileSync(restored, `${new Date().toISOString()}\n`);
420
+ } catch (e) {
421
+ die(`installed in ${tree}, but could not record the restore in ${restored} (${e.code ?? e.message}) — the mark stays`);
422
+ }
423
+ try {
424
+ unlinkSync(join(mark.dir, EVICTED));
425
+ } catch (e) {
426
+ die(`installed in ${tree} and recorded the restore in ${restored}, but could not remove the mark ${join(mark.dir, EVICTED)} (${e.code ?? e.message}) — the mark stays`);
427
+ }
428
+ }
429
+ writeAll(1, `${JSON.stringify({ applied: apply, worktree: tree, install })}\n`);
430
+ }
431
+
432
+ function main() {
433
+ const { arg, has, sweep: refuseUnknown, stray } = defineFlags(die, {
434
+ flags: { "after-rotate": "bool", apply: "bool", restore: "value" },
435
+ });
436
+ refuseUnknown();
437
+ stray();
438
+ const target = arg("restore");
439
+ const afterRotate = has("after-rotate");
440
+ const apply = has("apply");
441
+ if (target === null) {
442
+ sweep({ afterRotate, apply });
443
+ return;
444
+ }
445
+ if (afterRotate) die("--after-rotate is the sweep's; --restore reads no ledger");
446
+ if (!isAbsolute(target)) die(`--restore must be an absolute path, got ${JSON.stringify(target)}`);
447
+ restore(resolve(target), apply);
448
+ }
449
+
450
+ if (isCLI(import.meta.url)) main();
@@ -46,11 +46,11 @@
46
46
  // the heartbeat and by ledger.mjs.
47
47
  // applied fleet-tick only, and only under --apply. {run, reapAfter}: the
48
48
  // merge-bot numbers whose `merge-bot-<n>=done` the tick has already
49
- // run reap.sh and reclaim-scratch.mjs after, and the controller
50
- // record's `at` they belong to. Written only under a record: with
51
- // none, nothing tells one run from the next. Merge-bot numbering
52
- // restarts at 1 in a run that carries no bot forward, and this
53
- // file outlives the rotation, so a list whose `run` is not the
49
+ // run reap.sh, reclaim-scratch.mjs and evict.mjs after, and the
50
+ // controller record's `at` they belong to. Written only under a
51
+ // record: with none, nothing tells one run from the next. Merge-bot
52
+ // numbering restarts at 1 in a run that carries no bot forward, and
53
+ // this file outlives the rotation, so a list whose `run` is not the
54
54
  // current record's `at` is the previous run's and names nothing in
55
55
  // this one. Carried, never written, by the heartbeat and by
56
56
  // ledger.mjs.
@@ -1174,7 +1174,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1174
1174
  fixLive: live("fix-pr"),
1175
1175
  mergeBotLive,
1176
1176
  // The number of every merge bot settled `done`: each is a merge pass
1177
- // `--apply` reaps and reclaims after, once (reapDue).
1177
+ // `--apply` reaps, reclaims and evicts after, once (reapDue).
1178
1178
  mergeBotDone: all.filter((m) => m.family === "merge-bot" && m.outcome === "done").map((m) => m.number).sort(asc),
1179
1179
  reviewsLive: liveReviews.length,
1180
1180
  // The in-flight reviews of PRs the open list does not carry: the ones
@@ -1504,7 +1504,7 @@ export function reapedAfter(applied, controllerAt) {
1504
1504
  return applied !== null && controllerAt != null && applied.run === controllerAt ? applied.reapAfter : [];
1505
1505
  }
1506
1506
 
1507
- // The merge passes owed their reap and reclaim: every merge bot settled
1507
+ // The merge passes owed their reap, reclaim and evict: every merge bot settled
1508
1508
  // `done` that reapedAfter() does not name.
1509
1509
  export function reapDue(done, applied, controllerAt) {
1510
1510
  const ran = new Set(reapedAfter(applied, controllerAt));
@@ -1550,6 +1550,15 @@ export function reclaimSummary(stdout) {
1550
1550
  return `removed ${r.removed.length}, kept ${r.kept.length}, failed ${r.failed.length}`;
1551
1551
  }
1552
1552
 
1553
+ // evict.mjs's receipt as `evicted <k>, kept <m>, failed <f>`, or null. A tree
1554
+ // whose removal failed is in the receipt and exits 0: it is reported here, and
1555
+ // the pass still counts as evicted after.
1556
+ export function evictSummary(stdout) {
1557
+ const r = receiptOf(stdout);
1558
+ if (r === null || ![r.evicted, r.kept, r.failed].every(Array.isArray)) return null;
1559
+ return `evicted ${r.evicted.length}, kept ${r.kept.length}, failed ${r.failed.length}`;
1560
+ }
1561
+
1553
1562
  // --------------------------------------------------------------------------
1554
1563
  // I/O. Everything below runs only as a CLI — importing this file must never
1555
1564
  // parse argv or touch the network, or the pure half stops being unit-testable.
@@ -1634,8 +1643,8 @@ const OPTIONS = {
1634
1643
  // a controller that just acted needs the full rows.
1635
1644
  "fold-unchanged": { type: "boolean", default: false },
1636
1645
  // `--apply` runs the idempotent follow-ups whose trigger the ledger and the
1637
- // state file show, before the rows: reap.sh and reclaim-scratch.mjs after
1638
- // every merge pass settled `done`, and tier-check.mjs on every implementer
1646
+ // state file show, before the rows: reap.sh, reclaim-scratch.mjs and
1647
+ // evict.mjs after every merge pass settled `done`, and tier-check.mjs on every implementer
1639
1648
  // the tick would hold as unchecked. It never dispatches, never settles a
1640
1649
  // member and writes no ledger row but through those scripts. Without it the
1641
1650
  // tick is read-only.
@@ -1990,25 +1999,30 @@ function reportDuty(r, { label, duty, what, summarise }) {
1990
1999
  return summary !== null;
1991
2000
  }
1992
2001
 
1993
- // Reap, then reclaim, after the merge passes in `due` — once however many
1994
- // there are, since both sweep the whole repository and scratch root rather
1995
- // than one pass's share. Reclaim runs whether or not reap did: neither reads
1996
- // the other's result. True only when both applied, the one case `due` is
1997
- // recorded as reaped after; otherwise the next --apply tick runs both again.
2002
+ // Reap, then reclaim, then evict, after the merge passes in `due` — once
2003
+ // however many there are, since each sweeps the whole repository, scratch
2004
+ // root or set of claim trees rather than one pass's share. Each runs whether
2005
+ // or not the one before it did: none reads another's result. True only when
2006
+ // all three applied, the one case `due` is recorded as reaped after; otherwise
2007
+ // the next --apply tick runs them again.
1998
2008
  function applyReap(due) {
1999
2009
  const label = `reap after ${due.map((n) => `merge-bot-${n}`).join(" ")}`;
2000
2010
  const reaped = reportDuty(runSibling("reap.sh", ["--apply"]), { label, duty: "reap", what: "reap.sh", summarise: reapSummary });
2001
- let root;
2011
+ let reclaimed = false;
2012
+ let root = null;
2002
2013
  try {
2003
2014
  root = scratchRoot();
2004
2015
  } catch (e) {
2005
2016
  if (!(e instanceof FleetDirUnresolvable)) throw e;
2006
2017
  console.log(`APPLY FAILED reclaim: ${e.message}`);
2007
- return false;
2008
2018
  }
2009
- const reclaimed = reportDuty(runSibling("reclaim-scratch.mjs", ["--root", root, "--apply"]),
2010
- { label: "reclaim", duty: "reclaim", what: "reclaim-scratch.mjs", summarise: reclaimSummary });
2011
- return reaped && reclaimed;
2019
+ if (root !== null) {
2020
+ reclaimed = reportDuty(runSibling("reclaim-scratch.mjs", ["--root", root, "--apply"]),
2021
+ { label: "reclaim", duty: "reclaim", what: "reclaim-scratch.mjs", summarise: reclaimSummary });
2022
+ }
2023
+ const evicted = reportDuty(runSibling("evict.mjs", ["--apply"]),
2024
+ { label: "evict", duty: "evict", what: "evict.mjs", summarise: evictSummary });
2025
+ return reaped && reclaimed && evicted;
2012
2026
  }
2013
2027
 
2014
2028
  // tier-check.mjs's verdict by its exit status, each one a token the check
@@ -2304,8 +2318,8 @@ function main() {
2304
2318
  const mainCheckout = checkMainCheckout();
2305
2319
 
2306
2320
  if (apply) {
2307
- // Reap and reclaim after every merge pass settled `done` since the last
2308
- // time they ran. Recorded only once both applied, on a fresh read of the
2321
+ // Reap, reclaim and evict after every merge pass settled `done` since the
2322
+ // last time they ran. Recorded only once all three applied, on a fresh read of the
2309
2323
  // state file so nothing the heartbeat wrote meanwhile is reverted, never
2310
2324
  // onto a file that could not be read, and never with no controller
2311
2325
  // record: nothing could tell a list recorded then from the next run's.
@@ -20,7 +20,7 @@ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x)
20
20
  // by a finished phase 0.
21
21
  export const STEP_NAMES = Object.freeze([
22
22
  "alarm", "branch", "fast-forward", "pin", "baseline", "labels", "preflight", "ruleset", "tier-roles", "metrics",
23
- "cockpit", "rotate", "reclaim", "recipe", "fold-in", "stranded", "shortlist",
23
+ "cockpit", "rotate", "reclaim", "evict", "recipe", "fold-in", "stranded", "shortlist",
24
24
  ]);
25
25
 
26
26
  // The statuses a step can end in that let the run go on: `ok`, and the two
@@ -70,6 +70,11 @@
70
70
  // for the other keys under the scratch parent, which runs
71
71
  // whatever the first answered. What either receipt's failed[]
72
72
  // names is listed. Recorded; never fails the run.
73
+ // evict `evict.mjs --after-rotate --apply`, straight after the
74
+ // reclaim: the claim trees idle past evict.mjs's bound lose
75
+ // their installed dependencies. A non-zero exit, and each
76
+ // tree its receipt's failed[] names, is listed. Recorded;
77
+ // never fails the run.
73
78
  // recipe `derive-testcmd.sh . install`, `. check` and `. test`, each
74
79
  // `--at origin/main` (recipe-read.mjs, which the settle wakes of
75
80
  // fleet-event.mjs read the cache through as well). Any
@@ -356,18 +361,26 @@ function reclaim({ cwd, scratch }) {
356
361
  ].join("\n"));
357
362
  }
358
363
 
364
+ function evict({ cwd }) {
365
+ const r = node("evict.mjs", ["--after-rotate", "--apply"], { cwd });
366
+ return ok([
367
+ r.status === 0 ? "idle claim trees evicted" : withText(`evict.mjs ${r.how}, not enforced`, r),
368
+ ...unreclaimed("claim trees", r, { script: "evict.mjs", verb: "evict" }),
369
+ ].join("\n"));
370
+ }
371
+
359
372
  // A pass that exited 0 still lists in its receipt's `failed[]` what it could
360
373
  // not judge or remove: each is named here, and none fails the step.
361
- function unreclaimed(what, r) {
374
+ function unreclaimed(what, r, { script = "reclaim-scratch.mjs", verb = "reclaim" } = {}) {
362
375
  if (r.status !== 0) return [];
363
376
  let entries;
364
377
  try {
365
378
  ({ failed: entries } = JSON.parse(r.stdout));
366
379
  } catch (e) {
367
- return [`${what}: could not read reclaim-scratch.mjs's receipt: ${e.message}`];
380
+ return [`${what}: could not read ${script}'s receipt: ${e.message}`];
368
381
  }
369
- if (!Array.isArray(entries)) return [`${what}: reclaim-scratch.mjs's receipt holds no failed[]`];
370
- return entries.map((x) => `${what}: could not reclaim ${x?.path} (${x?.error})`);
382
+ if (!Array.isArray(entries)) return [`${what}: ${script}'s receipt holds no failed[]`];
383
+ return entries.map((x) => `${what}: could not ${verb} ${x?.path} (${x?.error})`);
371
384
  }
372
385
 
373
386
  function recipe({ cwd }) {
@@ -534,7 +547,7 @@ function alarm({ fleetDir }) {
534
547
  const STEPS = {
535
548
  "alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "labels": labels,
536
549
  "preflight": preflight, "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
537
- "reclaim": reclaim, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
550
+ "reclaim": reclaim, "evict": evict, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
538
551
  };
539
552
 
540
553
  const STEP_NAMES = Object.keys(STEPS);
@@ -191,13 +191,15 @@ export function removeEntry(path) {
191
191
  return r.error || r.status !== 0 ? how(r) : null;
192
192
  }
193
193
 
194
- // The live tokens the ledger holds, by name, read through `ledger.mjs read`
195
- // so the ledger keeps one parser. `--file` names it outright, so the read
196
- // resolves no workspace and runs no git.
197
- function liveNames(file) {
194
+ // The ledger's rows and `## Dispatched` entries, read through `ledger.mjs
195
+ // read` so the ledger keeps one parser. `--file` names it outright, so the read
196
+ // resolves no workspace and runs no git. `die` is the caller's, and `undone`
197
+ // names what a refusal leaves undone ("reclaimed", "evicted"): evict.mjs reads
198
+ // the ledger this same way.
199
+ export function readLedger(file, die, undone) {
198
200
  const script = join(dirname(fileURLToPath(import.meta.url)), "ledger.mjs");
199
201
  const r = spawnSync(process.execPath, [script, "--file", file, "read"], { encoding: "utf8", maxBuffer: MAX_BUFFER });
200
- if (r.error || r.status !== 0) die(`ledger.mjs read ${file} failed (${how(r)}) — which members are live is unknown, so nothing is reclaimed`);
202
+ if (r.error || r.status !== 0) die(`ledger.mjs read ${file} failed (${how(r)}) — which members are live is unknown, so nothing is ${undone}`);
201
203
  let d;
202
204
  try {
203
205
  d = JSON.parse(r.stdout);
@@ -206,14 +208,20 @@ function liveNames(file) {
206
208
  }
207
209
  const strings = (xs) => Array.isArray(xs) && xs.every((x) => typeof x === "string");
208
210
  if (!d || !strings(d.rows) || !strings(d.dispatched)) die("ledger.mjs read returned no {rows, dispatched}");
209
- return liveOnLedger(d.rows, d.dispatched).tokens.map((t) => t.name);
211
+ return { rows: d.rows, dispatched: d.dispatched };
212
+ }
213
+
214
+ // The live tokens the ledger holds, by name.
215
+ function liveNames(file) {
216
+ const { rows, dispatched } = readLedger(file, die, "reclaimed");
217
+ return liveOnLedger(rows, dispatched).tokens.map((t) => t.name);
210
218
  }
211
219
 
212
220
  // The checkout the fleet dir sits in, and its ledger file — `file` null when it
213
221
  // is absent. Only ENOENT is absence; a workspace that cannot be resolved, or a
214
- // path that cannot be looked up, refuses. `lstat`, so a dangling symlink is a
215
- // ledger that cannot be read.
216
- function ledgerFile() {
222
+ // path that cannot be looked up, refuses through the caller's `die`. `lstat`,
223
+ // so a dangling symlink is a ledger that cannot be read.
224
+ export function ledgerFile(die) {
217
225
  let dir;
218
226
  try {
219
227
  dir = fleetFile(null);
@@ -566,7 +574,7 @@ function main() {
566
574
  failed.push({ path: dirname(root), error: e.message });
567
575
  }
568
576
  } else {
569
- const found = ledgerFile();
577
+ const found = ledgerFile(die);
570
578
  ledger = found.file;
571
579
  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`");
572
580
  const live = ledger === null ? [] : liveNames(ledger);
@@ -84,6 +84,7 @@ import { gitEnv } from "./git-env.mjs";
84
84
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
85
85
  import { LABEL_MAP_FILE, LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
86
86
  import { readState, stateFileIn } from "./fleet-state.mjs";
87
+ import { isCLI } from "./is-cli.mjs";
87
88
  import { liveOnLedger } from "./ledger-grammar.mjs";
88
89
 
89
90
  const NAME = "stranded";
@@ -201,9 +202,10 @@ const real = (p) => {
201
202
  // A claim's names, off claim-ticket.sh's shapes for an implementer:
202
203
  // `.worktrees/<N>-impl-<N>[-x]` and `implementer/<N>-impl-<N>[-x]`, `-x` a
203
204
  // replacement's single retry letter. Each captures the number and the member
204
- // name `impl-<N>[-x]`, the slug release-ticket.sh takes.
205
- const CLAIM_WORKTREE = /^([1-9][0-9]*)-(impl-\1(?:-[a-z])?)$/;
206
- const CLAIM_BRANCH = /^implementer\/([1-9][0-9]*)-(impl-\1(?:-[a-z])?)$/;
205
+ // name `impl-<N>[-x]`, the slug release-ticket.sh takes. evict.mjs judges its
206
+ // candidates by the same two.
207
+ export const CLAIM_WORKTREE = /^([1-9][0-9]*)-(impl-\1(?:-[a-z])?)$/;
208
+ export const CLAIM_BRANCH = /^implementer\/([1-9][0-9]*)-(impl-\1(?:-[a-z])?)$/;
207
209
  const WAYS_OUT = "push the branch and open a PR, or release the claim by hand";
208
210
 
209
211
  // Every local branch under `implementer/`.
@@ -445,4 +447,4 @@ function carriedTokens(file) {
445
447
  return liveOnLedger(d.rows, d.dispatched).tokens;
446
448
  }
447
449
 
448
- main();
450
+ if (isCLI(import.meta.url)) main();
@@ -175,6 +175,9 @@ owes beyond its call:
175
175
  pass. Read `worktreesRemoved` alongside `reaped`: a pass that
176
176
  reaps branches and removes no worktrees is a finding, not a quiet success.
177
177
  Update the reaped tickets' ledger rows in the same step.
178
+ The same `--apply` then runs `evict.mjs --apply`, which empties idle claim
179
+ trees of their dependencies; a render that refuses an evicted tree names the
180
+ restore command to run first (references/phase-0.md).
178
181
  **Do not invoke `commit-commands:clean_gone`**: do the reap yourself. **Never
179
182
  reap a branch a live member is on** — cross-check `.fleet/ledger.md` first
180
183
  for a row without a terminal state.
@@ -110,6 +110,14 @@ above — so it is a second
110
110
  chance to notice a stale snapshot on the one path it covers, never a reason
111
111
  to skip the ref compare here.
112
112
 
113
+ **An evicted claim tree lacks its dependencies.** `evict.mjs` empties a claim
114
+ tree with neither a HEAD move nor a restore in 7 days of every path git ignores
115
+ but its runner, and leaves the tree, its branch and its commits. The renderer
116
+ refuses to brief an implementer
117
+ or a fix-applier into one; before you run code in one by hand, restore it with
118
+ `~/.fleet/bin/fleet-run evict.mjs --restore <tree> --apply`, which runs the
119
+ Install step there as a claim does.
120
+
113
121
  ## Filesystem isolation is not stack isolation
114
122
 
115
123
  Private copy and test command solve different problems; conflating them is how second gets skipped: compose project name comes from environment, not working directory, so three agents on three snapshots still collide on one postgres. Symlinking installed dependencies in does not help. "I'm on my own copy" is exactly the intuition that skips command — say both, every time. Which command depends on audience: member in worktree uses `./agent-test`; specialist on snapshot does not, takes one `review-and-fix.md` hands out. Which runner the worktree holds decides why: the runner a claim writes is untracked, so a `git archive` snapshot never carries it; one the repository tracks does ride along, but no claim exported ports into it — its isolation is whatever that repository built, not one triple per snapshot.
@@ -32,7 +32,7 @@ into one free implementer slot, the moment it frees (phase 1).
32
32
 
33
33
  `phase0.mjs` runs the start sequence in
34
34
  its fixed order — alarm, branch, fast-forward, pin, baseline, labels, preflight, ruleset,
35
- tier-roles, metrics, cockpit, rotate, reclaim, recipe, fold-in, stranded,
35
+ tier-roles, metrics, cockpit, rotate, reclaim, evict, recipe, fold-in, stranded,
36
36
  shortlist — prints one `phase0: <step>: <status>` line per step with the
37
37
  `NEED` lines last, and records each step in `.fleet/phase0.json`, which the
38
38
  tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
@@ -416,6 +416,31 @@ call runs whatever the root sweep answered, and records nothing on the ledger. A
416
416
  exit, and each path its receipt's `failed[]` names, is listed in the step's output; neither
417
417
  stops the run.
418
418
 
419
+ ## Evict idle claim trees
420
+
421
+ **Evict straight after the reclaim — every run.**
422
+ `~/.fleet/bin/fleet-run evict.mjs --after-rotate --apply` is phase 0's own
423
+ `evict` step. A claim tree with neither a HEAD move nor a restore in 7 days loses
424
+ every path git ignores in it but its `agent-test` runner; the claim, its tree,
425
+ its branch and its commits stay (`evict.mjs`'s header says what keeps a tree).
426
+ `--after-rotate` reads an absent ledger as "no live token", as it does for the
427
+ reclaim. A non-zero exit, and each tree its receipt's `failed[]` names, is listed
428
+ in the step's output; neither stops the run. Record nothing on the ledger.
429
+
430
+ The tick's `--apply` runs `evict.mjs --apply` after every settled merge pass,
431
+ straight after its reclaim, and reports it on an `APPLIED evict:` or
432
+ `APPLY FAILED evict:` line.
433
+
434
+ **An evicted tree is restored before a member runs code there.**
435
+ `dispatch-prompt.mjs render implementer` and `render fix-applier` refuse a
436
+ worktree evict.mjs marked, naming
437
+ `~/.fleet/bin/fleet-run evict.mjs --restore <tree> --apply`: run it, then render
438
+ again. It runs the Install step in the tree as a claim does and refuses as a
439
+ claim does. A refused restore leaves the tree evicted: dispatch nothing into
440
+ it, report the restore's message, and the row comes up again on the next wake.
441
+ `render review-runner` and `render finisher` do not refuse: neither member runs
442
+ code in the claim tree.
443
+
419
444
  ## Derive the Recipe
420
445
 
421
446
  **Derive the Recipe — the Recipe derivation step — before the fold-in below