bareloop 0.27.0 → 0.29.0

package/src/replayio.js

@@ -0,0 +1,159 @@
+// PANEL-BUILD.md P0 — the spine/gate-audit READ side. Lifted out of
+// `scripts/run-replay.mjs` (verbatim logic, moved so it is callable
+// in-process rather than only as a script) plus one more reader
+// (`readHistoryLog`) for `bareloop history`'s bundle-registry file. This
+// module is the IO layer ONLY: it resolves paths, parses JSONL tolerantly
+// (a malformed line is counted and skipped, never thrown on), and hands
+// parsed records to `src/replay.js`'s pure `replayRun`/`formatReplay`/
+// `summarizeForAllLine`/`formatAllLines` — it never recomputes anything
+// those already derive (PANEL-BUILD.md P0: "feed replay.js, never
+// duplicate it").
+//
+// NAME-AGNOSTIC spine detection (coordinator fix, 2026-08-25, carried over
+// verbatim from the script this replaces): the patient corpus does not agree
+// on a filename convention — `u-<id>.jsonl` (run-u), `battery-A1-<id>.jsonl`
+// / `l2accept-L1-<id>.jsonl` (batteries), `layer-r-probe-P1-<id>.jsonl`,
+// `types-screen-C-<id>.jsonl`, `reuse-<id>.jsonl` (first record
+// `reuse-start`), `job2-<id>.jsonl` all measured across the real archive. A
+// spine is therefore identified by CONTENT, never by a naming pattern: any
+// `*.jsonl` that is not a gate-audit/lag sidecar BY NAME
+// (`*-gate-audit.jsonl`, `*.lag.jsonl` — the one convention that IS
+// universal, because every spine resolves its own audit sibling this same
+// way) and whose records include at least one `job-start` or `run-start` is
+// a spine. A `.jsonl` that matches neither test is reported as
+// `<name> not-a-spine` — never silently dropped, never silently misread as
+// an empty/unknown run.
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { replayRun, summarizeForAllLine } from './replay.js';
+
+/**
+ * Parse one JSONL file into records, tolerant of a malformed line (counted
+ * in `skipped`, never thrown on). Mirrors `scripts/behaviour-readout.mjs`'s
+ * own parse.
+ * @param {string} file
+ * @returns {{records: any[], skipped: number}}
+ */
+export function parseJsonl(file) {
+  const raw = readFileSync(file, 'utf8');
+  const lines = raw.split('\n').filter((l) => l.trim() !== '');
+  /** @type {any[]} */
+  const records = [];
+  let skipped = 0;
+  for (const line of lines) {
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { records, skipped };
+}
+
+/**
+ * `true` when `name` (a bare filename, not a path) is a gate-audit or lag
+ * sidecar by NAME convention — the one filename rule that holds across the
+ * whole archive.
+ * @param {string} name
+ */
+export function isSidecarByName(name) {
+  return name.endsWith('-gate-audit.jsonl') || name.endsWith('.lag.jsonl');
+}
+
+/**
+ * `true` when `records` carries at least one `job-start` (present on every
+ * real spine checked, first record or not — a reuse/battery run nests one or
+ * more ordinary `runJob` calls inside it) or `run-start` (ralph's own inner
+ * loop marker, present on most but not all real spines).
+ * @param {any[]} records
+ */
+export function looksLikeSpine(records) {
+  return records.some((r) => r && (r.type === 'job-start' || r.type === 'run-start'));
+}
+
+/**
+ * `<name>.jsonl` → `<name>-gate-audit.jsonl` in the same directory, and the
+ * bare run id for display — the run id lives only in the filename (no spine
+ * record carries it; see `src/replay.js`'s header). A leading `u-` (the
+ * run-u convention) is stripped; every other prefix (`battery-A1-`,
+ * `reuse-`, …) is kept verbatim, since it is the only thing distinguishing
+ * that run from its siblings in the same directory.
+ * @param {string} spinePath
+ * @returns {{runId: string, auditPath: string|null}}
+ */
+export function resolveSiblings(spinePath) {
+  const dir = dirname(spinePath);
+  const base = basename(spinePath);
+  const stem = base.replace(/\.jsonl$/, '');
+  const runId = stem.startsWith('u-') ? stem.slice(2) : stem;
+  const auditPath = join(dir, `${stem}-gate-audit.jsonl`);
+  return { runId, auditPath: existsSync(auditPath) ? auditPath : null };
+}
+
+/**
+ * Read one run's spine (+ its gate-audit sidecar, when present) off disk and
+ * hand both to {@link replayRun}. Read-only, $0, mints no verdict.
+ * @param {string} spinePath absolute or cwd-relative path to a `.jsonl` spine
+ * @param {{preParsedSpine?: {records: any[], skipped: number}, skipAudit?: boolean}} [opts]
+ *   `preParsedSpine`: avoids a second parse of the same file when the caller
+ *   ({@link listSpines}) already read it once to run {@link looksLikeSpine}.
+ *   `skipAudit` (PR #23 review item 5, 2026-08-26, carried over): a
+ *   directory listing never opens the gate-audit sidecar at all —
+ *   `summarizeForAllLine` reads none of the fields that sidecar feeds inside
+ *   `replayRun`, so reading every run's sidecar in a directory listing was
+ *   pure unused I/O, multiplied by every spine found.
+ * @returns {ReturnType<typeof replayRun>}
+ */
+export function replayOne(spinePath, opts = {}) {
+  const { preParsedSpine, skipAudit = false } = opts;
+  const { runId, auditPath } = resolveSiblings(spinePath);
+  const spine = preParsedSpine ?? parseJsonl(spinePath);
+  const audit = (!skipAudit && auditPath) ? parseJsonl(auditPath) : { records: [], skipped: 0 };
+  // `auditAvailable`: true only when a sidecar was actually FOUND AND READ.
+  // `skipAudit` (a deliberate cheap directory listing) and "no sidecar on
+  // disk" both mean this call never learned the real tool-call count, so
+  // both report unknown, never a coincidental 0 (doctrine: unknown reported
+  // as unknown, never rendered as zero — see `replayRun`'s own doc).
+  const auditAvailable = !skipAudit && auditPath !== null;
+  const summary = replayRun(spine.records, audit.records, { runId, auditAvailable });
+  summary.skipped += spine.skipped + audit.skipped;
+  return summary;
+}
+
+/**
+ * List every spine found directly in `dir` (not recursive — same as the
+ * script this replaces): one entry per `.jsonl` file that is not a sidecar
+ * by name, each either `{kind:'spine', row}` ({@link summarizeForAllLine}'s
+ * row) or `{kind:'not-a-spine', name}` when the file's content doesn't look
+ * like a spine. Feeds `formatAllLines` (`src/replay.js`) for the printed
+ * table — this function does no formatting of its own, only IO + detection.
+ * @param {string} dir
+ * @returns {Array<{kind: 'spine', row: ReturnType<typeof summarizeForAllLine>}|{kind: 'not-a-spine', name: string}>}
+ */
+export function listSpines(dir) {
+  const candidates = readdirSync(dir)
+    .filter((f) => f.endsWith('.jsonl') && !isSidecarByName(f))
+    .sort();
+  return candidates.map((f) => {
+    const path = join(dir, f);
+    const spine = parseJsonl(path);
+    if (!looksLikeSpine(spine.records)) return { kind: /** @type {const} */ ('not-a-spine'), name: f };
+    const summary = replayOne(path, { preParsedSpine: spine, skipAudit: true });
+    return { kind: /** @type {const} */ ('spine'), row: summarizeForAllLine(summary) };
+  });
+}
+
+/**
+ * Read a bundle's `history.jsonl` (one `bareloop run` row per line, written
+ * by `appendHistory` in `src/bundle.js`) — the single reader for this file,
+ * replacing `src/cli.js`'s own hand-rolled `readFileSync`/split. Tolerant of
+ * a malformed line the same way {@link parseJsonl} is (counted in
+ * `skipped`, never thrown on).
+ * @param {string} file absolute path to `history.jsonl`
+ * @returns {{rows: any[], skipped: number}}
+ */
+export function readHistoryLog(file) {
+  const { records, skipped } = parseJsonl(file);
+  return { rows: records, skipped };
+}

package/src/reuse.js

@@ -805,7 +805,7 @@ function readGradeSeed(seen) {
  * abandoned attempt twice in a chain of resumes.
  *
  * @param {any[]} events the dead spine's events, parsed, in file order
- * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: string[]}} [opts]
+ * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: readonly string[]}} [opts]
  *   `deathAt`: when the process is judged to have died (the watchdog's kill record,
  *   which is later and better evidence than the last event). Defaults to the last
  *   event's own timestamp — the last sign of life there is.

package/src/run.js

@@ -204,7 +204,7 @@ async function primitiveSmoke(workdir) {
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
  *        binding.)
- * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ * @param {{decision: string, text?: string|null}|null} [opts.humanRuling] N4 — the SIGNER's
  *   answer at a hitl pause (accept | rerun <text> | pause), carried by the leg that
  *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
  *   ordinary run; never authored and never defaulted (a defaulted answer to "is this

package/src/runlist.js

@@ -0,0 +1,281 @@
+// PANEL-BUILD.md P1 (2026-09-24 rulings) — "one home for runs": a single LIST
+// of every run bareloop has started, never a move of the runs themselves.
+// Patient copies stay exactly where they already live (`bareloop-patients/…`
+// for run-u, `<bundleDir>/runs/<runid>/` for `bareloop run`); jobs stay in
+// `jobs/` (moving them into the home is deferred to P3, hamr picked "A").
+// This module is the ONE place that list lives: `~/.config/bareloop/
+// runs.jsonl` — the same directory the keys file (PRD §7d) lives in, kept
+// separate from any repo tree (secrets/run metadata never enter the tree,
+// the spine, or a repo's own configs).
+//
+// One JSON object per line: `{ at, runid, job, spine, patient, via }`.
+// `spine`/`patient` are always ABSOLUTE paths (or `patient: null` when the
+// caller doesn't know one) — a relative path here would resolve differently
+// depending on who later reads the file. `via` says how the row was minted:
+// `'run-u'` (src/userrun.js, the person-path run), `'bundle'`
+// (src/cli.js:doRun, `bareloop run`), or `'backfill'` (`bareloop runs
+// backfill`, reconstructed from an archived spine already on disk).
+//
+// SECRETS: a row carries only paths/ids/names — never a key, a prompt, or any
+// value read out of the run's own tree. Nothing here reads a spine's payload
+// beyond `job`/`ts` on its `job-start` record.
+//
+// No new env var: grepped the tree for an existing HOME-override convention
+// before adding one (2026-09-24) — none exists (`src/tools.js`'s
+// `expandHome` calls `os.homedir()` directly, same as every other caller).
+// This module follows that precedent and adds an injectable `home` param for
+// tests instead, the same test-seam shape `deps.provider` already is
+// elsewhere in this codebase.
+
+import {
+  existsSync, mkdirSync, appendFileSync, chmodSync, readdirSync, statSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import {
+  join, dirname, basename, resolve,
+} from 'node:path';
+import { parseJsonl, isSidecarByName, looksLikeSpine, resolveSiblings } from './replayio.js';
+
+/**
+ * `~/.config/bareloop` (or the injected override) — the one home directory
+ * for both the keys file (PRD §7d, not this module's concern) and the run
+ * list.
+ * @param {string} [override] test seam; a caller in production never passes it
+ * @returns {string}
+ */
+export function runlistHome(override) {
+  return override ?? join(homedir(), '.config', 'bareloop');
+}
+
+/**
+ * `<home>/runs.jsonl`.
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function runlistPath(home) {
+  return join(runlistHome(home), 'runs.jsonl');
+}
+
+/**
+ * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill' }} RunRow
+ */
+
+/**
+ * Append one row to the run list, mkdir -p'ing the home directory first.
+ * IDEMPOTENT BY RUNID: a row already carrying `row.runid` is never
+ * duplicated (a resume, or a re-run of `backfill`, must not double-list one
+ * run) — the file is read once first to check.
+ *
+ * Perms: the home directory is created `0700` and the file kept `0600`
+ * (chmod'd after every append, in case it pre-existed with wider perms) —
+ * the same "outside any repo, keys-file-adjacent" posture PRD §7d states for
+ * `.env` in this same directory, even though this file carries no secret
+ * itself.
+ *
+ * THROWS on any IO failure (permission denied, disk full, …) — the caller
+ * (a live run) is required to catch this and continue the run rather than
+ * let a list-append failure abort paid work (hamr's rule: a panel list must
+ * never block real work). This function itself does not swallow, so a
+ * direct caller (e.g. `backfillRuns`, a $0 path) sees the real error.
+ * @param {RunRow} row
+ * @param {{ home?: string }} [opts]
+ * @returns {{ appended: boolean, reason?: 'duplicate-runid' }}
+ */
+export function appendRun(row, opts = {}) {
+  const home = runlistHome(opts.home);
+  const path = runlistPath(opts.home);
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  if (existsSync(path)) {
+    const { records } = parseJsonl(path);
+    if (records.some((r) => r && r.runid === row.runid)) {
+      return { appended: false, reason: 'duplicate-runid' };
+    }
+  }
+  appendFileSync(path, `${JSON.stringify(row)}\n`);
+  try { chmodSync(path, 0o600); } catch { /* best-effort perms; the append above already landed */ }
+  return { appended: true };
+}
+
+/**
+ * Tolerant reader — reuses {@link parseJsonl} (never a second hand-rolled
+ * parser). An absent file reads as an empty list, not an error: a fresh
+ * install has never run `appendRun` yet.
+ * @param {{ home?: string }} [opts]
+ * @returns {{ rows: RunRow[], skipped: number }}
+ */
+export function readRunList(opts = {}) {
+  const path = runlistPath(opts.home);
+  if (!existsSync(path)) return { rows: [], skipped: 0 };
+  const { records, skipped } = parseJsonl(path);
+  return { rows: records, skipped };
+}
+
+/**
+ * The runid a spine file names, for BOTH layouts this scan understands:
+ * the bundle layout (`.../runs/<runid>/spine.jsonl` — the runid lives in the
+ * directory name, since every bundle run is literally named `spine.jsonl`)
+ * and every other convention ({@link resolveSiblings}'s filename-based
+ * read, e.g. `u-<id>.jsonl`).
+ * @param {string} spinePath
+ * @returns {string}
+ */
+function runidForSpine(spinePath) {
+  const base = basename(spinePath);
+  const parent = dirname(spinePath);
+  if (base === 'spine.jsonl' && basename(dirname(parent)) === 'runs') {
+    return basename(parent);
+  }
+  return resolveSiblings(spinePath).runId;
+}
+
+// A backfill scan of a real patients directory can be arbitrarily deep
+// (person-path runs archive several levels down: `<dir>/<proj>/out/
+// source-<x>/<proj>-bareloop/u-<id>.jsonl`, 4 levels under the dir a person
+// actually points `backfill` at) — a non-recursive/immediate-subdir-only
+// scan silently misses every run nested past that first level (measured:
+// the newest real run in a 2026-09-09-capped panel was 12 days stale while
+// real runs existed through 2026-09-21). Tighten-only cap, named so a future
+// change to it is a deliberate, visible edit, never a silent number bump.
+export const MAX_BACKFILL_DEPTH = 6;
+
+/**
+ * Every `.jsonl` file under `dir`, recursively, that is not a sidecar by
+ * name — bounded to {@link MAX_BACKFILL_DEPTH} directory levels below `dir`
+ * itself (`dir` is depth 0). Never descends into `node_modules` or `.git`
+ * (a copied repo source or a bundle's own worktree can carry either, and
+ * neither ever holds a real archived spine worth scanning). Never follows a
+ * symlinked directory (a symlink is skipped outright — `Dirent.isDirectory`/
+ * `isFile` both read false for one, since `readdirSync` with `withFileTypes`
+ * types by `lstat`, not the link's target — so it silently falls out of
+ * both branches below rather than needing a separate check).
+ * @param {string} dir
+ * @param {number} [maxDepth]
+ * @returns {string[]}
+ */
+function jsonlFilesIn(dir, maxDepth = MAX_BACKFILL_DEPTH) {
+  /** @type {Set<string>} */
+  const found = new Set();
+  /** @param {string} d @param {number} depth */
+  function walk(d, depth) {
+    let entries;
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        if (depth < maxDepth) walk(join(d, entry.name), depth + 1);
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith('.jsonl') && !isSidecarByName(entry.name)) {
+        found.add(join(d, entry.name));
+      }
+    }
+  }
+  if (existsSync(dir)) walk(dir, 0);
+  return [...found].sort();
+}
+
+/**
+ * `bareloop runs backfill <dir>` — recursively scan `dir` (bounded to
+ * {@link MAX_BACKFILL_DEPTH} levels, never into `node_modules`/`.git`,
+ * never following a symlinked directory) for archived spine files — both
+ * the free-standing layout (e.g. `<dir>/<x>/u-<id>.jsonl`, at any depth) and
+ * the bundle layout (`<dir>/.../runs/<runid>/spine.jsonl`) — and add one row
+ * per spine whose RESOLVED ABSOLUTE PATH is not already in the list.
+ *
+ * F197: dedup is by spine path, never by `runidForSpine`'s own derived
+ * runid. A spine carrying no `runid` field falls back to a filename-derived
+ * id (e.g. `run` for a `run.jsonl` with no runid inside) — a SECOND such
+ * file elsewhere (same basename, different directory: not a rare shape,
+ * `bareloop-patients/quickstart-proof/run.jsonl` is a real example) is a
+ * DIFFERENT run, not a duplicate, and dedup-by-runid would have silently
+ * dropped it. When the derived runid collides with one already in the list
+ * (pre-existing or added earlier in this same pass), the row's OWN runid is
+ * disambiguated (`<base>~2`, `<base>~3`, …) so every row keeps a runid the
+ * panel's `/api/runs/:runid` lookup can resolve unambiguously — see
+ * {@link RUNID_RE} in `src/panel/server.js`, updated to allow `~`.
+ *
+ * IDEMPOTENT: running twice adds nothing the second time (the resolved-path
+ * set already contains every spine this pass would otherwise re-add). Never
+ * silent about what it found: every candidate `.jsonl` is bucketed into
+ * exactly one of added / already listed / skipped (not a spine, or
+ * unreadable).
+ * @param {string} dir
+ * @param {{ home?: string }} [opts]
+ * @returns {{ added: number, alreadyListed: number, skipped: number, addedRows: RunRow[] }}
+ */
+export function backfillRuns(dir, opts = {}) {
+  if (!existsSync(dir)) throw new Error(`backfillRuns: no such directory: ${dir}`);
+
+  const candidates = new Set(jsonlFilesIn(dir));
+
+  const { rows: existingRows } = readRunList(opts);
+  const knownPaths = new Set(existingRows.map((r) => (r && typeof r.spine === 'string' ? resolve(r.spine) : null)).filter(Boolean));
+  const knownRunids = new Set(existingRows.map((r) => r && r.runid).filter(Boolean));
+
+  let added = 0;
+  let alreadyListed = 0;
+  let skipped = 0;
+  /** @type {RunRow[]} */
+  const addedRows = [];
+
+  for (const spinePath of [...candidates].sort()) {
+    const resolvedPath = resolve(spinePath);
+    if (knownPaths.has(resolvedPath)) { alreadyListed += 1; continue; }
+    let parsed;
+    try {
+      parsed = parseJsonl(spinePath);
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    if (!looksLikeSpine(parsed.records)) { skipped += 1; continue; }
+    const baseRunid = runidForSpine(spinePath);
+    let runid = baseRunid;
+    if (knownRunids.has(runid)) {
+      let n = 2;
+      while (knownRunids.has(`${baseRunid}~${n}`)) n += 1;
+      runid = `${baseRunid}~${n}`;
+    }
+    const jobStart = parsed.records.find((r) => r && r.type === 'job-start') ?? null;
+    const job = typeof jobStart?.job === 'string' ? jobStart.job : '(unknown job)';
+    // `at`: the job-start record's own `ts` (stamped by src/spine.js's
+    // `makeSpine`) when present; else the earliest timestamped record on the
+    // spine; else the file's own mtime, honestly — never a fabricated "now".
+    const earliestTs = parsed.records.find((r) => typeof r?.ts === 'string')?.ts ?? null;
+    const at = typeof jobStart?.ts === 'string' ? jobStart.ts
+      : earliestTs ?? statSync(spinePath).mtime.toISOString();
+    // `patient`: no spine record carries the run's workdir (verified against
+    // src/run.js's own `job-start` emit, 2026-09-24) — reported honestly as
+    // `null` rather than guessed from directory layout, which does not hold
+    // across the archive's several naming conventions (see src/replayio.js's
+    // own file-header comment).
+    const row = {
+      at, runid, job, spine: resolvedPath, patient: null, via: /** @type {const} */ ('backfill'),
+    };
+    const result = appendRun(row, opts);
+    if (result.appended) {
+      added += 1; addedRows.push(row); knownPaths.add(resolvedPath); knownRunids.add(runid);
+    } else {
+      // only reachable if two candidates in the SAME pass resolve to the
+      // same path under different spellings, or an unexpected runid clash
+      // appendRun itself caught — either way, honestly counted, never lost.
+      alreadyListed += 1;
+    }
+  }
+
+  return { added, alreadyListed, skipped, addedRows };
+}
+
+/**
+ * One printable line per row for `bareloop runs` (no subcommand): `job
+ * (runid) · date · spine path`, with `file missing` appended when the row's
+ * `spine` no longer exists on disk (an archive moved/pruned since the row
+ * was written — never silently listed as if it were still there).
+ * @param {RunRow} row
+ * @returns {string}
+ */
+export function formatRunRow(row) {
+  const date = typeof row.at === 'string' ? row.at.slice(0, 10) : '(unknown date)';
+  const missing = existsSync(row.spine) ? '' : ' — file missing';
+  return `${row.job} (${row.runid}) · ${date} · ${row.spine}${missing}`;
+}

package/src/u-patient.js

@@ -0,0 +1,73 @@
+// THE COLD RESET, in ONE place.
+//
+// `run-u.mjs` has always owned this: a cold run starts at the frozen seed with the
+// `.litectx` store removed, because a run that inherits the previous run's edits — or
+// the previous run's isolate-verb memory (stash/remember persist in the store) — is
+// measuring the wrong thing. The reuse rung's OFF arm and every cold contrast depend
+// on it.
+//
+// It moved here the day a BATTERY driver needed to rehearse it (the read-shim Phase 2
+// battery's `--dry-run` has to prove the patient really does go cold between rows).
+// The alternative was a second spelling of `git reset --hard` in the battery, and two
+// spellings of "cold" is exactly how one driver's rows come to start from a different
+// tree than the other's — the blind-instrument class, at the patient.
+//
+// Nothing here decides anything and nothing here is arbiter territory: it is the
+// mechanical preparation of a tree, and both callers print what it did.
+import { execFileSync } from 'node:child_process';
+import {
+  rmSync, existsSync, renameSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Reset a patient to its frozen seed and drop its `.litectx` store.
+ *
+ * @param {string} wd absolute path to the patient's tree (a git repo with >=1 commit)
+ * @param {string} seed the frozen seed commit
+ * @returns {{ head: string, storeRemoved: boolean }} `head` is the short sha the tree
+ *   now stands at; `storeRemoved` says whether a store was actually there to remove
+ *   (so a caller can print the truth rather than a claim).
+ */
+export function coldReset(wd, seed) {
+  const git = (/** @type {string[]} */ a) => execFileSync('git', ['-C', wd, ...a], { encoding: 'utf8' }).trim();
+  git(['reset', '--hard', seed]);
+  git(['clean', '-fd']);
+  const store = join(wd, '.litectx');
+  const storeRemoved = existsSync(store);
+  rmSync(store, { recursive: true, force: true });
+  return { head: git(['rev-parse', '--short', 'HEAD']), storeRemoved };
+}
+
+/**
+ * F186 — the patient's own `.gitignore` denies `*.jsonl`, so `coldReset`'s
+ * `git clean -fd` (no `-x`) never removes a `gate-audit.jsonl` already
+ * sitting at the tree root — it can only be there from an EARLIER run
+ * against this same patient (an authoring scout, or a prior worker run)
+ * that never got archived out. Left in place, THIS run's own Gate (which
+ * writes to that same path) would append to it, and the end-of-run rename
+ * that claims the whole file as "this run's own audit" would silently
+ * carry every earlier run's rows too — a harness slicing a shared append-
+ * only log has to account for every writer inside its window.
+ *
+ * Call this AFTER `coldReset` and BEFORE this run's own Gate ever opens: at
+ * that point a `gate-audit.jsonl` sitting in the tree is provably not this
+ * run's, because coldReset just proved the tree is unable to have produced
+ * one since the seed reset. NOT for a resume — a halted run's own gate
+ * audit already in the tree it resumes into is that SAME run's prior leg,
+ * not a stranger's; callers on the resume path must not call this.
+ *
+ * @param {string} wd absolute path to the patient's tree, just cold-reset
+ * @param {string} spineDir absolute path to this run's spine directory
+ * @param {string} runid this run's own id (the same one every other spine
+ *   file for this run is named after)
+ * @returns {string|null} the path the stale file was moved to, or `null`
+ *   when there was nothing to move
+ */
+export function moveStaleGateAudit(wd, spineDir, runid) {
+  const staleAudit = join(wd, 'gate-audit.jsonl');
+  if (!existsSync(staleAudit)) return null;
+  const preFile = join(spineDir, `pre-${runid}-gate-audit.jsonl`);
+  renameSync(staleAudit, preFile);
+  return preFile;
+}