bareloop 0.28.0 → 0.30.0

package/src/replayio.js

@@ -110,7 +110,13 @@ export function replayOne(spinePath, 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 });
+  // `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;
 }

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/userrun.js

@@ -70,6 +70,8 @@ import { HITL_PAUSE } from './declaredclose.js';
 import { answerReviewDoor, doorRecordOf, doorAgeGate } from './reviewdoor.js';
 // the cold reset, shared with the battery drivers so "cold" has one spelling
 import { coldReset, moveStaleGateAudit } from './u-patient.js';
+// PANEL-BUILD.md P1 — the one run list (`~/.config/bareloop/runs.jsonl`).
+import { appendRun } from './runlist.js';
 // the banner's wall arithmetic, extracted so it is reachable by a test (F83): the
 // end-of-run readout sits past the approval gate, so nothing could ever drive it here
 import { wallLine, doomedResume, deathAtOf, evidencePackage, doorLines, resumeAtLines, reviewDoorPackage, runDoorLines, tokensLine, doorTimingRedLines } from './u-readout.js';
@@ -222,6 +224,10 @@ class ExitSignal extends Error {
  *   check entirely, the same shape `src/cli.js`'s `main(argv, deps)` uses.
  * @property {(tier: string) => any} [providerFor]
  * @property {any} [judgeProvider]
+ * @property {string} [runlistHome] 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.
  */
 
 /**
@@ -1332,6 +1338,26 @@ async function execute(ctx) {
   const runid = Date.now().toString(36);
   const spineFile = join(spineDir, `u-${runid}.jsonl`);
 
+  // PANEL-BUILD.md P1 — one row in the run list, BEFORE any paid call (this
+  // leg's own `runJob` further down, and BEFORE the provider-key checks that
+  // preceded this point already gated on). `runid` is fresh for THIS leg
+  // (cold start or resumed leg both mint one here), so `appendRun`'s own
+  // runid-dedup never fires on the ordinary path — it exists for a caller
+  // that legitimately re-enters with the same runid (e.g. a retried
+  // in-process test). A list-append failure must never block a real,
+  // already-signed run: caught and named loudly, never rethrown.
+  // `deps.runlistHome` — the same injectable test seam `ctx.deps` already
+  // carries everything else through (env/out/err/provider/…): a caller that
+  // injects it writes this leg's row under a temp home instead of the real
+  // `~/.config/bareloop`; production never sets it.
+  try {
+    appendRun({
+      at: new Date().toISOString(), runid, job: spec.job, spine: spineFile, patient: wd, via: 'run-u',
+    }, { home: deps.runlistHome });
+  } catch (/** @type {any} */ e) {
+    err(`WARNING: could not add this run to ~/.config/bareloop/runs.jsonl (${e.message}) — the run continues; the panel's list will be missing this row.`);
+  }
+
   const git = (/** @type {string[]} */ a) => execFileSync('git', ['-C', wd, ...a], { encoding: 'utf8' }).trim();
   if (dead) {
     // A RESUME is the OPPOSITE case from a cold launch: the halted run's edits are work

package/types/behaviour.d.ts

@@ -39,8 +39,10 @@ export function runBehaviour(events: Array<{
  * Render a {@link runBehaviour} summary as the agreed printable block
  * (2–4 short lines). A zero-call run formats plainly ("0 tool calls") rather
  * than a NaN-laced percentage — an empty run is a complete, reportable
- * answer, not a division error.
- * @param {ReturnType<typeof runBehaviour>} summary
+ * answer, not a division error. `summary === null` means the caller never
+ * had a gate-audit sidecar to read at all (see `replayRun`'s `auditAvailable`
+ * option) — that reads as "unknown", never coerced to a 0-call summary.
+ * @param {ReturnType<typeof runBehaviour>|null} summary
  * @returns {string}
  */
-export function formatBehaviour(summary: ReturnType<typeof runBehaviour>): string;
+export function formatBehaviour(summary: ReturnType<typeof runBehaviour> | null): string;

package/types/cli.d.ts

@@ -3,7 +3,7 @@
  * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
  * queued stdout on its own (F-something: `process.exit()` can discard it).
  * @param {string[]} argv
- * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any }} deps
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any, runlistHome?: string }} deps
  * @returns {Promise<number>}
  */
 export function main(argv: string[], deps?: {
@@ -17,4 +17,5 @@ export function main(argv: string[], deps?: {
     judgeModel?: string | null;
     now?: () => number;
     stdin?: any;
+    runlistHome?: string;
 }): Promise<number>;

package/types/panel/server.d.ts

@@ -0,0 +1,265 @@
+/**
+ * `[✓]`/`[✗]`/`[▶]` — the ONLY vocabulary a result is ever rendered in
+ * (auto-memory `ui-verdict-words.md`: never the words green/red/soft-green
+ * anywhere in the page). `null` (no `job-end` reached — a killed-mid-run or
+ * still-running spine) reads `▶` — the same "in progress / unresolved" glyph
+ * P1's own four-glyph vocabulary reserves for that state; a genuinely still-
+ * running attempt and an archived spine that never reached its own end are
+ * the same fact from this read-only side: no verdict has been recorded yet.
+ * @param {string|null} outcome
+ * @returns {'✓'|'✗'|'▶'}
+ */
+export function glyphForOutcome(outcome: string | null): "\u2713" | "\u2717" | "\u25B6";
+/**
+ * `deterministic` (green) / `rubric` (soft-green) / `unknown` (a class this
+ * reader doesn't recognize) — the settled UI wording (PANEL-BUILD.md §6),
+ * never the internal `green`/`soft-green` spelling. Item 3 (2026-09-25): a
+ * spine with NO `verdictType` (pre-F117) is genuinely ambiguous UNLESS its
+ * own run date (`atIso`, the job-start ts) predates {@link
+ * SOFTGREEN_ADMITTED_ISO} — in that one case, `deterministic` was the only
+ * check type that could have run, so it is reported as such (not fabricated:
+ * derived from the frozen historical fact that soft-green did not exist
+ * yet), paired with {@link checkTypeTitle}'s tooltip explaining the
+ * derivation rather than presenting it as if it had been directly recorded.
+ * `atIso` is optional so every existing single-arg caller/test keeps its
+ * prior behavior (no date -> 'unknown', same as before this item).
+ * @param {string|null} verdictType
+ * @param {string|null} [atIso] the run's own job-start timestamp
+ * @returns {'deterministic'|'rubric'|'unknown'}
+ */
+export function checkTypeLabel(verdictType: string | null, atIso?: string | null): "deterministic" | "rubric" | "unknown";
+/**
+ * The tooltip/title text for {@link checkTypeLabel}'s pre-softgreen-cutoff
+ * branch — `null` for every other case (a real `verdictType` needs no
+ * explanation; a genuinely unknown one has none to give).
+ * @param {string|null} verdictType
+ * @param {string|null} [atIso]
+ * @returns {string|null}
+ */
+export function checkTypeTitle(verdictType: string | null, atIso?: string | null): string | null;
+/**
+ * `YYYY-MM-DD HH:MM` (local time, 24h, zero-padded) — the ONE
+ * timestamp-WITH-TIME format this page ever shows (a plain date elsewhere
+ * stays `YYYY-MM-DD`, e.g. `row.at.slice(0,10)`, untouched — that's a
+ * different, shorter field, not this helper's concern). Used instead of a
+ * locale-dependent `toLocaleString()` spelling (F195: the died "why" line
+ * read `9/9/2026, 11:49:40 AM`, inconsistent with every other date on the
+ * page) so a future second timestamp-with-time spot routes through the same
+ * one function rather than growing its own `toLocale*` call.
+ * @param {string|number|Date} ts
+ * @returns {string}
+ */
+export function formatTimestamp(ts: string | number | Date): string;
+/**
+ * `GET /api/runs` — every listed run, NEWEST FIRST BY `at` (never by file/
+ * append order — a backfill scan appends rows in sorted-PATH order, which
+ * does not track chronological `at` order; a plain `.reverse()` here once
+ * silently mis-sorted any list `appendRun` didn't build strictly
+ * chronologically), each enriched with a cheap ($0, `skipAudit:true`)
+ * summary. A row with an unparseable/missing `at` sorts last (Unix epoch 0),
+ * never crashes the sort or floats to the top. Ties (identical `at`) keep
+ * their original file order among themselves (stable sort) rather than an
+ * arbitrary one. The Workflows view (item 2, 2026-09-26 merge) groups this
+ * SAME payload by job client-side (`groupRunsByJob` in `index.html`) rather
+ * than a second server-side endpoint, so the glyph/checkType mapping is
+ * still computed in exactly one place.
+ * @param {{ home?: string }} [opts]
+ * @returns {any[]}
+ */
+export function listRuns(opts?: {
+    home?: string;
+}): any[];
+/**
+ * `GET /api/runs/:runid` — the full replay for the Run tab: steps (or
+ * iterations), counters, summary-box fields. Looks `runid` up in the run
+ * list FIRST and reads only the path stored there (path safety — see file
+ * header); `null` when the runid is not in the list at all (caller renders
+ * 404).
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {any|null}
+ */
+export function getRunDetail(runid: string, opts?: {
+    home?: string;
+}): any | null;
+/**
+ * `GET /api/runs/:runid/audit` — the Audit tab's rows, off the run's own
+ * gate-audit sidecar (name-convention resolution, `src/replayio.js`'s
+ * `resolveSiblings`), scoped to this run's own ts window (see {@link
+ * runAuditWindow} — a sidecar can carry other runs' rows). A row's real
+ * fields (`ts`, `action.type`, `action.path`, `decision`) plus `partIndex`/
+ * `partLabel`/`attemptN` — see {@link makePartLookup} (build item C,
+ * 2026-09-26 rewrite): derived from the row's own ROUND's `seq` matched
+ * against `summary.parts`' own attempt windows, never phase-string guessing.
+ * `reason` names WHY `partIndex` is `null`: `'no-round'` (the row's `ts` falls
+ * before the very first model call) vs `'unassigned'` (a round exists but its
+ * seq matched no part window — an honest gap, never fabricated) vs `null`
+ * when `partIndex` is real.
+ * `round` — see
+ * {@link makeRoundLookup}. A `phase:'record'`/`action.type:'llm'` row (item
+ * 2: every MODEL CALL, `decision` always `null` on the real record) is
+ * marked `kind:'model-call'` with its own `result.{costUsd,tokens,
+ * durationMs}` surfaced directly (never re-derived); every other row is
+ * `kind:'tool-call'`, unchanged.
+ * `reason` distinguishes the two ways this can come back empty (item 1,
+ * 2026-09-25): `'no-sidecar'` — no gate-audit sidecar was ever written for
+ * this run (an older version, or a run-u/native path that never emitted one)
+ * — vs `'sidecar-empty'` — a sidecar file DOES exist but has zero rows FOR
+ * THIS RUN'S OWN WINDOW (the run made no tool/model calls the gate audited,
+ * or every row on disk belongs to a different run sharing the same
+ * filename). The client renders these as two different sentences; never a
+ * bare empty table for either.
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {{runid: string, rows: any[], raw: string, empty: boolean, reason: 'no-sidecar'|'sidecar-empty'|null}|null}
+ */
+export function getRunAudit(runid: string, opts?: {
+    home?: string;
+}): {
+    runid: string;
+    rows: any[];
+    raw: string;
+    empty: boolean;
+    reason: "no-sidecar" | "sidecar-empty" | null;
+} | null;
+/**
+ * `GET /api/runs/:runid/rounds?part=<index>&attempt=<n>&offset=&limit=`
+ * — build item C (2026-09-26 rewrite): the Audit tab's expandable attempt
+ * detail, built server-side in one endpoint and rendered lazily on expand.
+ * REPLACES the earlier step-id/occurrence/`FIX_LOOP_STEP_ID`-sentinel/
+ * `timelineKind` branching (three separate ways to resolve a window,
+ * deleted here) with ONE rule: `part` indexes directly into
+ * `summary.parts` (`src/replay.js`'s own ONE ordered part list — scout,
+ * plan, each step occurrence, replan, fix, judge, or a single `run` part on
+ * an old spine), and `attempt` indexes into THAT part's own `attempts` array
+ * — every part kind already carries at least one (a real per-attempt list
+ * for `step`/`fix`, or a single synthetic whole-part attempt for
+ * scout/plan/replan/judge/run, `src/replay.js`'s `wholePartAttempt`). No
+ * second windowing pass: each attempt's own `startSeq`/`endSeq` is read
+ * directly off `replayOne`'s already-computed summary.
+ * Tool calls per round reuse {@link getRunAudit}'s own already-scoped,
+ * already-round-tagged rows — filtered to this round's number, never
+ * re-derived. `toolLogSaved:false` (no gate-audit sidecar at all) still
+ * returns every round from the spine's own worker-round records, each with
+ * `toolCalls: null` (never a fabricated empty array — the client renders
+ * "tool calls: no log saved").
+ * Pagination: `offset`/`limit` slice the ATTEMPT's rounds list (never a
+ * round's own tool-call list) — `limit` defaults to {@link
+ * ROUNDS_PAGE_DEFAULT}, clamped to {@link ROUNDS_PAGE_MAX}; the response
+ * always carries `totalRounds` so the client can print "showing A–B of N",
+ * never a silently truncated list.
+ * `null` when the run isn't listed, the requested part/attempt index doesn't
+ * resolve to a real window, or the spine file is missing — the caller
+ * renders 404, same posture as {@link getRunAudit}/{@link getRunJob}.
+ * @param {string} runid
+ * @param {{ part?: number, attempt?: number, offset?: number, limit?: number }} query
+ * @param {{ home?: string }} [opts]
+ * @returns {any|null}
+ */
+export function getRunRounds(runid: string, query?: {
+    part?: number;
+    attempt?: number;
+    offset?: number;
+    limit?: number;
+}, opts?: {
+    home?: string;
+}): any | null;
+/**
+ * `GET /api/runs/:runid/job` — the Job tab, filled from the first source
+ * that actually resolves (item 2, 2026-09-25), in order:
+ *  (a) the bundle's own `spec.json` (a `bareloop run` bundle keeps one
+ *      beside its `runs/` dir) — the pre-existing path, unchanged;
+ *  (b) `jobs/<job>.json` in the repo's own jobs/ dir (resolved from the
+ *      package root) — its `jobSpecHash` is compared against the run's own
+ *      job-start `specHash`; a mismatch is shown, never hidden (the job may
+ *      have been edited since this run signed it);
+ *  (c) NEW (item 2, 2026-09-25): the run's own `resolved-spec.json`, found
+ *      beside the spine via {@link sourceNearSpine} — a person-path (`--spec`
+ *      or a source-seed-backed JOBS-table row) run's signed copy, never
+ *      searched for, only read when the on-disk shape unambiguously names it;
+ *  (d) the run's own job-start record (goal/model/budgetUsd/verdictType only
+ *      — a narrower, unsigned record, `resolved:false`);
+ *  else every spec-only field reads `'not recorded'`, never fabricated.
+ * `resolvedFrom` names which of these actually supplied the fields, shown in
+ * the page. `source`/`destination` are resolved SEPARATELY from the rest (any
+ * branch above may supply the goal/close/etc while carrying no source.json of
+ * its own) — from the source front door's manifest when `sourceNearSpine`
+ * finds one, else the run list's own recorded `patient` path for a `source`
+ * with no manifest, else `'not recorded'`. `success`/`guardrails`/`tools` come
+ * from the resolved SPEC only (a) (b) (c) — a job-start record and `none()`
+ * carry no close/writeScope/tools at all, so those stay `'not recorded'`.
+ * @param {string} runid
+ * @param {{ home?: string }} [opts]
+ * @returns {any|null}
+ */
+export function getRunJob(runid: string, opts?: {
+    home?: string;
+}): any | null;
+/**
+ * Handle one request against the read-only API + the page. Exported
+ * separately from {@link createPanelServer} so tests can drive it without a
+ * real listening socket where that is simpler (most path-safety/405 tests
+ * still go through a real socket, per the build spec).
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ home?: string, port: number }} opts
+ */
+export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
+    home?: string;
+    port: number;
+}): void;
+/**
+ * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
+ * non-zero-exit failure — this never falls back to another port (see file
+ * header). Resolves once actually listening; rejects on a bind error
+ * (including `EADDRINUSE`) with a `.port` field on the error for the
+ * caller's message.
+ * @param {{ port?: number, home?: string }} [opts]
+ * @returns {Promise<{ server: import('node:http').Server, port: number, close: () => Promise<void> }>}
+ */
+export function createPanelServer(opts?: {
+    port?: number;
+    home?: string;
+}): Promise<{
+    server: import("node:http").Server;
+    port: number;
+    close: () => Promise<void>;
+}>;
+/**
+ * `bareloop panel [--port N]` — the CLI entry (`src/cli.js` dispatch).
+ * Never picks a different port on collision (see file header): prints a
+ * loud, named error to stderr and returns 1.
+ * @param {string[]} argv
+ * @param {{ out: (s: string) => void, err: (s: string) => void, runlistHome?: string }} ctx
+ * @returns {Promise<number>}
+ */
+export function panelMain(argv: string[], ctx: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    runlistHome?: string;
+}): Promise<number>;
+/**
+ * A runid, as it appears in a URL path segment — never a raw filesystem
+ * path. `~` is included so a backfill-disambiguated runid (F197:
+ * `src/runlist.js`'s `backfillRuns`, e.g. `run~2` when two archived spines
+ * derive the same filename-based runid) is a legal, reachable id, never a
+ * 400.
+ */
+export const RUNID_RE: RegExp;
+/** Default bind port (PANEL-BUILD.md P1: checked free on the build machine, not guaranteed elsewhere — the server still fails loudly on collision, see {@link createPanelServer}). */
+export const DEFAULT_PORT: 4700;
+/**
+ * Soft-green was admitted at commit 30df0f9 (2026-08-18) — before that,
+ * `green` was the only admissible verdict type, so a run started before this
+ * moment that carries no `verdictType` at all (pre-F117 spine) really was
+ * deterministic; there was no other check type it could have been. Tighten-
+ * only, named so a future change is a deliberate, visible edit (item 3,
+ * 2026-09-25).
+ */
+export const SOFTGREEN_ADMITTED_ISO: "2026-08-18T00:00:00.000Z";
+export const DIED_MTIME_MS: number;
+/** The default/max page size for {@link getRunRounds} — tighten-only,
+ * named so a future change is a deliberate, visible edit (item 5,
+ * 2026-09-25). */
+export const ROUNDS_PAGE_DEFAULT: 50;
+export const ROUNDS_PAGE_MAX: 200;