bareloop 0.27.0 → 0.29.0

package/types/replay.d.ts

@@ -1,3 +1,41 @@
+/**
+ * `[startTs, endTs]` (epoch ms; `endTs` possibly `Infinity`) bounding the
+ * gate-audit rows that actually belong to ONE run's own spine. A sidecar
+ * file can be SHARED across several runs whose spines happen to reuse the
+ * same filename (measured directly on a real archived patient —
+ * pulselog-person-live-2, run mu2p83go: its sidecar carries rows from 7
+ * distinct `run_id`s spanning 06:56Z..13:25Z on one day, but this run's own
+ * `job-start`..`job-end` window is 13:19:40Z..13:25:48Z; every row before
+ * that window belongs to an earlier, unrelated run sharing the sidecar
+ * path). No `step`/`run_id` field on a gate-audit row is a reliable enough
+ * key on its own (see this file's header) — bounding by `ts` against this
+ * run's own `job-start`/`job-end` is the only honest scope.
+ *
+ * `startTs` is this run's own `job-start.ts` (`-Infinity` when absent —
+ * never a guessed lower bound). `endTs` is `job-end.ts` when a `job-end`
+ * was actually reached, else `Infinity` (a died/still-running run — never
+ * clamped to the spine's own last record's `ts`, which would wrongly
+ * exclude a real tool call the gate logged just AFTER the spine's own last
+ * record landed: spine and gate-audit are written by different seams and
+ * are not guaranteed to interleave exactly).
+ *
+ * ONE shared owner for this rule (F195): `replayRun` (this file) uses it to
+ * scope every audit row it hands to `runBehaviour`, so `bareloop replay`
+ * and every caller of `replayRun`/`replayOne` (including the panel,
+ * `src/panel/server.js`) read the same, honest figure — never two places
+ * independently re-deriving (and risking drifting from) the same rule.
+ * @param {{ts?: string}|null} [jobStart]
+ * @param {{ts?: string}|null} [jobEnd]
+ * @returns {{startTs: number, endTs: number}}
+ */
+export function auditWindow(jobStart?: {
+    ts?: string;
+} | null, jobEnd?: {
+    ts?: string;
+} | null): {
+    startTs: number;
+    endTs: number;
+};
 /**
  * Reconstruct one run's whole story from its spine + gate-audit. Pure: no
  * IO, no spine writes, no verdict. Malformed/non-object entries in either
@@ -18,16 +56,26 @@
  *
  * @param {any[]} spineEvents parsed records from `u-<id>.jsonl`
  * @param {any[]} [auditEvents] parsed records from the sibling `-gate-audit.jsonl`
- * @param {{runId?: string|null}} [opts] `runId`: caller-supplied (the spine
- *   carries no run-id field of its own — see the file header)
+ * @param {{runId?: string|null, auditAvailable?: boolean}} [opts] `runId`:
+ *   caller-supplied (the spine carries no run-id field of its own — see the
+ *   file header). `auditAvailable` (default `true`, back-compat: every
+ *   direct caller in this codebase that hands a literal `[]` here means a
+ *   REAL, known-empty audit, not "unknown") — set `false` only when the
+ *   caller could not even determine whether a gate-audit sidecar exists (no
+ *   file found on disk, or deliberately not read). When `false`, every
+ *   tool-call figure this function derives (`behaviour`, each occurrence's
+ *   `toolCalls`) reads `null` (unknown), never `0` — doctrine: unknown is
+ *   reported as unknown, never rendered as zero.
  */
-export function replayRun(spineEvents: any[], auditEvents?: any[], { runId }?: {
+export function replayRun(spineEvents: any[], auditEvents?: any[], { runId, auditAvailable }?: {
     runId?: string | null;
+    auditAvailable?: boolean;
 }): {
     runId: string | null;
     job: any;
     verdictType: any;
     model: any;
+    provider: any;
     code: {
         version: any;
         sha: any;
@@ -71,14 +119,51 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId }?: {
         diffUsd: number;
     } | null;
     timelineKind: "steps" | "iterations";
+    scoutPlan: {
+        rounds: number;
+        toolCalls: number | null;
+        wallMs: number | null;
+        spentUsd: number | null;
+        unpricedRounds: number;
+        tripped: {
+            category: any;
+            detail: string | null;
+        } | null;
+        transportRetries: {
+            count: number;
+            label: string;
+            error: string | null;
+        } | null;
+        scoutRounds: number;
+        planRounds: number;
+    } | null;
     steps: {
         checks: {
             passed: number;
             failed: number;
         };
         treeChanged: boolean;
+        attempts: {
+            n: number;
+            iteration: number | null;
+            outcome: "green" | "red";
+        }[];
+        attemptWindows: {
+            n: number;
+            iteration: number | null;
+            outcome: "green" | "red";
+            startSeq: number;
+            endSeq: number;
+            startTs: number | null;
+            endTs: number | null;
+            exitEvalDetail: string | null;
+        }[];
+        stepStartSeq: any;
+        stepEndSeq: any;
+        stepStartTs: number | null;
+        stepEndTs: number | null;
         rounds: number;
-        toolCalls: number;
+        toolCalls: number | null;
         wallMs: number | null;
         spentUsd: number | null;
         unpricedRounds: number;
@@ -96,8 +181,12 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId }?: {
         outcome: any;
     }[];
     iterations: {
+        windowStartSeq: any;
+        windowEndSeq: any;
+        windowStartTs: number | null;
+        windowEndTs: number | null;
         rounds: number;
-        toolCalls: number;
+        toolCalls: number | null;
         wallMs: number | null;
         spentUsd: number | null;
         unpricedRounds: number;
@@ -118,6 +207,15 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId }?: {
             stages: any;
         } | null;
     }[];
+    fixLoop: {
+        attempts: any[];
+        rounds: any;
+        toolCalls: any;
+        wallMs: any;
+        spentUsd: any;
+        unpricedRounds: any;
+    } | null;
+    parts: any[];
     replans: any;
     close: {
         source: "close-verdict" | "outer-close";
@@ -137,7 +235,7 @@ export function replayRun(spineEvents: any[], auditEvents?: any[], { runId }?: {
         uniquePaths: number;
         repeats: number;
         repeatPct: number | null;
-    };
+    } | null;
     memoryCache: any;
     skipped: number;
 };

package/types/replayio.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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: string): {
+    records: any[];
+    skipped: number;
+};
+/**
+ * `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: string): boolean;
+/**
+ * `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: any[]): boolean;
+/**
+ * `<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: string): {
+    runId: string;
+    auditPath: string | 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: string, opts?: {
+    preParsedSpine?: {
+        records: any[];
+        skipped: number;
+    };
+    skipAudit?: boolean;
+}): ReturnType<typeof replayRun>;
+/**
+ * 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: string): Array<{
+    kind: "spine";
+    row: ReturnType<typeof summarizeForAllLine>;
+} | {
+    kind: "not-a-spine";
+    name: string;
+}>;
+/**
+ * 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: string): {
+    rows: any[];
+    skipped: number;
+};
+import { replayRun } from './replay.js';
+import { summarizeForAllLine } from './replay.js';

package/types/reuse.d.ts

@@ -234,7 +234,7 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
  * 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.
@@ -246,7 +246,7 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
 export function readResume(events: any[], { deathAt, direct, resumableOutcomes }?: {
     deathAt?: number | null;
     direct?: boolean;
-    resumableOutcomes?: string[];
+    resumableOutcomes?: readonly string[];
 }): any;
 /**
  * The AGE gate for a paused checkpoint — the sibling of `resumeTreeGate`, and it

package/types/run.d.ts

@@ -143,7 +143,7 @@
  *        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
@@ -219,7 +219,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     layerRoot?: boolean | undefined;
     humanRuling?: {
         decision: string;
-        text?: string;
+        text?: string | null;
     } | null | undefined;
     heldRuling?: {
         decision: string;

package/types/runlist.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `~/.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?: string): string;
+/**
+ * `<home>/runs.jsonl`.
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function runlistPath(home?: string): string;
+/**
+ * @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: RunRow, opts?: {
+    home?: string;
+}): {
+    appended: boolean;
+    reason?: "duplicate-runid";
+};
+/**
+ * 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?: {
+    home?: string;
+}): {
+    rows: RunRow[];
+    skipped: number;
+};
+/**
+ * `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: string, opts?: {
+    home?: string;
+}): {
+    added: number;
+    alreadyListed: number;
+    skipped: number;
+    addedRows: RunRow[];
+};
+/**
+ * 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: RunRow): string;
+export const MAX_BACKFILL_DEPTH: 6;
+export type RunRow = {
+    at: string;
+    runid: string;
+    job: string;
+    spine: string;
+    patient: string | null;
+    via: "run-u" | "bundle" | "backfill";
+};

package/types/u-patient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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: string, seed: string): {
+    head: string;
+    storeRemoved: boolean;
+};
+/**
+ * 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: string, spineDir: string, runid: string): string | null;