bareloop 0.28.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/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/userrun.d.ts

@@ -52,6 +52,13 @@ export type Deps = {
     provider?: any;
     providerFor?: ((tier: string) => any) | undefined;
     judgeProvider?: any;
+    /**
+     * F196 — a test seam for `appendRun`'s
+     * (src/runlist.js) `home` override, the same shape `deps.provider` already
+     * is. Production never sets it; `appendRun` falls through to its own
+     * `os.homedir()`-based default.
+     */
+    runlistHome?: string | undefined;
 };
 export type RunOpts = {
     /**