bareloop 0.27.0 → 0.28.0

package/src/planrun.js

@@ -932,7 +932,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   it the deterministic name would collide with that very branch and the collision walk
  *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
  *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
- * @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 (2026-08-12 §1, re-cut 2026-08-17: accept | rerun <text> | pause), carried in
  *   by the runner on the leg that RESUMES a paused run. Absent on every ordinary run and
  *   on the leg that pauses; it is never authored, never defaulted, and never inferred.

package/src/replayio.js

@@ -0,0 +1,153 @@
+// 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 };
+  const summary = replayRun(spine.records, audit.records, { runId });
+  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/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;
+}