faberun 0.3.0

package/src/run/disk-gc.mjs

@@ -0,0 +1,251 @@
+/**
+ * Garbage collection for `.runs/` under disk pressure.
+ *
+ * A finished run's directory (contract, node snapshots, invocation logs) is
+ * disposable once nothing can ever read it again: every node is terminal, no
+ * controller holds it, and it is not the run currently writing. Reclaiming it
+ * is the only thing that can turn an ENOSPC mid-run into something a resume
+ * can recover from, since the disk will not free itself.
+ *
+ * Selection is a pure function over already-gathered facts (`describeRuns`
+ * reads the disk; `selectGarbageCollectableRuns` does not) so the eligibility
+ * rules are testable without creating a single file. Removal is a separate,
+ * impure step that stops as soon as free space clears the threshold — it
+ * never removes more than it has to — and it never removes `.runs/campaigns/`
+ * or `.runs/archive/`, the durable handoff and any future archive, no matter
+ * what a caller passes in.
+ */
+import { readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { TERMINAL } from "../engine/prompts.mjs";
+import { lockStale, readLock } from "./lock.mjs";
+
+import { checkDisk, minFreeDiskBytes } from "../host/preflight.mjs";
+import { appendJsonl, writeTextAtomic } from "./store.mjs";
+import { errorCode } from "../util.mjs";
+import { campaignsDir } from "../campaign/layout.mjs";
+
+/** @typedef {{path: string, startedAt: string|null, hasActiveController: boolean, allNodesTerminal: boolean}} RunDescriptor */
+
+/** Names under `.runs/` a run directory can never be, in any circumstance. */
+const RESERVED_RUN_DIR_NAMES = new Set(["campaigns", "archive"]);
+
+/**
+ * Gather the facts GC needs about every candidate under `runsDir`, straight
+ * off disk. A directory this cannot positively identify as a run (no
+ * readable `run.json`) is never described at all — `selectGarbageCollectableRuns`
+ * only ever sees directories this function is sure are runs.
+ *
+ * @param {string} runsDir
+ * @returns {RunDescriptor[]}
+ */
+export function describeRuns(runsDir) {
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(runsDir);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return [];
+    throw error;
+  }
+  const reservedPaths = new Set([campaignsDir(runsDir), join(runsDir, "archive")].map((path) => resolve(path)));
+  /** @type {RunDescriptor[]} */
+  const descriptors = [];
+  for (const name of names) {
+    if (RESERVED_RUN_DIR_NAMES.has(name)) continue;
+    const path = join(runsDir, name);
+    if (reservedPaths.has(resolve(path))) continue;
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+    /** @type {string|null} */
+    let startedAt = null;
+    try {
+      const metadata = JSON.parse(readFileSync(join(path, "run.json"), "utf8"));
+      startedAt = typeof metadata.startedAt === "string" ? metadata.startedAt : null;
+    } catch {
+      // Not a recognizable run directory (missing or unreadable run.json) —
+      // never described, so it can never be selected.
+      continue;
+    }
+    const lock = readLock(path);
+    descriptors.push({
+      path,
+      startedAt,
+      hasActiveController: lock !== null && !lockStale(lock),
+      allNodesTerminal: allNodeStatesTerminal(path),
+    });
+  }
+  return descriptors;
+}
+
+/**
+ * @param {string} runDir
+ * @returns {boolean}
+ */
+function allNodeStatesTerminal(runDir) {
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(join(runDir, "nodes")).filter((name) => name.endsWith(".json"));
+  } catch {
+    return false;
+  }
+  if (names.length === 0) return false;
+  for (const name of names) {
+    try {
+      const state = JSON.parse(readFileSync(join(runDir, "nodes", name), "utf8"));
+      if (!TERMINAL.has(state.status)) return false;
+    } catch {
+      // An unreadable or corrupt node snapshot is never provably terminal.
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Pure selection: every rule here is checked against already-gathered facts,
+ * never the filesystem, so this is testable with hand-built descriptors and
+ * no run directory ever created. Eligible runs are returned oldest first —
+ * `run.json`'s own `startedAt` is the only ordering signal, so a run whose
+ * `startedAt` this could not read is never eligible; there is nothing safe to
+ * compare it against.
+ *
+ * @param {RunDescriptor[]} descriptors
+ * @param {{currentRunDir?: string|null}} [options]
+ * @returns {string[]} run directories eligible for GC, oldest to newest
+ */
+export function selectGarbageCollectableRuns(descriptors, options = {}) {
+  const currentRunDir = options.currentRunDir ? resolve(options.currentRunDir) : null;
+  return descriptors
+    .filter((run) => !RESERVED_RUN_DIR_NAMES.has(basename(run.path)))
+    .filter((run) => typeof run.startedAt === "string")
+    .filter((run) => run.allNodesTerminal)
+    .filter((run) => !run.hasActiveController)
+    .filter((run) => resolve(run.path) !== currentRunDir)
+    .sort((a, b) => Date.parse(/** @type {string} */ (a.startedAt)) - Date.parse(/** @type {string} */ (b.startedAt)))
+    .map((run) => run.path);
+}
+
+/**
+ * Remove eligible run directories, oldest first, stopping the instant free
+ * space clears the threshold — never more than the minimum necessary. Every
+ * removal is appended to `<runsDir>/gc.jsonl` with its path and reason before
+ * the next candidate is even considered, so a removal is never silent.
+ *
+ * @param {string} runsDir
+ * @param {{currentRunDir?: string|null, minFreeBytes?: number, probePath?: string, reason?: string, isAboveThreshold?: () => boolean}} [options]
+ * @returns {{removed: string[]}}
+ */
+export function runGarbageCollection(runsDir, options = {}) {
+  const minFreeBytes = options.minFreeBytes ?? minFreeDiskBytes(process.env);
+  const probePath = options.probePath ?? runsDir;
+  const reason = options.reason ?? "enospc";
+  // A real statfs threshold check by default, unless a case deterministically
+  // simulates disk pressure (see `simulatedDiskPressureOverride`) — the same
+  // threshold `checkDisk` already reuses, just paired with a way to prove the
+  // removal loop without waiting on real free space to move. Tests may also
+  // substitute their own stub directly instead of either.
+  const isAboveThreshold = options.isAboveThreshold
+    ?? (() => simulatedDiskPressureOverride() ?? checkDisk(probePath, minFreeBytes).ok);
+  /** @type {string[]} */
+  const removed = [];
+  if (isAboveThreshold()) return { removed };
+  const descriptors = describeRuns(runsDir);
+  const candidates = selectGarbageCollectableRuns(descriptors, { currentRunDir: options.currentRunDir });
+  for (const runDir of candidates) {
+    if (isAboveThreshold()) break;
+    rmSync(runDir, { recursive: true, force: true });
+    removed.push(runDir);
+    appendJsonl(join(runsDir, "gc.jsonl"), { at: new Date().toISOString(), path: runDir, reason });
+  }
+  return { removed };
+}
+
+/** Error code a run stops with when GC could not recover from disk pressure. */
+export const DISK_PRESSURE_UNRECOVERABLE = "disk_pressure_unrecoverable";
+
+/**
+ * Write one run-directory text file, running GC exactly once and retrying
+ * exactly once if the first write fails with ENOSPC. A second ENOSPC is never
+ * retried again and never swallowed: it becomes a distinct, named error so
+ * the run stops visibly instead of failing on whatever generic thing ENOSPC
+ * happened to break next.
+ *
+ * @param {string} runDir
+ * @param {string} path
+ * @param {string} text
+ */
+export function writeRunTextWithDiskPressureRetry(runDir, path, text) {
+  try {
+    simulateEnospcForTest(path);
+    writeTextAtomic(path, text);
+    return;
+  } catch (error) {
+    if (errorCode(error) !== "ENOSPC") throw error;
+  }
+  runGarbageCollection(dirname(runDir), { currentRunDir: runDir });
+  try {
+    simulateEnospcForTest(path);
+    writeTextAtomic(path, text);
+  } catch (error) {
+    if (errorCode(error) !== "ENOSPC") throw error;
+    throw Object.assign(
+      new Error(`disk pressure persists after garbage collection while writing ${path}`),
+      { code: DISK_PRESSURE_UNRECOVERABLE },
+    );
+  }
+}
+
+/**
+ * Deterministic ENOSPC injection for tests and evals, never a real full
+ * disk. Inert unless `FABERUN_SIMULATE_ENOSPC_MATCH` names a substring
+ * of `path` and `FABERUN_SIMULATE_ENOSPC_COUNT` holds a positive
+ * integer; each simulated failure decrements that count, so a case sets it to
+ * `1` to prove GC recovers the write and `2` to prove a second ENOSPC in a
+ * row is never retried again.
+ *
+ * @param {string} path
+ */
+function simulateEnospcForTest(path) {
+  const match = process.env.FABERUN_SIMULATE_ENOSPC_MATCH;
+  if (!match || !path.includes(match)) return;
+  const remaining = Number(process.env.FABERUN_SIMULATE_ENOSPC_COUNT ?? "0");
+  if (!Number.isInteger(remaining) || remaining <= 0) return;
+  process.env.FABERUN_SIMULATE_ENOSPC_COUNT = String(remaining - 1);
+  throw Object.assign(
+    new Error(`ENOSPC: simulated no space left on device, write '${path}'`),
+    { code: "ENOSPC", errno: -28, syscall: "write", path },
+  );
+}
+
+/**
+ * Deterministic stand-in for "free space is still below the threshold",
+ * paired with `simulateEnospcForTest` so a case can prove the removal loop
+ * itself — not just the write retry — without waiting on real free space to
+ * move. Inert unless `FABERUN_SIMULATE_GC_ROUNDS` holds a non-negative
+ * integer; never consulted by `environmentPreflight`'s own disk check, which
+ * always reads real free space.
+ *
+ * The count is calls, not removals: `runGarbageCollection` calls this once
+ * before considering any candidate, then once more before each one it
+ * removes, so a run with `n` eligible candidates needs `n + 1` to remove all
+ * of them, or fewer to stop early after that many candidates.
+ *
+ * @returns {boolean|null} `false`/`true` to override the real check, or
+ * `null` when no simulation is configured and the real check should decide
+ */
+function simulatedDiskPressureOverride() {
+  const raw = process.env.FABERUN_SIMULATE_GC_ROUNDS;
+  if (raw === undefined) return null;
+  const remaining = Number(raw);
+  if (!Number.isInteger(remaining) || remaining < 0) return null;
+  if (remaining <= 0) return true;
+  process.env.FABERUN_SIMULATE_GC_ROUNDS = String(remaining - 1);
+  return false;
+}

package/src/run/lock.mjs

@@ -0,0 +1,329 @@
+/**
+ * One controller per run, held by an atomic lock file (TECH-SPEC lean, rule 5).
+ *
+ * `controller.lock` records the holder's pid, its process start token, and
+ * when it started. There is no expiry and nothing to renew: a lock stays
+ * valid for as long as its holder is alive, however long that takes, and a
+ * contender treats it as stale only once it can prove the holder dead — the
+ * pid is gone, or its start token no longer matches (the pid was recycled).
+ * That is a strictly stronger claim than a lease's TTL, so there is no
+ * healthy-but-expired window and nothing to fence against: at most one
+ * process can ever hold a live pid, so at most one takeover can ever observe
+ * a captured lock as stale.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { fsyncDirectory } from "./store.mjs";
+import { errorCode } from "../util.mjs";
+
+const LOCK_FILE = "controller.lock";
+const TAKEOVER_ATTEMPTS = 20;
+
+export class LockBusyError extends Error {
+  /** @param {string} message @param {unknown} lock */
+  constructor(message, lock = null) {
+    super(message);
+    this.name = "LockBusyError";
+    this.code = "lock_busy";
+    this.lock = lock;
+  }
+}
+
+export class LockLostError extends Error {
+  constructor(message = "controller lock was lost") {
+    super(message);
+    this.name = "LockLostError";
+    this.code = "lock_lost";
+  }
+}
+
+/** @typedef {{schemaVersion: number, pid: number, processStartToken: string|null, startedAt: string, hostname: string, invalid?: never}} LockRecord */
+/** @typedef {LockRecord|null|{invalid: true}} ReadLockResult */
+/** @typedef {{pid?: number, processStartToken?: string|null}} LockOptions */
+
+/** @param {string} runDir @returns {string} */
+export function lockPath(runDir) {
+  return join(runDir, LOCK_FILE);
+}
+
+/**
+ * The process start time distinguishes a live pid from a recycled one. On
+ * Linux, field 22 of /proc/<pid>/stat. On darwin, there is no /proc, so the
+ * fingerprint comes from the OS process table instead: `ps -o lstart=`
+ * reports the same live process's own start time on every call and a
+ * different one for whatever process next reuses that pid, without a
+ * compiled addon or elevated privileges. Every other platform has no cheap
+ * equivalent, so the pid probe alone decides there.
+ * @param {number|null} pid @returns {string|null}
+ */
+export function processStartToken(pid) {
+  if (!pid) return null;
+  if (process.platform === "linux") {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
+      return stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19] ?? null;
+    } catch {
+      return null;
+    }
+  }
+  if (process.platform === "darwin") {
+    const started = psStartTime(pid);
+    if (started.length > 0) return started;
+    // Immediately after spawn, `ps` can race the kernel's process-table insert
+    // and report nothing for a pid that is already alive. One short retry
+    // closes that window; a still-empty answer stays null.
+    if (!pidAlive(pid)) return null;
+    sleepMs(20);
+    const retried = psStartTime(pid);
+    return retried.length > 0 ? retried : null;
+  }
+  return null;
+}
+
+/**
+ * `ps -o lstart=` for one pid, or the empty string when the probe finds
+ * nothing. It is the darwin half of the start-token fingerprint.
+ *
+ * @param {number} pid
+ * @returns {string}
+ */
+function psStartTime(pid) {
+  try {
+    return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Block without a timer so the synchronous darwin retry above can wait out the
+ * spawn race. The duration is tiny and bounded, so blocking the loop is safe.
+ *
+ * @param {number} milliseconds
+ */
+function sleepMs(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+/** @param {number|null|undefined} pid @returns {boolean} */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || /** @type {number} */ (pid) <= 0) return false;
+  try {
+    process.kill(/** @type {number} */ (pid), 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) === "EPERM";
+  }
+}
+
+/** @param {string} runDir @returns {ReadLockResult} */
+export function readLock(runDir) {
+  try {
+    return /** @type {LockRecord} */ (JSON.parse(readFileSync(lockPath(runDir), "utf8")));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return null;
+    if (error instanceof SyntaxError) return { invalid: true };
+    throw error;
+  }
+}
+
+/**
+ * A lock is stale only once its holder is proven dead. A live holder keeps
+ * the lock no matter its age — there is no expiry to race.
+ * @param {ReadLockResult} lock @returns {boolean}
+ */
+export function lockStale(lock) {
+  if (!lock || /** @type {{invalid?: true}} */ (lock).invalid) return true;
+  const record = /** @type {LockRecord} */ (lock);
+  if (!pidAlive(record.pid)) return true;
+  return Boolean(record.processStartToken) && processStartToken(record.pid) !== record.processStartToken;
+}
+
+/**
+ * Acquire the run's controller lock, taking over a stale one. Contention on a
+ * live lock fails immediately: there is nothing to wait for, since a live
+ * holder does not become dead within this call.
+ * @param {string} runDir @param {LockOptions} [options] @returns {LockRecord & {current: LockRecord, assert: () => void, release: () => void, released: boolean}}
+ */
+export function acquire(runDir, options = {}) {
+  mkdirSync(runDir, { recursive: true });
+  const path = lockPath(runDir);
+  const pid = options.pid ?? process.pid;
+  /** @type {LockRecord} */
+  const record = {
+    schemaVersion: 1,
+    pid,
+    processStartToken: options.processStartToken !== undefined ? options.processStartToken : processStartToken(pid),
+    startedAt: new Date().toISOString(),
+    hostname: hostname(),
+  };
+  for (let attempt = 0; attempt < TAKEOVER_ATTEMPTS; attempt += 1) {
+    try {
+      writeExclusive(path, record, runDir);
+      return createHandle(runDir, record);
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+    }
+    const occupant = readLock(runDir);
+    if (!lockStale(occupant)) {
+      throw new LockBusyError(`run controller lock is held by pid ${/** @type {LockRecord} */ (occupant)?.pid}`, occupant);
+    }
+    // Capture is one atomic rename: there is no gap in which a live successor
+    // could install under the name and be destroyed by a decision made about
+    // its dead predecessor. A capture that turns out to still be live — the
+    // successor won the race between our read and our rename — is handed
+    // straight back, never discarded.
+    const aside = captureEntry(path);
+    if (aside === null) continue;
+    const captured = readCapturedLock(aside);
+    if (!lockStale(captured)) {
+      try {
+        linkSync(aside, path);
+      } catch (error) {
+        if (errorCode(error) !== "EEXIST") throw error;
+      }
+      discardEntry(aside);
+      fsyncDirectory(runDir);
+      continue;
+    }
+    discardEntry(aside);
+    fsyncDirectory(runDir);
+  }
+  throw new LockBusyError(`contended controller lock takeover for ${runDir} did not settle`, readLock(runDir));
+}
+
+/** @param {string} path @param {LockRecord} record @param {string} runDir */
+function writeExclusive(path, record, runDir) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, "wx", 0o600);
+  try {
+    writeSync(fd, `${JSON.stringify(record, null, 2)}\n`, 0, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    linkSync(temporary, path);
+    fsyncDirectory(runDir);
+  } finally {
+    discardEntry(temporary);
+  }
+}
+
+/** @param {string} path @returns {string|null} */
+function captureEntry(path) {
+  const aside = `${path}.captured.${process.pid}.${randomUUID()}`;
+  try {
+    renameSync(path, aside);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+  return aside;
+}
+
+/** @param {string} path @returns {ReadLockResult} */
+function readCapturedLock(path) {
+  try {
+    return /** @type {LockRecord} */ (JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return { invalid: true };
+  }
+}
+
+/** @param {string} path */
+function discardEntry(path) {
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/** @param {string} runDir @param {LockRecord} record */
+function createHandle(runDir, record) {
+  const path = lockPath(runDir);
+  let released = false;
+  /** @returns {boolean} */
+  const held = () => {
+    const actual = readLock(runDir);
+    return Boolean(actual) && !/** @type {{invalid?: true}} */ (actual).invalid
+      && /** @type {LockRecord} */ (actual).pid === record.pid
+      && /** @type {LockRecord} */ (actual).startedAt === record.startedAt;
+  };
+  return {
+    ...record,
+    get current() { return record; },
+    assert() {
+      if (released || !held()) throw new LockLostError();
+    },
+    release() {
+      if (released) return;
+      if (held()) {
+        discardEntry(path);
+        fsyncDirectory(runDir);
+      }
+      released = true;
+    },
+    get released() { return released; },
+  };
+}
+
+/**
+ * Detached-bootstrap identity (TECH-SPEC section 4.3).
+ *
+ * A `run --detach` parent hands its child a nonce and later needs proof that
+ * the bootstrap record and the controller lock it finds really belong to the
+ * pid it spawned, not to some other process that reused that pid in the
+ * meantime. Matching pid and nonce alone is not that proof: a nonce is
+ * generated by the parent and never reused, but a recycled pid could
+ * coincidentally match while belonging to an unrelated process if the
+ * parent's own child died and something else took its pid before the parent
+ * finished checking. The process start token is what rules that out.
+ */
+
+/**
+ * @param {string|null|undefined} actual
+ * @param {string|null|undefined} expected
+ * @returns {boolean}
+ */
+export function sameProcessStartToken(actual, expected) {
+  return actual === expected;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function validBootstrapNonce(value) {
+  return typeof value === "string" && /^[A-Za-z0-9-]{16,64}$/u.test(value);
+}
+
+/**
+ * @param {{pid?: number, nonce?: string, processStartToken?: string|null}} record
+ * @param {number} pid
+ * @param {string} nonce
+ * @param {string|null} expectedProcessStartToken
+ * @returns {boolean}
+ */
+export function bootstrapMatchesChild(record, pid, nonce, expectedProcessStartToken) {
+  return record?.pid === pid && record?.nonce === nonce && validBootstrapNonce(record.nonce) && sameProcessStartToken(record.processStartToken, expectedProcessStartToken);
+}
+
+/**
+ * @param {{pid?: number, nonce?: string, processStartToken?: string|null}} record
+ * @param {number} pid
+ * @param {string} nonce
+ * @param {string|null} expectedProcessStartToken
+ * @returns {boolean}
+ */
+export function bootstrapFailureMatchesChild(record, pid, nonce, expectedProcessStartToken) {
+  return record?.pid === pid && record?.nonce === nonce && validBootstrapNonce(record.nonce) && (
+    expectedProcessStartToken === null
+      ? record.processStartToken === null || typeof record.processStartToken === "string"
+      : record.processStartToken === expectedProcessStartToken
+  );
+}

package/src/run/node-store.mjs

@@ -0,0 +1,62 @@
+/**
+ * The one place that knows where a node's snapshot lives on disk
+ * (`<runDir>/nodes/<nodeId>.json`). Everything that persists or reads a node
+ * snapshot goes through here so the path itself has a single owner.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { errorCode } from "../util.mjs";
+import { writeRunTextWithDiskPressureRetry } from "./disk-gc.mjs";
+import { validateNodeSnapshot } from "../contract/snapshot.mjs";
+
+/** @typedef {ReturnType<typeof import("./lock.mjs").acquire>} LockHandle */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+
+const NODES_DIR_NAME = "nodes";
+
+/**
+ * @param {string} runDir
+ * @param {string} nodeId
+ * @returns {string}
+ */
+export function nodeSnapshotPath(runDir, nodeId) {
+  return join(runDir, NODES_DIR_NAME, `${nodeId}.json`);
+}
+
+/**
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {LockHandle|null} [lock]
+ */
+export function writeNodeSnapshot(runDir, state, lock = null) {
+  lock?.assert();
+  validateNodeSnapshot(state);
+  const serialized = JSON.stringify(state);
+  if (Buffer.byteLength(serialized, "utf8") > 128 * 1024) throw new Error("node snapshot exceeds 131072 bytes");
+  writeRunTextWithDiskPressureRetry(runDir, nodeSnapshotPath(runDir, state.id), `${serialized}\n`);
+}
+
+/**
+ * @param {string} runDir
+ * @param {string} nodeId
+ * @returns {Record<string, unknown>}
+ */
+export function readNodeSnapshot(runDir, nodeId) {
+  return JSON.parse(readFileSync(nodeSnapshotPath(runDir, nodeId), "utf8"));
+}
+
+/**
+ * File names (`<nodeId>.json`) of every node snapshot persisted in this run.
+ * A run directory with no `nodes/` yet reads as empty, not ENOENT.
+ *
+ * @param {string} runDir
+ * @returns {string[]}
+ */
+export function listNodeSnapshots(runDir) {
+  try {
+    return readdirSync(join(runDir, NODES_DIR_NAME)).filter((name) => name.endsWith(".json"));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return [];
+    throw error;
+  }
+}