@feigi/fleet-ctl 3.151.1 → 3.152.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.151.1",
3
+ "version": "3.152.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": {
@@ -194,7 +194,7 @@ function isWorkspaceId(v) {
194
194
  * The workspace comes from fleet-dir.mjs's fleetFile(), the same locator the
195
195
  * run's ledger and heartbeat are resolved with — so the board, the ledger and
196
196
  * the heartbeat cannot disagree about which run they belong to — asked with
197
- * the `canonicalise` opt-in only this caller takes: a symlinked route to one
197
+ * the `canonicalise` opt-in: a symlinked route to one
198
198
  * workspace must derive that workspace's port instead of a second, private
199
199
  * one.
200
200
  *
package/scripts/board.mjs CHANGED
@@ -21,7 +21,7 @@ import { serve, resolveCockpitInstance, cockpitWorkspace } from "./board-server.
21
21
  // filename rather than spelling `heartbeat.json` a second time. The PATH
22
22
  // still comes from resolveCockpitInstance() (board-server.mjs), not from
23
23
  // statePath(): the workspace is already resolved once per launch there, with
24
- // the `canonicalise` opt-in only that caller takes, and a second resolution
24
+ // the `canonicalise` opt-in statePath() does not take, and a second resolution
25
25
  // could answer differently.
26
26
  import { stateFileIn } from "./fleet-state.mjs";
27
27
  import { cockpitLifetime, controllerVerdict } from "./cockpit-lifetime.mjs";
@@ -0,0 +1,154 @@
1
+ // What an Evict removes from a git tree, and the one removal sequence every
2
+ // removal here and in Reclaim goes through. evict.mjs (a claim tree),
3
+ // reclaim-scratch.mjs (a review run's snapshot and copies, in its `--pr` pass)
4
+ // and review-core.mjs (the same trees, when a review ends) all import it; a
5
+ // module of its own so none of the three loads another's CLI, and so the
6
+ // enumeration of "every path git ignores" is written once.
7
+ //
8
+ // IGNORED PATHS. `ignoredPaths(tree)` is every path `git ls-files --others
9
+ // --ignored --exclude-standard --directory` lists in the tree, but the
10
+ // `agent-test` runner: a directory is listed whole, once, and nothing inside
11
+ // one already listed. Tracked files, the tree's .git and untracked files git
12
+ // does not ignore are not in it.
13
+ //
14
+ // A TREE, for `evictTrees(root)`, is a directory that holds `.git` at its own
15
+ // top level and whose `git rev-parse --show-toplevel` resolves, by realpath,
16
+ // to that same directory. A directory that resolves to an enclosing repository
17
+ // — one with no `.git` of its own, or with one git cannot read — is never
18
+ // stripped, and git is never asked about a directory with no `.git`. The walk
19
+ // goes down from `root` at any depth and never follows a symlink, never enters
20
+ // a `.git`, and never enters a path it removes (or, in a dry run, would
21
+ // remove) as ignored, so a repository inside `node_modules` goes with that
22
+ // directory and is not a tree of its own.
23
+ //
24
+ // No status check, no mark, no restore: a tree is evicted whatever `git status`
25
+ // says. A claim tree's status check and its mark are evict.mjs's own.
26
+
27
+ import { spawnSync } from "node:child_process";
28
+ import { lstatSync, readdirSync, realpathSync } from "node:fs";
29
+ import { join } from "node:path";
30
+ import { how } from "./evict-mark.mjs";
31
+ import { gitEnv } from "./git-env.mjs";
32
+
33
+ export const RUNNER = "agent-test";
34
+ const GIT_TIMEOUT_MS = 30_000;
35
+ const MAX_BUFFER = 64 * 1024 * 1024;
36
+
37
+ // The one removal sequence. `$1` is the entry. A symlink entry is unlinked
38
+ // before anything else runs, so no chmod or chflags ever sees it: whether a
39
+ // recursive chmod dereferences a link given as its operand differs between
40
+ // BSD and GNU, and either would change the mode or flags of a target outside
41
+ // the entry being removed. Links met inside a directory are left to `rm`,
42
+ // which unlinks them without following. `chmod -R` fails
43
+ // on a flagged directory, and `chflags -R` cannot read a mode-000 directory it
44
+ // has just unflagged, so when the first pass fails each directory's flag and
45
+ // mode come off together, top-down, before anything inside it is read.
46
+ const REMOVE = [
47
+ 'd=$1',
48
+ 'if [ -L "$d" ]; then rm -f "$d"; exit $?; fi',
49
+ 'chmod -R u+rwx "$d" 2>/dev/null; m=$?',
50
+ 'if command -v chflags >/dev/null 2>&1; then',
51
+ ' [ $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',
52
+ ' chflags -R nouchg,nouappnd "$d" 2>/dev/null',
53
+ 'fi',
54
+ 'rm -rf "$d"',
55
+ ].join("\n");
56
+
57
+ /** Remove `path` through REMOVE; null on success, else the reason. */
58
+ export function removeEntry(path) {
59
+ const r = spawnSync("sh", ["-c", REMOVE, "sh", path], { encoding: "utf8" });
60
+ return r.error || r.status !== 0 ? how(r) : null;
61
+ }
62
+
63
+ const git = (tree, args) =>
64
+ spawnSync("git", ["-C", tree, ...args], { encoding: "utf8", maxBuffer: MAX_BUFFER, env: gitEnv(), timeout: GIT_TIMEOUT_MS });
65
+
66
+ /** Every path the tree ignores, relative to it, but the runner; throws what git cannot answer. */
67
+ export function ignoredPaths(tree) {
68
+ const r = git(tree, ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory"]);
69
+ if (r.error || r.status !== 0) throw new Error(`git ls-files --ignored failed (${how(r)})`);
70
+ const out = [];
71
+ for (const p of r.stdout.split("\0").filter(Boolean).sort()) {
72
+ const bare = p.replace(/\/$/, "");
73
+ if (bare === RUNNER) continue;
74
+ if (out.some((q) => q.endsWith("/") && p.startsWith(q))) continue;
75
+ out.push(p);
76
+ }
77
+ return out;
78
+ }
79
+
80
+ /** Remove each of `ignored` (relative to `tree`); null, or every error in one string. */
81
+ export function removeIgnored(tree, ignored) {
82
+ const errors = [];
83
+ for (const p of ignored) {
84
+ const error = removeEntry(join(tree, p.replace(/\/$/, "")));
85
+ if (error !== null) errors.push(`${p}: ${error}`);
86
+ }
87
+ return errors.length ? `could not remove ${errors.join("; ")}` : null;
88
+ }
89
+
90
+ // Whether `dir` is a tree: a `.git` of its own, and git answering for this
91
+ // directory rather than for an enclosing repository.
92
+ function isTree(dir) {
93
+ try {
94
+ lstatSync(join(dir, ".git"));
95
+ } catch {
96
+ return false;
97
+ }
98
+ const r = git(dir, ["rev-parse", "--show-toplevel"]);
99
+ if (r.error || r.status !== 0) return false;
100
+ try {
101
+ return realpathSync(r.stdout.replace(/\n$/, "")) === realpathSync(dir);
102
+ } catch {
103
+ return false;
104
+ }
105
+ }
106
+
107
+ /**
108
+ * Evict every tree under `root`, `root` itself included: `{evicted, failed}`.
109
+ * `evicted` is `[{path, ignored}]` for each tree that held ignored paths — in a
110
+ * dry run, what `apply` would remove — and a tree holding none is in neither.
111
+ * `failed` is `[{path, error}]`: a tree whose ignored paths cannot be listed or
112
+ * all removed, or a directory whose listing fails for any reason but its being
113
+ * gone, not a directory, or unreadable. Best-effort: the walk goes on.
114
+ */
115
+ export function evictTrees(root, { apply }) {
116
+ const evicted = [];
117
+ const failed = [];
118
+ const skip = new Set();
119
+ const stack = [root];
120
+ while (stack.length) {
121
+ const dir = stack.pop();
122
+ if (isTree(dir)) {
123
+ let ignored;
124
+ try {
125
+ ignored = ignoredPaths(dir);
126
+ } catch (e) {
127
+ failed.push({ path: dir, error: e.message });
128
+ continue;
129
+ }
130
+ for (const p of ignored) skip.add(join(dir, p.replace(/\/$/, "")));
131
+ if (ignored.length > 0) {
132
+ const error = apply ? removeIgnored(dir, ignored) : null;
133
+ if (error === null) evicted.push({ path: dir, ignored });
134
+ else failed.push({ path: dir, error });
135
+ }
136
+ }
137
+ let entries;
138
+ try {
139
+ entries = readdirSync(dir, { withFileTypes: true });
140
+ } catch (e) {
141
+ // A directory the walk cannot list or search holds no tree it can reach:
142
+ // skipped, as freshUnder() skips one it cannot read, and never a failure.
143
+ if (!["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(e.code)) failed.push({ path: dir, error: `cannot list it (${e.code ?? e.message})` });
144
+ continue;
145
+ }
146
+ for (const e of entries) {
147
+ if (e.name === ".git" || !e.isDirectory()) continue;
148
+ const path = join(dir, e.name);
149
+ if (!skip.has(path)) stack.push(path);
150
+ }
151
+ }
152
+ const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
153
+ return { evicted: evicted.sort(byPath), failed: failed.sort(byPath) };
154
+ }
package/scripts/evict.mjs CHANGED
@@ -54,7 +54,7 @@
54
54
  //
55
55
  // `--apply` judges each tree to evict again, writes the mark (EVICTED, a file
56
56
  // in the tree's git admin dir) unless the tree carries it already, then removes
57
- // every ignored path but the runner through reclaim-scratch.mjs's one removal
57
+ // every ignored path but the runner through evict-tree.mjs's one removal
58
58
  // sequence. Tracked files, HEAD, the branch and the registration are not
59
59
  // touched. Best-effort per tree: a tree whose mark cannot be written, or a path
60
60
  // in it that cannot be removed, lands in `failed`; the sweep goes on. A mark
@@ -99,10 +99,11 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
99
99
  import { fileURLToPath } from "node:url";
100
100
  import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
101
101
  import { adminDir, EVICTED, evictionMark, how, RESTORED } from "./evict-mark.mjs";
102
+ import { RUNNER, ignoredPaths, removeIgnored } from "./evict-tree.mjs";
102
103
  import { gitEnv } from "./git-env.mjs";
103
104
  import { isCLI } from "./is-cli.mjs";
104
105
  import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
105
- import { ledgerFile, readLedger, removeEntry } from "./reclaim-scratch.mjs";
106
+ import { ledgerFile, readLedger } from "./reclaim-scratch.mjs";
106
107
  import { CLAIM_BRANCH, CLAIM_WORKTREE } from "./stranded.mjs";
107
108
 
108
109
  const NAME = "evict";
@@ -114,7 +115,6 @@ const DAY_MS = 24 * 60 * 60 * 1000;
114
115
  export const IDLE_MS = 7 * DAY_MS;
115
116
  /** Whether a tree whose HEAD last moved, or which was last restored, at `last` is idle at `now`. */
116
117
  export const isIdle = (now, last) => now - last >= IDLE_MS;
117
- const RUNNER = "agent-test";
118
118
  const GIT_TIMEOUT_MS = 30_000;
119
119
  const MAX_BUFFER = 64 * 1024 * 1024;
120
120
  // claim-ticket.sh's `rederive`, word for word. The refusals that send their
@@ -277,21 +277,6 @@ function restoredAt(dir) {
277
277
  return at;
278
278
  }
279
279
 
280
- // Every path the tree ignores, relative to it, but the runner — a directory
281
- // git lists whole once, and nothing listed inside one already listed.
282
- function ignoredPaths(tree) {
283
- const r = git(tree, ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory"]);
284
- if (r.error || r.status !== 0) throw new Error(`git ls-files --ignored failed (${how(r)})`);
285
- const out = [];
286
- for (const p of r.stdout.split("\0").filter(Boolean).sort()) {
287
- const bare = p.replace(/\/$/, "");
288
- if (bare === RUNNER) continue;
289
- if (out.some((q) => q.endsWith("/") && p.startsWith(q))) continue;
290
- out.push(p);
291
- }
292
- return out;
293
- }
294
-
295
280
  const within = (path, root) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
296
281
 
297
282
  /**
@@ -370,12 +355,7 @@ function evictTree(path, verdict, now) {
370
355
  return `could not write ${join(verdict.dir, EVICTED)} (${e.code ?? e.message}), so nothing was removed`;
371
356
  }
372
357
  }
373
- const errors = [];
374
- for (const p of verdict.ignored) {
375
- const error = removeEntry(join(path, p.replace(/\/$/, "")));
376
- if (error !== null) errors.push(`${p}: ${error}`);
377
- }
378
- return errors.length ? `could not remove ${errors.join("; ")}` : null;
358
+ return removeIgnored(path, verdict.ignored);
379
359
  }
380
360
 
381
361
  function sweep({ afterRotate, apply }) {
@@ -113,9 +113,10 @@ function workspaceOf(cwd, timeoutMs, canonicalise) {
113
113
  * the run's file in someone else's workspace, silently, at exit 0.
114
114
  *
115
115
  * `canonicalise` is git-env.mjs's resolveWorkspace() opt-in, passed through:
116
- * only a caller that keys something on the path (the cockpit's port) takes
117
- * it. Everyone else prints the path it resolves, and realpath would change
118
- * that spelling without changing which file it names.
116
+ * only a caller that keys something on the path takes it — the cockpit's
117
+ * port, a scratch key's `checkout-path`. Everyone else prints the path it
118
+ * resolves, and realpath would change that spelling without changing which
119
+ * file it names.
119
120
  *
120
121
  * `timeoutMs` (default git-env.mjs's DEFAULT_GIT_TIMEOUT_MS) bounds each git
121
122
  * child, not the call. When the common git dir is not named `.git` and the
@@ -90,7 +90,9 @@
90
90
  // then `reclaim-scratch.mjs --siblings --root <scratch> --apply`
91
91
  // for the other keys under the scratch parent, which runs
92
92
  // whatever the first answered. What either receipt's failed[]
93
- // names is listed. Recorded; never fails the run.
93
+ // names is listed, and so, from the sibling pass's receipt, is
94
+ // each key removed and each kept with nothing modified within
95
+ // 7 days, with its reason. Recorded; never fails the run.
94
96
  // evict `evict.mjs --after-rotate --apply`, straight after the
95
97
  // reclaim: the claim trees idle past evict.mjs's bound lose
96
98
  // their installed dependencies. A non-zero exit, and each
@@ -436,7 +438,7 @@ function reclaim({ cwd, scratch }) {
436
438
  return ok([
437
439
  live.status === 0 ? "scratch reclaimed" : withText(`reclaim-scratch.mjs ${live.how}, not enforced`, live),
438
440
  ...unreclaimed("scratch root", live),
439
- ...(siblings.status === 0 ? unreclaimed("sibling keys", siblings) : [withText(`sibling keys: reclaim-scratch.mjs ${siblings.how}, not enforced`, siblings)]),
441
+ ...(siblings.status === 0 ? unreclaimed("sibling keys", siblings, { named: true }) : [withText(`sibling keys: reclaim-scratch.mjs ${siblings.how}, not enforced`, siblings)]),
440
442
  ].join("\n"));
441
443
  }
442
444
 
@@ -449,17 +451,29 @@ function evict({ cwd }) {
449
451
  }
450
452
 
451
453
  // A pass that exited 0 still lists in its receipt's `failed[]` what it could
452
- // not judge or remove: each is named here, and none fails the step.
453
- function unreclaimed(what, r, { script = "reclaim-scratch.mjs", verb = "reclaim" } = {}) {
454
+ // not judge or remove: each is named here, and none fails the step. `named`
455
+ // (the sibling pass) also names each entry the receipt's `removed[]` holds and
456
+ // each in `kept[]` whose `idle` is true: a key kept while it is still being
457
+ // written to is not news.
458
+ function unreclaimed(what, r, { script = "reclaim-scratch.mjs", verb = "reclaim", named = false } = {}) {
454
459
  if (r.status !== 0) return [];
455
- let entries;
460
+ let receipt;
456
461
  try {
457
- ({ failed: entries } = JSON.parse(r.stdout));
462
+ receipt = JSON.parse(r.stdout);
458
463
  } catch (e) {
459
464
  return [`${what}: could not read ${script}'s receipt: ${e.message}`];
460
465
  }
461
- if (!Array.isArray(entries)) return [`${what}: ${script}'s receipt holds no failed[]`];
462
- return entries.map((x) => `${what}: could not ${verb} ${x?.path} (${x?.error})`);
466
+ const { failed: entries, removed, kept } = receipt ?? {};
467
+ const out = [];
468
+ if (named) {
469
+ if (!Array.isArray(removed) || !Array.isArray(kept)) out.push(`${what}: ${script}'s receipt holds no removed[] or kept[]`);
470
+ else {
471
+ out.push(...removed.map((x) => `${what}: removed ${x?.path} (${x?.reason})`));
472
+ out.push(...kept.filter((x) => x?.idle === true).map((x) => `${what}: kept ${x.path} (${x.reason})`));
473
+ }
474
+ }
475
+ if (!Array.isArray(entries)) return [...out, `${what}: ${script}'s receipt holds no failed[]`];
476
+ return [...out, ...entries.map((x) => `${what}: could not ${verb} ${x?.path} (${x?.error})`)];
463
477
  }
464
478
 
465
479
  function recipe({ cwd }) {
@@ -20,11 +20,13 @@
20
20
  // judged against this one's numbers.
21
21
  //
22
22
  // `--siblings` is the sibling pass, its own invocation: `--root` names the
23
- // live key, and the pass judges the other key-shaped directories beside it by
24
- // age alone (judgeSiblings below), judging each again just before `--apply`
25
- // removes it. Any other key passed as `--root` would put the real live key
26
- // among the judged siblings. It reads no ledger and is never combined with
27
- // --pr or --after-rotate.
23
+ // live key, and the pass judges the other key-shaped directories beside it
24
+ // (judgeSiblings below) by the checkout each records and by age, judging each
25
+ // again just before `--apply` removes it. Under `--apply` it first writes the
26
+ // live key's own `checkout-path`, and only that. Any other key passed as
27
+ // `--root` would put the real live key among the judged siblings. It reads no
28
+ // ledger, asks GitHub nothing, and is never combined with --pr or
29
+ // --after-rotate.
28
30
  //
29
31
  // THE ROOT SWEEP judges every entry directly under `--root`:
30
32
  // pr<M>/, dispositions-fix-pr-<M>[-x].json
@@ -74,6 +76,9 @@
74
76
  // nothing
75
77
  // removed when idle past the retention and no live token's name
76
78
  // appears in the entry's name.
79
+ // checkout-path
80
+ // never judged: the sibling pass's record of the checkout the key
81
+ // belongs to, neither removed nor listed.
77
82
  // "Idle past the retention" is the newest mtime ANYWHERE under the entry
78
83
  // older than 7 days — never the top-level mtime alone, which a write deep
79
84
  // inside does not move. A directory that cannot be listed or searched counts
@@ -96,12 +101,16 @@
96
101
  // alone in GitHub's place.
97
102
  //
98
103
  // `--pr <N>` MODE is the review snapshot's prune: every directory
99
- // `<root>/pr<N>/run-*` idle past the retention is removed, and nothing else
100
- // is looked at — no ledger, no gh (a live review's own run root is seconds
101
- // old), no sibling under pr<N>/.
104
+ // `<root>/pr<N>/run-*` idle past the retention is removed whole, and every
105
+ // other one has the trees in it evicted — each directory that holds a .git of
106
+ // its own, at any depth, loses every path git ignores in it, which is
107
+ // evict-tree.mjs's rule: tracked files, each .git, untracked files git does not
108
+ // ignore and everything in the run root outside a tree stay. Nothing else is
109
+ // looked at — no ledger, no gh (a live review's own run root is seconds old
110
+ // and holds no tree yet), no sibling under pr<N>/.
102
111
  //
103
- // EVERY REMOVAL, in either mode, goes through REMOVE below: owner rwx
104
- // restored, darwin's user-immutable and append-only flags cleared where
112
+ // EVERY REMOVAL, in either mode, goes through evict-tree.mjs's REMOVE: owner
113
+ // rwx restored, darwin's user-immutable and append-only flags cleared where
105
114
  // `chflags` exists, then `rm -rf` — so a fixture that dropped its own read bit
106
115
  // or flagged a file cannot wedge it. Removal is best-effort per entry: a
107
116
  // failure lands in `failed[]` and the sweep continues.
@@ -109,10 +118,14 @@
109
118
  // Prints ONE JSON line on stdout once the sweep is done:
110
119
  // {"applied":<bool>,"ledger":<abs path|null>,"removed":[{"path","reason"}],
111
120
  // "kept":[{"path","reason"}],"failed":[{"path","error"}]}
121
+ // The sibling pass's kept entries also carry "idle": true when nothing under
122
+ // the key was found modified within the retention, false otherwise.
123
+ // `--pr` mode adds `"evicted":[{"path","reason","ignored"}]` after `removed`:
124
+ // each tree that held ignored paths, `ignored` naming them.
112
125
  // `ledger` is the file read, or null when none was (`--pr` mode, or
113
126
  // `--after-rotate` with no file) — so "never read" stays distinct from "read
114
127
  // and found empty". A dry run prints the same receipt with "applied":false,
115
- // `removed` naming what --apply would remove.
128
+ // `removed` and `evicted` naming what --apply would remove.
116
129
  // Exit 0 whenever the receipt is printed, failures included; 2 for a refused
117
130
  // invocation — bad arguments, no --root, a root that is not a directory, a
118
131
  // root sweep or sibling pass whose --root is not this workspace's own scratch
@@ -121,10 +134,12 @@
121
134
  // other than ENOENT. Nothing is removed before a refusal.
122
135
 
123
136
  import { spawnSync } from "node:child_process";
124
- import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
137
+ import { createHash } from "node:crypto";
138
+ import { lstatSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
125
139
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
126
140
  import { fileURLToPath } from "node:url";
127
141
  import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
142
+ import { evictTrees, removeEntry } from "./evict-tree.mjs";
128
143
  import { fleetFile, FleetDirUnresolvable, SCRATCH_KEY_SHAPE, scratchRoot } from "./fleet-dir.mjs";
129
144
  import { gitEnv } from "./git-env.mjs";
130
145
  import { ghAliasedRead, how } from "./gh-aliased-read.mjs";
@@ -133,32 +148,15 @@ import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
133
148
  import { REVIEWS_DIR, reviewTargets } from "./run-records.mjs";
134
149
 
135
150
  const NAME = "reclaim-scratch";
151
+ // The file at a key's top level naming the checkout the key's hash is taken
152
+ // over: one line, an absolute path.
153
+ export const CHECKOUT_FILE = "checkout-path";
136
154
  const die = makeDie(NAME);
137
155
  const DAY_MS = 24 * 60 * 60 * 1000;
138
156
  export const RETENTION_MS = 7 * DAY_MS;
139
157
  const GH_TIMEOUT_MS = 30_000;
140
158
  const MAX_BUFFER = 64 * 1024 * 1024;
141
159
 
142
- // The one removal sequence. `$1` is the entry. A symlink entry is unlinked
143
- // before anything else runs, so no chmod or chflags ever sees it: whether a
144
- // recursive chmod dereferences a link given as its operand differs between
145
- // BSD and GNU, and either would change the mode or flags of a target outside
146
- // the entry being removed. Links met inside a directory are left to `rm`,
147
- // which unlinks them without following. `chmod -R` fails
148
- // on a flagged directory, and `chflags -R` cannot read a mode-000 directory it
149
- // has just unflagged, so when the first pass fails each directory's flag and
150
- // mode come off together, top-down, before anything inside it is read.
151
- const REMOVE = [
152
- 'd=$1',
153
- 'if [ -L "$d" ]; then rm -f "$d"; exit $?; fi',
154
- 'chmod -R u+rwx "$d" 2>/dev/null; m=$?',
155
- 'if command -v chflags >/dev/null 2>&1; then',
156
- ' [ $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',
157
- ' chflags -R nouchg,nouappnd "$d" 2>/dev/null',
158
- 'fi',
159
- 'rm -rf "$d"',
160
- ].join("\n");
161
-
162
160
  const PR_ENTRY = /^pr([1-9][0-9]*)$/;
163
161
  const IMPL_ENTRY = /^impl-([1-9][0-9]*)$/;
164
162
  const DISPOSITIONS_ENTRY = /^dispositions-fix-pr-([1-9][0-9]*)(?:-[a-z])?\.json$/;
@@ -204,12 +202,6 @@ export function freshUnder(path, cutoff, unreadable = null) {
204
202
  return null;
205
203
  }
206
204
 
207
- /** Remove `path` through REMOVE; null on success, else the reason. */
208
- export function removeEntry(path) {
209
- const r = spawnSync("sh", ["-c", REMOVE, "sh", path], { encoding: "utf8" });
210
- return r.error || r.status !== 0 ? how(r) : null;
211
- }
212
-
213
205
  // The ledger's rows and `## Dispatched` entries, read through `ledger.mjs
214
206
  // read` so the ledger keeps one parser. `--file` names it outright, so the read
215
207
  // resolves no workspace and runs no git. `die` is the caller's, and `undone`
@@ -392,6 +384,8 @@ function judgeRoot(root, names, live, now, listing, checkout) {
392
384
  // idle directory.
393
385
  const entries = [];
394
386
  for (const name of names) {
387
+ // The sibling pass's record of whose key this is: never this sweep's to judge.
388
+ if (name === CHECKOUT_FILE) continue;
395
389
  const path = join(root, name);
396
390
  let isDir = false;
397
391
  try {
@@ -528,11 +522,10 @@ function staleRunRoots(parent, cutoff, kept) {
528
522
  }
529
523
 
530
524
  // THE SIBLING PASS judges every key-shaped directory directly under the scratch
531
- // parent of `root`, other than the live key, by age alone: one with nothing
532
- // modified within the retention goes whole; one with anything fresh stays whole,
533
- // and so does one with any part that could not be read, since what that part
534
- // holds is unknown. Other entries under the parent, links and the live key are
535
- // not judged at all. The keys are judged in name order.
525
+ // parent of `root`, other than the live key, by the checkout its
526
+ // `checkout-path` names (judgeSibling below) and by age. Other entries under
527
+ // the parent, links and the live key are not judged at all. The keys are
528
+ // judged in name order.
536
529
  function judgeSiblings(root, cutoff) {
537
530
  const parent = dirname(root);
538
531
  const live = basename(root);
@@ -550,18 +543,103 @@ function judgeSiblings(root, cutoff) {
550
543
  failed.push({ path, error: e.message });
551
544
  continue;
552
545
  }
553
- (verdict.idle ? remove : kept).push({ path, reason: verdict.reason });
546
+ if (verdict.remove) remove.push({ path, reason: verdict.reason });
547
+ else kept.push({ path, reason: verdict.reason, idle: verdict.idle });
554
548
  }
555
549
  return { remove, kept, failed };
556
550
  }
557
551
 
558
- // One sibling key's verdict: `idle` only when nothing under it is fresh and
559
- // every part of it could be read.
552
+ // A read of `checkout-path` that leaves no file to judge, rather than an error.
553
+ const NO_CHECKOUT_FILE = new Set(["ENOENT", "ENOTDIR", "EISDIR", "EACCES", "EPERM"]);
554
+
555
+ // The checkout `key`'s `checkout-path` names, `{ checkout }`, or the `{ reason }`
556
+ // the key is kept for instead: `no checkout file: …` when there is no valid
557
+ // file — missing, unreadable, not a regular file, anything but one absolute
558
+ // path, or a path whose sha256 does not start with the key's 8-hex suffix —
559
+ // or the error any other failure to read it left. Only a regular file is read:
560
+ // a FIFO there would block the pass and a link to a device such as /dev/zero
561
+ // would never end.
562
+ function checkoutOf(key) {
563
+ const file = join(key, CHECKOUT_FILE);
564
+ const none = (why) => ({ reason: `no checkout file: ${why}` });
565
+ let text;
566
+ try {
567
+ if (!lstatSync(file).isFile()) return none(`${CHECKOUT_FILE} is not a regular file`);
568
+ text = readFileSync(file, "utf8");
569
+ } catch (e) {
570
+ if (NO_CHECKOUT_FILE.has(e.code)) return none(e.code === "ENOENT" ? `${CHECKOUT_FILE} is missing` : `${CHECKOUT_FILE} cannot be read (${e.code})`);
571
+ return { reason: `its ${CHECKOUT_FILE} cannot be read: ${e.message}` };
572
+ }
573
+ const line = text.endsWith("\n") ? text.slice(0, -1) : text;
574
+ if (line.includes("\n") || !isAbsolute(line)) return none(`${CHECKOUT_FILE} holds no single absolute path`);
575
+ const suffix = basename(key).slice(-8);
576
+ if (!createHash("sha256").update(line).digest("hex").startsWith(suffix)) return none(`${line} does not hash to the key's suffix ${suffix}`);
577
+ return { checkout: line };
578
+ }
579
+
580
+ // Whether anything exists at `p` (lstat): true, false, or the error that
581
+ // leaves it unknown.
582
+ function existsAt(p) {
583
+ try {
584
+ lstatSync(p);
585
+ return true;
586
+ } catch (e) {
587
+ if (e.code === "ENOENT" || e.code === "ENOTDIR") return false;
588
+ return e;
589
+ }
590
+ }
591
+
592
+ // One sibling key's verdict, `{remove, reason, idle}`. `idle` is whether
593
+ // nothing under the key was found modified within the retention, searched for
594
+ // every key. Removed only when its checkout file is valid, nothing exists at
595
+ // the checkout it names, the directory that held that checkout does exist,
596
+ // nothing under the key is fresh and every part of it could be read. A key
597
+ // whose checkout still exists is its own phase 0's to reclaim; one whose
598
+ // checkout's parent is gone too may sit on an unplugged drive.
560
599
  function judgeSibling(path, cutoff) {
561
600
  const unreadable = [];
562
- if (freshUnder(path, cutoff, unreadable) !== null) return { idle: false, reason: "sibling key modified within 7 days" };
563
- if (unreadable.length > 0) return { idle: false, reason: `sibling key could not be read whole (${unreadable[0]})` };
564
- return { idle: true, reason: "sibling key idle past 7 days" };
601
+ const idle = freshUnder(path, cutoff, unreadable) === null;
602
+ const keep = (reason) => ({ remove: false, reason, idle });
603
+ const found = checkoutOf(path);
604
+ if (found.reason !== undefined) return keep(found.reason);
605
+ const { checkout } = found;
606
+ const at = existsAt(checkout);
607
+ if (at instanceof Error) return keep(`whether its checkout ${checkout} exists cannot be told: ${at.message}`);
608
+ if (at) return keep(`its checkout ${checkout} still exists, so its own phase 0 reclaims it`);
609
+ const held = dirname(checkout);
610
+ const up = existsAt(held);
611
+ if (up instanceof Error) return keep(`whether ${held}, the directory that held its checkout ${checkout}, exists cannot be told: ${up.message}`);
612
+ if (!up) return keep(`neither its checkout ${checkout} nor ${held}, the directory that held it, exists`);
613
+ if (!idle) return keep("sibling key modified within 7 days");
614
+ if (unreadable.length > 0) return keep(`sibling key could not be read whole (${unreadable[0]})`);
615
+ return { remove: true, reason: `its checkout ${checkout} is gone and nothing under it changed in 7 days`, idle: true };
616
+ }
617
+
618
+ // The live key's own `checkout-path`, written when it is missing or says
619
+ // anything but this workspace's canonical path: a temp file in the key,
620
+ // renamed over it. A failure is returned as a failed[] entry, null otherwise.
621
+ function writeCheckout(root) {
622
+ const file = join(root, CHECKOUT_FILE);
623
+ let checkout;
624
+ try {
625
+ checkout = dirname(fleetFile(null, { canonicalise: true }));
626
+ } catch (e) {
627
+ return { path: file, error: e.message };
628
+ }
629
+ if (checkoutOf(root).checkout === checkout) return null;
630
+ const tmp = join(root, `.${CHECKOUT_FILE}.${process.pid}.tmp`);
631
+ try {
632
+ writeFileSync(tmp, `${checkout}\n`);
633
+ renameSync(tmp, file);
634
+ } catch (e) {
635
+ try {
636
+ rmSync(tmp, { force: true });
637
+ } catch {
638
+ // left for the root sweep to age out
639
+ }
640
+ return { path: file, error: e.message };
641
+ }
642
+ return null;
565
643
  }
566
644
 
567
645
  function main() {
@@ -608,6 +686,8 @@ function main() {
608
686
 
609
687
  const now = Date.now();
610
688
  let ledger = null;
689
+ // `--pr` mode's evictions; null in every other mode.
690
+ let evicted = null;
611
691
  let remove;
612
692
  let kept = [];
613
693
  const failed = [];
@@ -619,7 +699,18 @@ function main() {
619
699
  remove = [];
620
700
  failed.push({ path: parent, error: e.message });
621
701
  }
702
+ // `--pr` mode also evicts the trees in every run root it keeps.
703
+ evicted = [];
704
+ for (const run of kept) {
705
+ const done = evictTrees(run.path, { apply });
706
+ for (const t of done.evicted) evicted.push({ path: t.path, reason: "a tree in a kept review run root", ignored: t.ignored });
707
+ failed.push(...done.failed);
708
+ }
622
709
  } else if (siblings) {
710
+ if (apply) {
711
+ const wrote = writeCheckout(root);
712
+ if (wrote !== null) failed.push(wrote);
713
+ }
623
714
  try {
624
715
  const judged = judgeSiblings(root, now - RETENTION_MS);
625
716
  remove = judged.remove;
@@ -653,11 +744,12 @@ function main() {
653
744
  let error;
654
745
  try {
655
746
  // A sibling key belongs to another workspace's runs, which can write to it
656
- // while an earlier key is still being removed: it is judged again here, so
657
- // a key that turned fresh since the pass judged it is kept.
747
+ // or bring its checkout back while an earlier key is still being removed:
748
+ // its whole verdict is taken again here, so a key no longer removable is
749
+ // kept.
658
750
  const again = siblings ? judgeSibling(entry.path, now - RETENTION_MS) : null;
659
- if (again !== null && !again.idle) {
660
- kept.push({ path: entry.path, reason: again.reason });
751
+ if (again !== null && !again.remove) {
752
+ kept.push({ path: entry.path, reason: again.reason, idle: again.idle });
661
753
  continue;
662
754
  }
663
755
  error = removeEntry(entry.path);
@@ -667,7 +759,8 @@ function main() {
667
759
  if (error === null) removed.push(entry);
668
760
  else failed.push({ path: entry.path, error });
669
761
  }
670
- writeAll(1, `${JSON.stringify({ applied: apply, ledger, removed, kept, failed })}\n`);
762
+ const receipt = { applied: apply, ledger, removed, ...(evicted === null ? {} : { evicted }), kept, failed };
763
+ writeAll(1, `${JSON.stringify(receipt)}\n`);
671
764
  }
672
765
 
673
766
  if (isCLI(import.meta.url)) main();
@@ -23,12 +23,14 @@
23
23
  // `null`, which every guard here — `if (snap) {...}`, `unrunCrashed`,
24
24
  // `verdictFor` — is written against).
25
25
  //
26
- // Three imports. arg.mjs's isDigits(): this file is an ordinary
26
+ // The imports. arg.mjs's isDigits(): this file is an ordinary
27
27
  // module, so it consumes the repo's digits rule directly rather than
28
28
  // declaring its own copy. node:path's `posix`, to normalise a
29
29
  // scratch path before `runnerScratchRefusal` reads its last component, and
30
- // its `isAbsolute`, to refuse a scratch that is not an absolute path.
31
- // fleet-dir.mjs's scratchRoot(), scratchRootRefusal() and FleetDirUnresolvable.
30
+ // its `isAbsolute`, to refuse a scratch that is not an absolute path; node:fs's
31
+ // `lstatSync`, to tell a real run-root directory from a symlink before the
32
+ // review's end evicts the trees in it. evict-tree.mjs's evictTrees(), which does
33
+ // that eviction. fleet-dir.mjs's scratchRoot(), scratchRootRefusal() and FleetDirUnresolvable.
32
34
  // scratchRoot() and FleetDirUnresolvable serve the one caller that passes no
33
35
  // `scratch` at all — a standalone review with no dispatcher — which takes the
34
36
  // fleet's own scratch root for this repository; scratchRootRefusal() vets every
@@ -41,8 +43,10 @@
41
43
  // review-eval.mjs's import of it failed. A suite sweep keeps a
42
44
  // shipped `.mjs` from importing a relative module under any other extension.
43
45
 
46
+ import { lstatSync } from "node:fs";
44
47
  import { isAbsolute, posix } from "node:path";
45
48
  import { isDigits } from "./arg.mjs";
49
+ import { evictTrees } from "./evict-tree.mjs";
46
50
  import { FleetDirUnresolvable, scratchRoot, scratchRootRefusal } from "./fleet-dir.mjs";
47
51
 
48
52
  // --- Schemas ----------------------------------------------------------
@@ -1003,7 +1007,65 @@ function standaloneScratchRoot() {
1003
1007
  return root;
1004
1008
  }
1005
1009
 
1010
+ /**
1011
+ * The review. When it returns or throws after its snapshot step has reported a
1012
+ * run root of this PR, it evicts every tree in that run root: the snapshot and
1013
+ * each specialist's and refuter's copy lose every path git ignores in them,
1014
+ * and nothing restores them. The run root's other files stay, review.json
1015
+ * among them. A failed eviction, and a reported run root it refuses to touch,
1016
+ * are logged; neither, nor a log that throws, changes what the review returns
1017
+ * or throws. A snapshot step that reported no run root evicts nothing and
1018
+ * logs nothing.
1019
+ */
1006
1020
  export async function runReview(host, args) {
1021
+ const run = { partition: null, runRoot: null };
1022
+ try {
1023
+ return await reviewRun(host, args, run);
1024
+ } finally {
1025
+ evictRunRoot(host.log, run);
1026
+ }
1027
+ }
1028
+
1029
+ // A reported run root eviction may touch: this PR's partition of the scratch
1030
+ // root — the very string the snapshot step's `mktemp` template starts with, so
1031
+ // a scratch spelled with a trailing slash or a `./` segment still matches — a
1032
+ // slash, `run-` and the eight `mktemp` characters, and nothing after — so no
1033
+ // `..` segment, no trailing slash, no other directory. It must also be a real
1034
+ // directory, not a symlink.
1035
+ function evictableRunRoot(runRoot, partition) {
1036
+ if (!runRoot.startsWith(`${partition}/`)) return false;
1037
+ if (!/^run-[A-Za-z0-9]{8}$/.test(runRoot.slice(partition.length + 1))) return false;
1038
+ try {
1039
+ return lstatSync(partition).isDirectory() && lstatSync(runRoot).isDirectory();
1040
+ } catch {
1041
+ return false;
1042
+ }
1043
+ }
1044
+
1045
+ // `run.runRoot` is set only once `run.partition` is, so a run root implies a
1046
+ // partition.
1047
+ function evictRunRoot(log, { partition, runRoot }) {
1048
+ const say = (m) => {
1049
+ try {
1050
+ log(m);
1051
+ } catch {
1052
+ // The review's own outcome stands whatever the log sink does.
1053
+ }
1054
+ };
1055
+ if (runRoot === null) return;
1056
+ try {
1057
+ if (!evictableRunRoot(runRoot, partition)) {
1058
+ say(`no eviction at the end of the review: the reported run root ${runRoot} is not a real directory named run- and eight characters directly in ${partition}`);
1059
+ return;
1060
+ }
1061
+ const done = evictTrees(runRoot, { apply: true });
1062
+ for (const f of done.failed) say(`eviction at the end of the review failed in ${f.path}: ${f.error}`);
1063
+ } catch (e) {
1064
+ say(`eviction at the end of the review failed in ${runRoot}: ${e?.message ?? e}`);
1065
+ }
1066
+ }
1067
+
1068
+ async function reviewRun(host, args, run) {
1007
1069
  const { agent, phase, log } = host;
1008
1070
  const pipeline = host.pipeline ?? defaultPipeline;
1009
1071
  const parallel = host.parallel ?? defaultParallel;
@@ -1069,6 +1131,7 @@ export async function runReview(host, args) {
1069
1131
  const rootRefusal = scratchRootRefusal(scratch);
1070
1132
  if (rootRefusal !== null) throw new Error(`review-pr: args.scratch: ${rootRefusal}`);
1071
1133
  }
1134
+ run.partition = runRootParent;
1072
1135
 
1073
1136
  const explicitDimensions = resolveDimensions(A.dimensions, DEFAULT_DIMENSIONS);
1074
1137
 
@@ -1255,6 +1318,9 @@ installError only replaces installCmd and installExit, and uncoveredError only
1255
1318
  replaces uncovered.`,
1256
1319
  { label: `snapshot${forPr}`, phase: "Snapshot", agentType: SNAPSHOT_AGENT_TYPE, schema: SNAPSHOT_SCHEMA },
1257
1320
  );
1321
+ // From here the run root the snapshot step made is known, whatever the
1322
+ // report says next: runReview's end evicts the trees in it.
1323
+ if (snap && typeof snap.runRoot === "string") run.runRoot = snap.runRoot;
1258
1324
 
1259
1325
  if (snap) {
1260
1326
  if (typeof snap.head === "string") snap.head = snap.head.trim().toLowerCase();
@@ -443,11 +443,15 @@ its reason — and exits 0 even when a removal failed; record nothing on the
443
443
  ledger.
444
444
 
445
445
  Straight after that, the same step reclaims the other keys under the scratch parent:
446
- `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --siblings --root <scratch> --apply`. A key
447
- goes whole when nothing under it has changed in 7 days, and stays whole otherwise. The
448
- call runs whatever the root sweep answered, and records nothing on the ledger. A non-zero
449
- exit, and each path its receipt's `failed[]` names, is listed in the step's output; neither
450
- stops the run.
446
+ `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --siblings --root <scratch> --apply`. It
447
+ first writes this key's `checkout-path`, the checkout the key was computed from. A
448
+ sibling key goes whole only when the checkout its `checkout-path` names is gone, the
449
+ directory that held it is still there, and nothing under the key has changed in 7 days;
450
+ every other key stays whole, a key with no valid `checkout-path` included. The call asks
451
+ GitHub nothing, runs whatever the root sweep answered, and records nothing on the ledger.
452
+ The step's output names each sibling key removed and each kept with nothing changed in 7
453
+ days, with the reason. A non-zero exit, and each path its receipt's `failed[]` names, is
454
+ listed there too; neither stops the run.
451
455
 
452
456
  ## Evict idle claim trees
453
457