@feigi/fleet-ctl 3.151.1 → 3.151.2

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.151.2",
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";
@@ -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
@@ -109,6 +114,8 @@
109
114
  // Prints ONE JSON line on stdout once the sweep is done:
110
115
  // {"applied":<bool>,"ledger":<abs path|null>,"removed":[{"path","reason"}],
111
116
  // "kept":[{"path","reason"}],"failed":[{"path","error"}]}
117
+ // The sibling pass's kept entries also carry "idle": true when nothing under
118
+ // the key was found modified within the retention, false otherwise.
112
119
  // `ledger` is the file read, or null when none was (`--pr` mode, or
113
120
  // `--after-rotate` with no file) — so "never read" stays distinct from "read
114
121
  // and found empty". A dry run prints the same receipt with "applied":false,
@@ -121,7 +128,8 @@
121
128
  // other than ENOENT. Nothing is removed before a refusal.
122
129
 
123
130
  import { spawnSync } from "node:child_process";
124
- import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
131
+ import { createHash } from "node:crypto";
132
+ import { lstatSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
125
133
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
126
134
  import { fileURLToPath } from "node:url";
127
135
  import { defineFlags, isDigits, makeDie, writeAll } from "./arg.mjs";
@@ -133,6 +141,9 @@ import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
133
141
  import { REVIEWS_DIR, reviewTargets } from "./run-records.mjs";
134
142
 
135
143
  const NAME = "reclaim-scratch";
144
+ // The file at a key's top level naming the checkout the key's hash is taken
145
+ // over: one line, an absolute path.
146
+ export const CHECKOUT_FILE = "checkout-path";
136
147
  const die = makeDie(NAME);
137
148
  const DAY_MS = 24 * 60 * 60 * 1000;
138
149
  export const RETENTION_MS = 7 * DAY_MS;
@@ -392,6 +403,8 @@ function judgeRoot(root, names, live, now, listing, checkout) {
392
403
  // idle directory.
393
404
  const entries = [];
394
405
  for (const name of names) {
406
+ // The sibling pass's record of whose key this is: never this sweep's to judge.
407
+ if (name === CHECKOUT_FILE) continue;
395
408
  const path = join(root, name);
396
409
  let isDir = false;
397
410
  try {
@@ -528,11 +541,10 @@ function staleRunRoots(parent, cutoff, kept) {
528
541
  }
529
542
 
530
543
  // 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.
544
+ // parent of `root`, other than the live key, by the checkout its
545
+ // `checkout-path` names (judgeSibling below) and by age. Other entries under
546
+ // the parent, links and the live key are not judged at all. The keys are
547
+ // judged in name order.
536
548
  function judgeSiblings(root, cutoff) {
537
549
  const parent = dirname(root);
538
550
  const live = basename(root);
@@ -550,18 +562,103 @@ function judgeSiblings(root, cutoff) {
550
562
  failed.push({ path, error: e.message });
551
563
  continue;
552
564
  }
553
- (verdict.idle ? remove : kept).push({ path, reason: verdict.reason });
565
+ if (verdict.remove) remove.push({ path, reason: verdict.reason });
566
+ else kept.push({ path, reason: verdict.reason, idle: verdict.idle });
554
567
  }
555
568
  return { remove, kept, failed };
556
569
  }
557
570
 
558
- // One sibling key's verdict: `idle` only when nothing under it is fresh and
559
- // every part of it could be read.
571
+ // A read of `checkout-path` that leaves no file to judge, rather than an error.
572
+ const NO_CHECKOUT_FILE = new Set(["ENOENT", "ENOTDIR", "EISDIR", "EACCES", "EPERM"]);
573
+
574
+ // The checkout `key`'s `checkout-path` names, `{ checkout }`, or the `{ reason }`
575
+ // the key is kept for instead: `no checkout file: …` when there is no valid
576
+ // file — missing, unreadable, not a regular file, anything but one absolute
577
+ // path, or a path whose sha256 does not start with the key's 8-hex suffix —
578
+ // or the error any other failure to read it left. Only a regular file is read:
579
+ // a FIFO there would block the pass and a link to a device such as /dev/zero
580
+ // would never end.
581
+ function checkoutOf(key) {
582
+ const file = join(key, CHECKOUT_FILE);
583
+ const none = (why) => ({ reason: `no checkout file: ${why}` });
584
+ let text;
585
+ try {
586
+ if (!lstatSync(file).isFile()) return none(`${CHECKOUT_FILE} is not a regular file`);
587
+ text = readFileSync(file, "utf8");
588
+ } catch (e) {
589
+ if (NO_CHECKOUT_FILE.has(e.code)) return none(e.code === "ENOENT" ? `${CHECKOUT_FILE} is missing` : `${CHECKOUT_FILE} cannot be read (${e.code})`);
590
+ return { reason: `its ${CHECKOUT_FILE} cannot be read: ${e.message}` };
591
+ }
592
+ const line = text.endsWith("\n") ? text.slice(0, -1) : text;
593
+ if (line.includes("\n") || !isAbsolute(line)) return none(`${CHECKOUT_FILE} holds no single absolute path`);
594
+ const suffix = basename(key).slice(-8);
595
+ if (!createHash("sha256").update(line).digest("hex").startsWith(suffix)) return none(`${line} does not hash to the key's suffix ${suffix}`);
596
+ return { checkout: line };
597
+ }
598
+
599
+ // Whether anything exists at `p` (lstat): true, false, or the error that
600
+ // leaves it unknown.
601
+ function existsAt(p) {
602
+ try {
603
+ lstatSync(p);
604
+ return true;
605
+ } catch (e) {
606
+ if (e.code === "ENOENT" || e.code === "ENOTDIR") return false;
607
+ return e;
608
+ }
609
+ }
610
+
611
+ // One sibling key's verdict, `{remove, reason, idle}`. `idle` is whether
612
+ // nothing under the key was found modified within the retention, searched for
613
+ // every key. Removed only when its checkout file is valid, nothing exists at
614
+ // the checkout it names, the directory that held that checkout does exist,
615
+ // nothing under the key is fresh and every part of it could be read. A key
616
+ // whose checkout still exists is its own phase 0's to reclaim; one whose
617
+ // checkout's parent is gone too may sit on an unplugged drive.
560
618
  function judgeSibling(path, cutoff) {
561
619
  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" };
620
+ const idle = freshUnder(path, cutoff, unreadable) === null;
621
+ const keep = (reason) => ({ remove: false, reason, idle });
622
+ const found = checkoutOf(path);
623
+ if (found.reason !== undefined) return keep(found.reason);
624
+ const { checkout } = found;
625
+ const at = existsAt(checkout);
626
+ if (at instanceof Error) return keep(`whether its checkout ${checkout} exists cannot be told: ${at.message}`);
627
+ if (at) return keep(`its checkout ${checkout} still exists, so its own phase 0 reclaims it`);
628
+ const held = dirname(checkout);
629
+ const up = existsAt(held);
630
+ if (up instanceof Error) return keep(`whether ${held}, the directory that held its checkout ${checkout}, exists cannot be told: ${up.message}`);
631
+ if (!up) return keep(`neither its checkout ${checkout} nor ${held}, the directory that held it, exists`);
632
+ if (!idle) return keep("sibling key modified within 7 days");
633
+ if (unreadable.length > 0) return keep(`sibling key could not be read whole (${unreadable[0]})`);
634
+ return { remove: true, reason: `its checkout ${checkout} is gone and nothing under it changed in 7 days`, idle: true };
635
+ }
636
+
637
+ // The live key's own `checkout-path`, written when it is missing or says
638
+ // anything but this workspace's canonical path: a temp file in the key,
639
+ // renamed over it. A failure is returned as a failed[] entry, null otherwise.
640
+ function writeCheckout(root) {
641
+ const file = join(root, CHECKOUT_FILE);
642
+ let checkout;
643
+ try {
644
+ checkout = dirname(fleetFile(null, { canonicalise: true }));
645
+ } catch (e) {
646
+ return { path: file, error: e.message };
647
+ }
648
+ if (checkoutOf(root).checkout === checkout) return null;
649
+ const tmp = join(root, `.${CHECKOUT_FILE}.${process.pid}.tmp`);
650
+ try {
651
+ writeFileSync(tmp, `${checkout}\n`);
652
+ renameSync(tmp, file);
653
+ } catch (e) {
654
+ try {
655
+ rmSync(tmp, { force: true });
656
+ } catch {
657
+ // left for the root sweep to age out
658
+ }
659
+ return { path: file, error: e.message };
660
+ }
661
+ return null;
565
662
  }
566
663
 
567
664
  function main() {
@@ -620,6 +717,10 @@ function main() {
620
717
  failed.push({ path: parent, error: e.message });
621
718
  }
622
719
  } else if (siblings) {
720
+ if (apply) {
721
+ const wrote = writeCheckout(root);
722
+ if (wrote !== null) failed.push(wrote);
723
+ }
623
724
  try {
624
725
  const judged = judgeSiblings(root, now - RETENTION_MS);
625
726
  remove = judged.remove;
@@ -653,11 +754,12 @@ function main() {
653
754
  let error;
654
755
  try {
655
756
  // 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.
757
+ // or bring its checkout back while an earlier key is still being removed:
758
+ // its whole verdict is taken again here, so a key no longer removable is
759
+ // kept.
658
760
  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 });
761
+ if (again !== null && !again.remove) {
762
+ kept.push({ path: entry.path, reason: again.reason, idle: again.idle });
661
763
  continue;
662
764
  }
663
765
  error = removeEntry(entry.path);
@@ -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