bareloop 0.33.0 → 0.35.0

package/src/panel/importroutes.js

@@ -0,0 +1,359 @@
+// PANEL-BUILD.md P5 item 4 — IMPORT, READ ONLY. A person points the panel at a job folder (an exported bundle) to
+// LOOK at it: its goal, checks, guardrails, caps, model, exported history and whether it is approved on this
+// machine. Nothing here runs a bundle, signs anything or writes into the folder; the only write is one line in
+// `<home>/imports.jsonl` (`{at, dir, job, bundleHash}`, the list of what was imported).
+//
+// Two routes carry NEW DISK EXPOSURE, so both sit behind `checkHumanGuard` (token + own address), the strict
+// guard `/api/author/*` has — not just the Host guard the read-only GETs use:
+//   GET  /api/fs/list?path=   the job bundles (a manifest.json file sits there) found up to 3 folders below path
+//   POST /api/imports {path}  import one folder (readBundle must be clean)
+// plus the guarded reads `GET /api/imports` (the list, every bundle re-read) and `GET /api/imports/:id` (one view).
+//
+// PATH SAFETY (the listing is a window onto the person's disk, so it is narrow by construction):
+//   * the requested path is expanded (`~` / `~/…` only), refused if it carries a NUL byte or is not absolute,
+//     then `resolve`d (`.`/`..` collapsed) and `realpath`ed — the REAL folder is what is listed and what is
+//     recorded, and the response says which it chose (`path` beside `requested`);
+//   * a path that is not a directory is refused; names are listed, file CONTENTS are never read here;
+//   * a SYMLINK inside the search is never listed and never followed (Dirent.isDirectory() is false for a link,
+//     which is what `readdir` withFileTypes reports — it types by lstat); `node_modules`, `.git` and dot-folders are
+//     skipped, a bundle is never descended into, and the search is capped (folders visited, bundles returned);
+//   * the `bundle` tag is a regular FILE named manifest.json (lstat), never a link to one.
+
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import {
+  writeFileSync, renameSync, mkdirSync, readFileSync, existsSync, readdirSync, statSync, lstatSync, realpathSync,
+} from 'node:fs';
+import { dirname, join, isAbsolute, resolve } from 'node:path';
+import { checkHumanGuard } from './authorroutes.js';
+import { readBundle, verifyBlessing } from '../bundle.js';
+import { runlistHome } from '../runlist.js';
+import { statusFor, GOAL_MET_LINE } from './status.js';
+import { bundleRuns, latestGreenRun, latestBridgeGreen, bridgeRunDetail, importedRunId } from './importrun.js';
+
+/** the longest path the routes will look at (bytes) */
+export const MAX_PATH_LEN = 4096;
+
+/**
+ * Expand, normalise and `realpath` a requested folder. Never throws.
+ * @param {unknown} input the raw `path` (absent/blank = the person's home folder)
+ * @param {string} userHome the home folder (`~`)
+ * @returns {{ok: true, requested: string, path: string}|{ok: false, error: string}}
+ */
+export function resolveFsPath(input, userHome) {
+  const raw = input === undefined || input === null ? '' : input;
+  if (typeof raw !== 'string') return { ok: false, error: 'the path must be text' };
+  if (raw.length > MAX_PATH_LEN) return { ok: false, error: 'that path is too long' };
+  if (raw.includes('\0')) return { ok: false, error: 'that path has a character no folder name can have' };
+  let want = raw.trim();
+  if (want === '') want = userHome;
+  else if (want === '~') want = userHome;
+  else if (want.startsWith('~/')) want = join(userHome, want.slice(2));
+  else if (want.startsWith('~')) return { ok: false, error: 'only ~ and ~/… are understood, not another user\'s home' };
+  if (!isAbsolute(want)) return { ok: false, error: 'use an absolute path (starting with / or ~)' };
+  const requested = resolve(want);
+  /** @type {string} */
+  let real;
+  try { real = realpathSync(requested); } catch (/** @type {any} */ e) {
+    return { ok: false, error: e?.code === 'ENOENT' ? `no such folder: ${requested}` : `could not open ${requested} (${e?.code ?? 'error'})` };
+  }
+  let isDir = false;
+  try { isDir = statSync(real).isDirectory(); } catch { isDir = false; }
+  if (!isDir) return { ok: false, error: `not a folder: ${real}` };
+  return { ok: true, requested, path: real };
+}
+
+/** how many levels below the current folder the bundle search looks */
+export const SEARCH_DEPTH = 3;
+/** the most folders one search visits; past it `stopped: true` */
+export const MAX_VISITED = 5000;
+/** the most bundles one search returns; past it `truncated: true` */
+export const MAX_RESULTS = 200;
+
+/** a bundle is a folder holding a regular FILE named manifest.json (lstat — never a link to one) */
+function isBundleDir(/** @type {string} */ dir) {
+  try { return lstatSync(join(dir, 'manifest.json')).isFile(); } catch { return false; }
+}
+
+/**
+ * The exported job bundles below `dir` (a `realpath` already), searched DOWN at most SEARCH_DEPTH levels. Symlinks are
+ * never followed, `node_modules`, `.git` and every dot-folder are skipped, a bundle is never descended into, an
+ * unreadable folder is skipped silently, and the search is capped (folders visited, results). Only names are read.
+ * @param {string} dir
+ * @returns {{entries: {name: string, path: string, bundle: true}[], visited: number, stopped: boolean, truncated: boolean}}
+ */
+export function findBundles(dir) {
+  /** @type {{name: string, path: string, bundle: true}[]} */
+  const entries = [];
+  let visited = 0;
+  let stopped = false;
+  let truncated = false;
+  /** @param {string} cur @param {string} rel @param {number} depth */
+  const walk = (cur, rel, depth) => {
+    if (depth > SEARCH_DEPTH || stopped || truncated) return;
+    /** @type {string[]} */
+    let names;
+    try { names = readdirSync(cur, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name); } catch { return; }
+    names.sort((a, b) => a.localeCompare(b));
+    for (const name of names) {
+      if (name === 'node_modules' || name.startsWith('.')) continue;
+      if (visited >= MAX_VISITED) { stopped = true; return; }
+      visited += 1;
+      const path = join(cur, name);
+      const r = rel ? `${rel}/${name}` : name;
+      if (isBundleDir(path)) {
+        if (entries.length >= MAX_RESULTS) { truncated = true; return; }
+        entries.push({ name: r, path, bundle: true });
+      } else walk(path, r, depth + 1);
+      if (stopped || truncated) return;
+    }
+  };
+  walk(dir, '', 1);
+  return { entries, visited, stopped, truncated };
+}
+
+/** @param {string} [home] @returns {string} `<home>/imports.jsonl` */
+export function importsPath(home) { return join(runlistHome(home), 'imports.jsonl'); }
+
+/** the stable id of an imported folder (its real path, hashed — never the path itself in a URL) */
+export function importId(/** @type {string} */ dir) { return createHash('sha256').update(dir).digest('hex').slice(0, 12); }
+
+/** a folder's realpath, or the text itself when it cannot be resolved (a moved/deleted folder still lists) */
+function realDir(/** @type {string} */ dir) { try { return realpathSync(dir); } catch { return dir; } }
+
+/**
+ * Record one import: ONE row per real folder. Any earlier row for the same folder is dropped and the new one is
+ * written, so re-importing updates the entry instead of adding a second. The rewrite goes through a temp file + rename.
+ * @param {string|undefined} home
+ * @param {{at: string, dir: string, job: string, bundleHash: string}} row
+ */
+export function recordImport(home, row) {
+  const file = importsPath(home);
+  const key = realDir(row.dir);
+  /** @type {string[]} */
+  const keep = [];
+  let text = '';
+  try { text = readFileSync(file, 'utf8'); } catch { text = ''; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { keep.push(line); continue; } // never drop what we cannot read
+    if (o && typeof o.dir === 'string' && realDir(o.dir) === key) continue;
+    keep.push(line);
+  }
+  keep.push(JSON.stringify(row));
+  mkdirSync(runlistHome(home), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${keep.join('\n')}\n`, { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/**
+ * The imported list: the LATEST row per folder (a re-import supersedes), newest first. A malformed line is skipped.
+ * @param {string} [home]
+ * @returns {{at: string, dir: string, job: string, bundleHash: string, id: string}[]}
+ */
+export function readImports(home) {
+  let text = '';
+  try { text = readFileSync(importsPath(home), 'utf8'); } catch { return []; }
+  /** @type {Map<string, any>} */
+  const byDir = new Map();
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let r;
+    try { r = JSON.parse(line); } catch { continue; }
+    if (r && typeof r.dir === 'string' && typeof r.job === 'string' && typeof r.bundleHash === 'string') {
+      // one row per REAL folder: a later line (or a symlinked spelling of the same folder) replaces the earlier one
+      const key = realDir(r.dir);
+      const prev = byDir.get(key);
+      if (!prev || String(r.at) >= String(prev.at)) byDir.set(key, { ...r, id: importId(r.dir) });
+    }
+  }
+  return [...byDir.values()].sort((a, b) => String(b.at).localeCompare(String(a.at)));
+}
+
+/** The ONE spelling of the plain-words line for a changed import (Run tab, reuse refusal). The list tag stays the short statusText. */
+export const IMPORT_CHANGED_LINE = 'files changed since you imported it \u2014 Reuse is off. Import it again if the change was yours.';
+
+/**
+ * Re-read one imported folder NOW and say how it stands against the import: `ok`, `changed` (the bundle's own
+ * hash, a tampered file or an unreadable part differ from what was imported — shown red as "changed since
+ * import"), or `missing` (the folder is gone). Never throws.
+ * @param {{dir: string, bundleHash: string}} row
+ * @returns {{status: 'ok'|'changed'|'missing', statusText: string|null, reds: string[], bundle: ReturnType<typeof readBundle>}}
+ */
+export function bundleStatus(row) {
+  const bundle = readBundle(row.dir);
+  const reds = bundle.reds.map((r) => r.code);
+  if (!existsSync(row.dir)) return { status: 'missing', statusText: 'folder not found — it was moved or deleted since import', reds, bundle };
+  const hash = bundle.manifest && typeof bundle.manifest.bundleHash === 'string' ? bundle.manifest.bundleHash : null;
+  if (bundle.ok && hash === row.bundleHash) return { status: 'ok', statusText: null, reds, bundle };
+  return { status: 'changed', statusText: 'changed since import', reds, bundle };
+}
+
+/**
+ * The `bundle` half of an import view: the exported history (the registry rows the bundle shipped), the approval
+ * on THIS machine (`blessing.json`, written by the first green run here), nothing about the folder's other files.
+ * @param {ReturnType<typeof readBundle>} bundle
+ */
+export function bundleHistoryAndApproval(bundle) {
+  /** @type {any[]} */
+  const rows = [];
+  for (const b of bundle.bridges) if (b && Array.isArray(b.history)) rows.push(...b.history);
+  rows.sort((a, b) => String(b?.at ?? '').localeCompare(String(a?.at ?? '')));
+  const greens = rows.filter((r) => r && r.outcome === 'green').length;
+  const approval = verifyBlessing(bundle);
+  const blessedAt = bundle.blessing && typeof bundle.blessing.blessedAt === 'string' ? bundle.blessing.blessedAt.slice(0, 10) : null;
+  return {
+    history: {
+      greens, reds: rows.length - greens, total: rows.length,
+      recent: rows.slice(0, 10).map((r) => ({
+        at: typeof r?.at === 'string' ? r.at : null, runid: typeof r?.runid === 'string' ? r.runid : null,
+        outcome: typeof r?.outcome === 'string' ? r.outcome : null, costUsd: typeof r?.costUsd === 'number' ? r.costUsd : null,
+      })),
+    },
+    approved: approval.ok,
+    approvedText: approval.ok ? `approved on this machine${blessedAt ? ` (first green run ${blessedAt})` : ''}`
+      : (approval.unblessed ? 'not approved on this machine yet — it has never run green here'
+        : 'approval is stale — the bundle changed since it was approved'),
+  };
+}
+
+/**
+ * The import routes' handler. `describeSpec(spec)` is the server's own spec reader (the SAME fact-readers the Job
+ * tab uses, so an imported job and a run read alike): `{checkType, goal, success, guardrails, model, budgetUsd,
+ * maxWallMs}`.
+ * @param {{ port: number, token: string, home?: string, userHome?: string,
+ *   describeSpec: (spec: any) => any }} opts
+ */
+export function createImportRoutes(opts) {
+  const userHome = opts.userHome ?? homedir();
+
+  /** the view of one imported row, re-read now */
+  const viewOf = (/** @type {{id: string, at: string, dir: string, job: string, bundleHash: string}} */ row) => {
+    const st = bundleStatus(row);
+    const spec = st.bundle.spec;
+    const iv = importedRunView(row, st.bundle);
+    return {
+      id: row.id, job: row.job, dir: row.dir, importedAt: row.at, bundleHash: row.bundleHash,
+      status: st.status, statusText: st.statusText, changedLine: st.status === 'changed' ? IMPORT_CHANGED_LINE : null, reds: st.reds,
+      ...(spec && typeof spec === 'object' ? opts.describeSpec(spec) : {}),
+      ...bundleHistoryAndApproval(st.bundle),
+      ...iv,
+      runStatus: iv.run.kind !== 'none' ? statusFor({ outcome: 'green' }) : null, runReason: iv.run.kind !== 'none' ? GOAL_MET_LINE : null,
+    };
+  };
+
+  /**
+   * What the Run tab shows below the IMPORTED facts (see importrun.js): `runsHere` (run folders with a readable spine),
+   * and `run` — `{kind:'spine', id, runid, at}` (the newest green run in the bundle's `runs/`, read through
+   * `/api/runs/<id>`), `{kind:'bridge', runid, at, detail}` (the bridge's green version as a run detail) or
+   * `{kind:'none'}`. Never throws: a bundle that cannot be read is `none`.
+   * @param {{id: string, dir: string, job: string}} row
+   * @param {ReturnType<typeof readBundle>} bundle
+   */
+  const importedRunView = (row, bundle) => {
+    try {
+      const runsHere = bundleRuns(row.dir).length;
+      const g = latestGreenRun(row.dir);
+      if (g) return { runsHere, run: { kind: 'spine', id: importedRunId(row.id, g.runid), runid: g.runid, at: g.at } };
+      const b = latestBridgeGreen(bundle.bridges);
+      if (b) {
+        const spec = bundle.spec && typeof bundle.spec === 'object' ? bundle.spec : {};
+        const facts = opts.describeSpec(spec);
+        const detail = bridgeRunDetail(b, {
+          job: row.job, checkType: facts.checkType, checkTypeTitle: null,
+          model: typeof spec.model === 'string' && spec.model.length > 0 ? spec.model : null,
+          budgetUsd: typeof spec.budgetUsd === 'number' ? spec.budgetUsd : null,
+        });
+        return { runsHere, run: { kind: 'bridge', runid: detail.runid, at: b.version.greenAt, detail } };
+      }
+      return { runsHere, run: { kind: 'none' } };
+    } catch {
+      return { runsHere: 0, run: { kind: 'none' } };
+    }
+  };
+
+  /**
+   * @param {import('node:http').IncomingMessage} req
+   * @param {import('node:http').ServerResponse} res
+   * @param {string} pathname
+   * @param {any} body
+   * @returns {boolean}
+   */
+  function handle(req, res, pathname, body) {
+    const viewM = /^\/api\/imports\/([0-9a-f]{12})$/.exec(pathname);
+    if (pathname !== '/api/fs/list' && pathname !== '/api/imports' && !viewM) return false;
+    const send = (/** @type {number} */ code, /** @type {any} */ obj) => {
+      const text = JSON.stringify(obj);
+      res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
+      res.end(text);
+    };
+    const guard = checkHumanGuard(req, { token: opts.token, port: opts.port });
+    if (!guard.ok) { send(403, { ok: false, error: `refused — ${guard.reason}` }); return true; }
+
+    if (pathname === '/api/fs/list') {
+      if (req.method !== 'GET') { send(405, { ok: false, error: 'GET only' }); return true; }
+      const q = new URL(/** @type {string} */ (req.url), 'http://127.0.0.1').searchParams.get('path') ?? '';
+      const r = resolveFsPath(q, userHome);
+      if (!r.ok) { send(400, r); return true; }
+      try {
+        const l = findBundles(r.path);
+        const parent = dirname(r.path);
+        send(200, {
+          ok: true, requested: r.requested, path: r.path, parent: parent === r.path ? null : parent,
+          bundle: (() => { try { return lstatSync(join(r.path, 'manifest.json')).isFile(); } catch { return false; } })(),
+          entries: l.entries, truncated: l.truncated, stopped: l.stopped, visited: l.visited, depth: SEARCH_DEPTH,
+        });
+      } catch (/** @type {any} */ e) {
+        send(400, { ok: false, error: `could not read ${r.path} (${e?.code ?? 'error'})` });
+      }
+      return true;
+    }
+
+    if (viewM) {
+      if (req.method !== 'GET') { send(405, { ok: false, error: 'GET only' }); return true; }
+      const row = readImports(opts.home).find((x) => x.id === viewM[1]);
+      if (!row) { send(404, { ok: false, error: 'no such imported job' }); return true; }
+      send(200, { ok: true, ...viewOf(row) });
+      return true;
+    }
+
+    // /api/imports
+    if (req.method === 'GET') {
+      send(200, {
+        ok: true,
+        imports: readImports(opts.home).map((r) => {
+          const st = bundleStatus(r);
+          // the sign + word of the green run the view will SHOW (null when the bundle holds none — nothing to wear a word)
+          const shown = importedRunView(r, st.bundle).run.kind !== 'none';
+          return {
+            id: r.id, job: r.job, dir: r.dir, importedAt: r.at, bundleHash: r.bundleHash, status: st.status, statusText: st.statusText,
+            runStatus: shown ? statusFor({ outcome: 'green' }) : null, runReason: shown ? GOAL_MET_LINE : null,
+          };
+        }),
+      });
+      return true;
+    }
+    if (req.method !== 'POST') { send(405, { ok: false, error: 'GET or POST only' }); return true; }
+    const r = resolveFsPath(body?.path, userHome);
+    if (!r.ok) { send(400, r); return true; }
+    const bundle = readBundle(r.path);
+    if (!bundle.ok || !bundle.manifest || typeof bundle.manifest.job !== 'string' || typeof bundle.manifest.bundleHash !== 'string') {
+      const why = bundle.reds.length > 0 ? bundle.reds.map((x) => `${x.code} (${x.path})`).join('; ') : 'no manifest';
+      send(400, { ok: false, error: `${r.path} is not a clean exported job folder — ${why}` });
+      return true;
+    }
+    const row = { at: new Date().toISOString(), dir: r.path, job: bundle.manifest.job, bundleHash: bundle.manifest.bundleHash };
+    try {
+      recordImport(opts.home, row);
+    } catch (/** @type {any} */ e) {
+      send(500, { ok: false, error: `could not record the import: ${e?.message ?? e}` });
+      return true;
+    }
+    send(200, { ok: true, id: importId(r.path), job: row.job, dir: r.path, requested: r.requested });
+    return true;
+  }
+
+  return { handle, viewOf };
+}

package/src/panel/importrun.js

@@ -0,0 +1,203 @@
+// An IMPORTED job's Run tab reads like a normal run page: the latest GREEN run in the bundle, rendered by the same
+// summary / map / audit code a run uses. Where that run comes from, in order:
+//   1. `<bundle>/runs/<runid>/spine.jsonl` (what `bareloop run <bundle>` writes) — the newest one that ended green.
+//      The panel reads it through the ordinary `/api/runs/<id>` routes (the run's id there is `<importId>~<runid>`).
+//   2. else the bundle's bridge (`bridges/*.json`): the plan's steps and the numbers the bridge carries, as a run
+//      detail with every field it does not carry left null (the page says "not recorded", never 0).
+//   3. else nothing: "no green run in this bundle".
+// READ ONLY, and the bundle is untrusted input: nothing is ever written into it; every path is built from a checked
+// name and `lstat`ed (a link is never followed), reads are size-bounded, a parse failure reads as "not recorded".
+
+import { lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { replayOne, parseJsonl } from '../replayio.js';
+import { statusFor } from './status.js';
+
+/** the most run folders one bundle is searched through (newest first) */
+export const MAX_RUN_DIRS = 40;
+/** the biggest spine / tool-log file that is read (bytes) */
+export const MAX_RUN_FILE_BYTES = 32 * 1024 * 1024;
+const RUN_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const IMPORTED_RUN_RE = /^([0-9a-f]{12})~([A-Za-z0-9_-]{1,64})$/;
+
+/** @param {string} p @returns {import('node:fs').Stats|null} */
+function lst(p) { try { return lstatSync(p); } catch { return null; } }
+
+/** the id an imported run has in `/api/runs/<id>` @param {string} importId @param {string} runid */
+export function importedRunId(importId, runid) { return `${importId}~${runid}`; }
+
+/** @param {string} id @returns {{importId: string, runid: string}|null} */
+export function parseImportedRunId(id) {
+  const m = IMPORTED_RUN_RE.exec(id);
+  return m ? { importId: m[1], runid: m[2] } : null;
+}
+
+/**
+ * The spine path of `<dir>/runs/<runid>`, or null when it is not a plain, bounded file in plain folders: `runs/` and
+ * the run folder must be real directories (a link is refused), the spine a regular file under the size bound, and a
+ * tool log beside it (either spelling the replay reader looks for) must not be a link or oversize either.
+ * @param {string} dir the bundle folder
+ * @param {string} runid
+ * @returns {string|null}
+ */
+export function safeSpinePath(dir, runid) {
+  if (typeof runid !== 'string' || !RUN_NAME_RE.test(runid)) return null;
+  const runDir = join(dir, 'runs', runid);
+  for (const p of [join(dir, 'runs'), runDir]) {
+    const s = lst(p);
+    if (!s || !s.isDirectory()) return null;
+  }
+  const spine = join(runDir, 'spine.jsonl');
+  const ss = lst(spine);
+  if (!ss || !ss.isFile() || ss.size > MAX_RUN_FILE_BYTES) return null;
+  for (const name of ['gate-audit.jsonl', 'spine-gate-audit.jsonl']) {
+    const s = lst(join(runDir, name));
+    if (s && (!s.isFile() || s.size > MAX_RUN_FILE_BYTES)) return null;
+  }
+  return spine;
+}
+
+/**
+ * The run folders of a bundle that hold a readable spine, newest spine first (bounded).
+ * @param {string} dir
+ * @returns {{runid: string, spine: string, mtimeMs: number}[]}
+ */
+export function bundleRuns(dir) {
+  let names;
+  try { names = readdirSync(join(dir, 'runs'), { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name); } catch { return []; }
+  /** @type {{runid: string, spine: string, mtimeMs: number}[]} */
+  const out = [];
+  for (const runid of names) {
+    const spine = safeSpinePath(dir, runid);
+    const s = spine ? lst(spine) : null;
+    if (spine && s) out.push({ runid, spine, mtimeMs: s.mtimeMs });
+  }
+  out.sort((a, b) => (b.mtimeMs - a.mtimeMs) || a.runid.localeCompare(b.runid));
+  return out.slice(0, MAX_RUN_DIRS);
+}
+
+/**
+ * When the run started: its `job-start` record's `ts`, else the spine file's mtime (an ISO string). Never throws.
+ * @param {string} spine
+ * @returns {string}
+ */
+export function spineStartedAt(spine) {
+  try {
+    const first = parseJsonl(spine).records.find((r) => r && r.type === 'job-start' && typeof r.ts === 'string' && Number.isFinite(Date.parse(r.ts)));
+    if (first) return first.ts;
+  } catch { /* falls back to the file's own time */ }
+  const s = lst(spine);
+  return new Date(s ? s.mtimeMs : 0).toISOString();
+}
+
+/**
+ * The newest run in the bundle whose spine ended green (`green` / `already-green`, the same two the run page's Ended
+ * block calls green). A spine that cannot be read is skipped, never fatal.
+ * @param {string} dir
+ * @returns {{runid: string, spine: string, at: string}|null}
+ */
+export function latestGreenRun(dir) {
+  for (const r of bundleRuns(dir)) {
+    let outcome = null;
+    try { outcome = replayOne(r.spine, { skipAudit: true }).outcome; } catch { continue; }
+    if (outcome === 'green' || outcome === 'already-green') return { runid: r.runid, spine: r.spine, at: spineStartedAt(r.spine) };
+  }
+  return null;
+}
+
+/**
+ * The newest green version across a bundle's bridges (by `greenAt`), with the history row of the same run (it
+ * carries whether the spend figure is complete). A malformed bridge or version is skipped.
+ * @param {any[]} bridges
+ * @returns {{bridge: any, version: any, historyRow: any|null}|null}
+ */
+export function latestBridgeGreen(bridges) {
+  /** @type {{bridge: any, version: any, at: number}|null} */
+  let best = null;
+  for (const b of Array.isArray(bridges) ? bridges : []) {
+    if (!b || typeof b !== 'object' || !Array.isArray(b.versions)) continue;
+    for (const v of b.versions) {
+      if (!v || typeof v !== 'object' || typeof v.greenAt !== 'string') continue;
+      const at = Date.parse(v.greenAt);
+      if (!Number.isFinite(at)) continue;
+      if (!best || at > best.at) best = { bridge: b, version: v, at };
+    }
+  }
+  if (!best) return null;
+  const hist = Array.isArray(best.bridge.history) ? best.bridge.history : [];
+  const historyRow = typeof best.version.runid === 'string'
+    ? (hist.find((/** @type {any} */ h) => h && h.runid === best.version.runid && h.outcome === 'green') ?? null) : null;
+  return { bridge: best.bridge, version: best.version, historyRow };
+}
+
+/** @param {unknown} v @returns {number|null} */
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null);
+/** @param {unknown} v @returns {string[]} */
+const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x.length > 0).slice(0, 100) : []);
+
+/**
+ * The run detail of the bridge's green version, in the SAME shape `getRunDetail` returns (so the page's one run
+ * renderer paints it), plus `fromBridge: true`. Only what the bridge carries is filled; every other field is null
+ * ("not recorded" on the page), never 0: no tool counts, no cache, no per-step figures, no close stages' numbers.
+ * @param {{bridge: any, version: any, historyRow: any|null}} g
+ * @param {{job: string, checkType: string, checkTypeTitle: string|null, model: string|null, budgetUsd: number|null}} facts
+ * @returns {any}
+ */
+export function bridgeRunDetail(g, facts) {
+  const v = g.version;
+  const steps = Array.isArray(v.plan?.steps) ? v.plan.steps.filter((/** @type {any} */ s) => s && typeof s.id === 'string').slice(0, 200) : [];
+  const parts = steps.map((/** @type {any} */ s) => ({
+    kind: 'step', label: s.id, occurrence: 1, tryNumber: 1, continued: false, resumedNext: false, outcome: null, stopReason: null,
+    attempts: [], blocked: 0, rounds: null, toolCalls: null, wallMs: null, spentUsd: null, unpricedRounds: 0, byTool: null,
+  }));
+  const stageNames = strs(g.bridge.closeStageNames);
+  return {
+    fromBridge: true,
+    runid: typeof v.runid === 'string' ? v.runid : null,
+    job: facts.job,
+    goal: null,
+    checkType: facts.checkType,
+    checkTypeTitle: facts.checkTypeTitle,
+    model: facts.model,
+    provider: null,
+    judgeModel: null,
+    budgetUsd: facts.budgetUsd,
+    glyph: '✓',
+    status: statusFor({ outcome: 'green' }),
+    outcome: 'green',
+    died: false,
+    stopReason: 'not recorded',
+    ended: null,
+    live: false,
+    stopping: false,
+    legs: [],
+    legDividers: [],
+    resumedCount: 0,
+    resume: null,
+    spentUsd: num(v.costUsd),
+    spendComplete: g.historyRow ? g.historyRow.spendComplete === true : null,
+    draftSpentUsd: null,
+    draftSpendComplete: null,
+    spendFloorUsd: null,
+    wallFloorMs: null,
+    wallMs: num(v.wallMs),
+    rounds: num(v.rounds),
+    timelineKind: 'plan',
+    steps: parts.map((/** @type {any} */ p) => ({
+      id: p.label, occurrence: 1, outcome: null, state: 'done', rounds: null, toolCalls: null, wallMs: null, spentUsd: null,
+      unpricedRounds: 0, checks: null, treeChanged: null, tripped: null, attempts: [],
+    })),
+    scoutPlan: null,
+    fixLoop: null,
+    parts,
+    replans: null,
+    close: stageNames.length > 0 ? { verdict: `satisfied — ${stageNames.join(' · ')}` } : null,
+    branch: null,
+    date: typeof v.greenAt === 'string' ? v.greenAt.slice(0, 10) : null,
+    at: v.greenAt,
+    via: 'import',
+    behaviour: null,
+    memoryCache: null,
+    toolsUsed: strs(g.bridge.toolsUsed),
+  };
+}