create-pmos 0.132.0 → 0.133.0

package/workspace/lib/vendor/workspace/lib/actor.js

@@ -0,0 +1,91 @@
+'use strict';
+/* actor.js — who a write is, read from the CALL PATH, never from a field (pm-os-absorb, PRD R23 and R25).
+ *
+ *   fromUi()              → { by: 'pm:wawan', via: 'ui' }      the page, after the route's own checks
+ *   fromCli({isTTY, env}) → { by, via: 'cli' }                 a bound agent session, else a terminal (the PM), else unknown
+ *   isPm(actor) · isAgent(actor) · sessionOf(actor)
+ *   pageName(by)          → 'agent:sess-<n>' for 'agent:sess-<n>.<8hex>', else `by` unchanged
+ *
+ * F5: a ledger line's `by` carries the session token; the page must never see it. Every GET route and every needs
+ * provider maps each `by` it answers through pageName (proposals, moves, item owners, report attributions).
+ *
+ * The placements, measurements and issues writers take their actor from here, so the four ledgers attribute one way.
+ * A caller never passes `by` or `via`: a writer that accepted them would make attribution something a caller chooses.
+ *
+ * THE SESSION-TOKEN MAP (Run 2, slice 2A). server.js gives each agent session a token, `sess-<n>.<8 hex>`, in its PTY
+ * environment as PMOS_SESSION. The token itself is never written to disk or sent to the page (D08, F5). server.js
+ * persists its SHA-256 (`tokenHash`) in the session's own meta file, so after a restart the map still answers which
+ * session a token belongs to and which initiative that session is bound to. The map is read from the files each time
+ * (no cache, D33), so a CLI with no server reads the same answer as the server.
+ *
+ *   tokenHash(token)                       → 64 hex characters, or null for a value that is not a token
+ *   sessionForToken(token, { sessDir })    → { session, initiative } | null
+ *
+ * HONEST LIMIT. A token is an attribution, not a credential: a process that unsets PMOS_SESSION is no longer an agent
+ * to fromCli. pm-guard.js requirePmCli asks such a caller to type the id of a PM-only act (X12); CI detection is the
+ * backstop for the rest.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const PM_SLUG = 'wawan';
+const SESSION_RE = /^sess-\d+\.[0-9a-f]{8}$/;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+const VIA = ['ui', 'cli'];
+
+const PM = Object.freeze({ by: `pm:${PM_SLUG}`, via: 'ui' });
+
+/** The page. Call it only after the route has run its checks (pm-guard.js requirePmPress for a PM-only act). */
+function fromUi() { return { by: PM.by, via: 'ui' }; }
+
+/**
+ * A `pmos <verb>` call. A bound agent session FIRST, by its token: an agent that runs its commands in a PTY (or wraps
+ * them with `script`) still has a terminal, and a terminal must not turn its writes into the PM's. Only agent sessions
+ * get PMOS_SESSION (server.js spawnSession), so the PM's own shell is a terminal with no token: the PM. Else unknown.
+ */
+function fromCli({ isTTY = !!(process.stdin.isTTY && process.stdout.isTTY), env = process.env } = {}) {
+  const tok = env && env.PMOS_SESSION;
+  if (typeof tok === 'string' && SESSION_RE.test(tok)) return { by: `agent:${tok}`, via: 'cli' };
+  if (isTTY) return { by: `pm:${PM_SLUG}`, via: 'cli' };
+  return { by: 'agent:unknown', via: 'cli' };
+}
+
+const valid = (a) => !!a && typeof a.by === 'string' && BY_RE.test(a.by) && VIA.includes(a.via);
+const isPm = (a) => valid(a) && a.by.startsWith('pm:');
+const isAgent = (a) => valid(a) && a.by.startsWith('agent:');
+/** The session token of an agent actor, or null. */
+const sessionOf = (a) => (isAgent(a) && a.by !== 'agent:unknown' ? a.by.slice('agent:'.length) : null);
+
+/** The name the page may show. Strips the session token's secret suffix; anything else passes through. */
+function pageName(by) {
+  if (typeof by !== 'string') return by;
+  const m = /^(agent:sess-\d+)\.[0-9a-f]{8}$/.exec(by);
+  return m ? m[1] : by;
+}
+
+/** The SHA-256 of a session token. The map stores this, never the token. */
+function tokenHash(token) {
+  if (typeof token !== 'string' || !SESSION_RE.test(token)) return null;
+  return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+/**
+ * The session a token belongs to, read from the session meta files server.js persists (`<sessDir>/<id>.json`). The id
+ * part of the token names the file, and the stored hash must match: a token with the right id and a wrong suffix is not
+ * that session. Null when there is no such session or no hash on record. `plan_item` is the item Hand to agent gave the
+ * session (null for any other session).
+ */
+function sessionForToken(token, { sessDir } = {}) {
+  const h = tokenHash(token);
+  if (!h || typeof sessDir !== 'string' || !sessDir) return null;
+  const id = token.slice(0, token.indexOf('.'));
+  let meta;
+  try { meta = JSON.parse(fs.readFileSync(path.join(sessDir, id + '.json'), 'utf8')); } catch { return null; }
+  if (!meta || meta.id !== id || typeof meta.tokenHash !== 'string' || meta.tokenHash.length !== h.length) return null;
+  if (!crypto.timingSafeEqual(Buffer.from(meta.tokenHash), Buffer.from(h))) return null;
+  const str = (v) => (typeof v === 'string' && v ? v : null);
+  return { session: id, initiative: str(meta.initiative), plan_item: str(meta.plan_item) };
+}
+
+module.exports = { tokenHash, sessionForToken, PM_SLUG, SESSION_RE, BY_RE, VIA, fromUi, fromCli, valid, isPm, isAgent, sessionOf, pageName };

package/workspace/lib/vendor/workspace/lib/board-cache.js

@@ -0,0 +1,156 @@
+'use strict';
+/*
+ * board-cache.js — the workflow board, cached and derived OFF the event loop.
+ *
+ * WHY THIS EXISTS. `console-state.workflow()` runs `scripts/workflow-state.js` over every
+ * initiative record, and the engine resolves each artifact's FIRST APPEARANCE by shelling `git`.
+ * Measured on the PMOS repo, 2026-07-29: ~260 ms per initiative × 109 records = **~30 seconds**, and
+ * every millisecond of it is SYNCHRONOUS. Today that cost is paid only when the PM opens the
+ * `workflow` lens, where it freezes the server — and with it every PTY WebSocket — for half a minute.
+ *
+ * PRD R4 puts the same board behind EVERY sidebar row, so an uncached in-process derivation would
+ * turn a 30-second freeze into a freeze on every render. Two rules follow, and they are the whole
+ * design:
+ *
+ *   1. NEVER derive on the request path. A miss spawns a CHILD PROCESS and returns immediately.
+ *      The event loop is never blocked, however cold the cache is.
+ *   2. NEVER serve a stale board as if it were fresh. Every hit carries `as_of` and `stale`, and a
+ *      cold cache returns `pending: true` rather than an empty board. A surface that cannot say how
+ *      old its answer is has no business showing a stage — that is R5's rule applied to time
+ *      instead of to branch.
+ *
+ * The signature is HEAD + the initiative records' own mtimes, so editing a record refreshes the
+ * board without a commit, and switching branch refreshes it without an edit.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync, spawn } = require('child_process');
+
+const MAX_AGE_MS = 10 * 60 * 1000;   // a board older than this is refreshed even if the signature holds
+const REFRESH_TIMEOUT_MS = 120000;   // a derivation that cannot finish in 2 minutes is reported, not awaited
+
+const cache = new Map();             // root -> { sig, at, value, error }
+const inflight = new Map();          // root -> true
+
+// headSha runs on every signature, and the needs poll asks for a signature per registered tree several times per
+// request, so a `git rev-parse` each time held the server for seconds with twenty trees registered. The answer is
+// kept per root while the files a commit, checkout or reset touches (HEAD, its ref, packed-refs, the HEAD reflog)
+// are unchanged; anything unreadable falls back to asking git.
+const headMemo = new Map();          // root -> { key, sha }
+function gitDirOf(root) {
+  const dotgit = path.join(root, '.git');
+  const st = fs.statSync(dotgit);
+  if (st.isDirectory()) return { dir: dotgit, common: dotgit };
+  const m = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(dotgit, 'utf8'));
+  if (!m) throw new Error('no gitdir');
+  const dir = path.resolve(root, m[1].trim());
+  let common = dir;
+  try { common = path.resolve(dir, fs.readFileSync(path.join(dir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
+  return { dir, common };
+}
+function headKey(root) {
+  const { dir, common } = gitDirOf(root);
+  const head = fs.readFileSync(path.join(dir, 'HEAD'), 'utf8').trim();
+  const stat = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}:${st.ino}`; } catch { return '-'; } };
+  const ref = /^ref:\s*(.+)$/.exec(head);
+  return [head, ref ? stat(path.join(common, ref[1])) : '', stat(path.join(common, 'packed-refs')), stat(path.join(dir, 'logs', 'HEAD'))].join('|');
+}
+function headSha(root) {
+  let key = null;
+  try { key = headKey(root); } catch { key = null; }
+  const hit = headMemo.get(root);
+  if (key && hit && hit.key === key) return hit.sha;
+  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 });
+  const sha = r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
+  if (key) headMemo.set(root, { key, sha });
+  return sha;
+}
+
+// The records' own state, so an UNCOMMITTED edit still invalidates. Cheap: one readdir + one stat
+// per record, no git, no file contents.
+function recordsSig(root) {
+  // Both layouts (pmos-self `planning/`, a PM repository's `pmos/state/`), and the ledgers the
+  // board's rows depend on: an uncommitted lifecycle or acceptance line must not wait out the TTL (D70).
+  // pm-os-absorb: plan-items.jsonl (Run 4's Build rule reads items) and issues.jsonl (Run 5's report lane reads issues).
+  const dirs = [path.join(root, 'planning', 'initiatives'), path.join(root, 'pmos', 'state', 'initiatives')];
+  const ledgers = ['lifecycle.jsonl', 'acceptances.jsonl', 'plan-items.jsonl', 'issues.jsonl'].flatMap((f) => [
+    path.join(root, 'planning', 'runs', f), path.join(root, 'pmos', 'state', f)]);
+  let total = 0; let newest = 0; let any = false;
+  for (const dir of dirs) {
+    let names = [];
+    try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort(); } catch { continue; }
+    any = true; total += names.length;
+    for (const n of names) {
+      try { const st = fs.statSync(path.join(dir, n)); if (st.mtimeMs > newest) newest = st.mtimeMs; }
+      catch { /* a record that vanished mid-scan just does not raise the watermark */ }
+    }
+  }
+  if (!any) return 'none';
+  let led = 0;
+  for (const f of ledgers) { try { const st = fs.statSync(f); led = Math.max(led, Math.round(st.mtimeMs)) + st.size; } catch { /* absent */ } }
+  return `${total}:${Math.round(newest)}:${led}`;
+}
+
+function signature(root) { return `${headSha(root)}|${recordsSig(root)}`; }
+
+// The child runs the SAME reader the lens uses — no second implementation of the board to drift.
+function refresh(root, sig) {
+  if (inflight.get(root)) return;
+  inflight.set(root, true);
+  const script = `
+    const cs = require(${JSON.stringify(path.join(__dirname, 'console-state.js'))});
+    process.stdout.write(JSON.stringify(cs.workflow({ root: ${JSON.stringify(root)} })));
+  `;
+  let out = '';
+  let child;
+  try { child = spawn(process.execPath, ['-e', script], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }); }
+  catch (e) {
+    inflight.delete(root);
+    cache.set(root, { sig, at: Date.now(), value: null, error: 'could not start the board derivation: ' + (e.code || e.message) });
+    return;
+  }
+  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, REFRESH_TIMEOUT_MS);
+  if (timer.unref) timer.unref();
+  child.stdout.on('data', (c) => { out += c; });
+  child.on('error', (e) => {
+    clearTimeout(timer); inflight.delete(root);
+    cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation failed to run: ' + (e.code || e.message) });
+  });
+  child.on('close', (code, signal) => {
+    clearTimeout(timer); inflight.delete(root);
+    if (signal === 'SIGKILL') {
+      cache.set(root, { sig, at: Date.now(), value: null, error: `the board took longer than ${Math.round(REFRESH_TIMEOUT_MS / 1000)}s to derive and was stopped` });
+      return;
+    }
+    if (code !== 0 || !out) {
+      cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation exited without a result' });
+      return;
+    }
+    try { cache.set(root, { sig, at: Date.now(), value: JSON.parse(out), error: null }); }
+    catch { cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation returned unreadable output' }); }
+  });
+}
+
+/*
+ * The read the request path uses. Always returns immediately.
+ *   { pending: true }                       nothing cached yet; a derivation was started
+ *   { ok:false, error, as_of, stale }       the derivation failed — render RED, never a calm empty
+ *   { ...workflowPayload, as_of, stale }    a board; `stale` means a refresh is running behind it
+ */
+function board(root, { refreshNow = false } = {}) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow board', as_of: null, stale: false };
+  let sig;
+  try { sig = signature(root); } catch { sig = 'unreadable'; }
+  const hit = cache.get(root);
+  const fresh = hit && hit.sig === sig && (Date.now() - hit.at) < MAX_AGE_MS;
+  if (!fresh || refreshNow) refresh(root, sig);
+  if (!hit) return { pending: true, refreshing: true, as_of: null, stale: false };
+  const envelope = { as_of: new Date(hit.at).toISOString(), stale: !fresh, refreshing: !!inflight.get(root) };
+  if (hit.error) return { ok: false, error: hit.error, ...envelope };
+  return { ...hit.value, ...envelope };
+}
+
+// Test/maintenance seam: drop everything, or one root.
+function invalidate(root) { if (root) { cache.delete(root); inflight.delete(root); } else { cache.clear(); inflight.clear(); } }
+
+module.exports = { board, invalidate, signature, MAX_AGE_MS, REFRESH_TIMEOUT_MS };

package/workspace/lib/vendor/workspace/lib/console-state.js

@@ -0,0 +1,295 @@
+'use strict';
+/*
+ * Read-only console state readers (D64 / pivot-workspace-first, Track B).
+ *
+ * The workspace console surfaces — the "needs you" queue, a radar-style health summary, and a
+ * metrics view — derive ONLY from local file-mode state: the kit's `pmos/state/*.jsonl` and, as a
+ * seed/demo source when no live state exists yet, the committed hosted snapshot under
+ * `planning/data-export/<date>-hosted-snapshot/*.json`. Live file-mode state is ALWAYS preferred.
+ *
+ * HONESTY BY CONSTRUCTION (the anti-watermelon rule): every reader returns a discriminated result —
+ *   { ok:true,  empty:false, source, data }   data present
+ *   { ok:true,  empty:true,  source }          genuinely nothing (calm empty state on the client)
+ *   { ok:false, error }                        a missing source / parse failure — the client MUST
+ *                                              render this RED, never a green "all clear".
+ * A missing DATA source (no live file AND no snapshot) is an ERROR, not an empty — a health surface
+ * that cannot read its inputs is broken, and a broken honesty surface must read red.
+ */
+const fs = require('fs');
+const path = require('path');
+const reviewGate = require('./review-gate');
+const gitInfo = require('./git-info');       // R5: the ladder is branch-scoped — name the branch it came from
+
+function loadJson(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { missing: true }; }
+  try { return { ok: true, data: JSON.parse(text) }; }
+  catch { return { ok: false, error: `${path.basename(file)} is not valid JSON — the file-mode source is corrupt, not empty` }; }
+}
+function loadJsonl(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { missing: true }; }
+  const rows = []; let bad = 0;
+  for (const line of text.split('\n')) {
+    const t = line.trim(); if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch { bad++; }
+  }
+  // A file that is entirely unparseable is corrupt state — surface it red rather than call it empty.
+  if (bad > 0 && rows.length === 0) return { ok: false, error: `every line in ${path.basename(file)} is malformed — corrupt file-mode state` };
+  return { ok: true, data: rows, bad };
+}
+
+function computeMetricsFromRuns(runs) {
+  const corr = runs.map((r) => Number(r.human_corrections) || 0);
+  const total = corr.reduce((a, b) => a + b, 0);
+  const needing = corr.filter((c) => c > 0).length;
+  const n = runs.length;
+  return {
+    total_runs: n,
+    avg_corrections_per_run: n ? +(total / n).toFixed(3) : 0,
+    runs_needing_correction: needing,
+    share_runs_corrected: n ? +(needing / n).toFixed(3) : 0,
+    per_initiative: [],
+  };
+}
+
+// ── metrics: prefer live pmos/state/runs.jsonl; fall back to the snapshot's metrics.json ──
+function metrics({ stateDir, snapshotDir }) {
+  if (stateDir) {
+    const live = loadJsonl(path.join(stateDir, 'runs.jsonl'));
+    if (live.ok) {
+      if (!live.data.length) return { ok: true, empty: true, source: 'file-mode' };
+      return { ok: true, empty: false, source: 'file-mode', data: computeMetricsFromRuns(live.data) };
+    }
+    if (live.ok === false) return { ok: false, error: live.error };
+    // live.missing → fall through to the snapshot
+  }
+  if (!snapshotDir) return { ok: false, error: 'no metrics source — no live runs.jsonl and no hosted snapshot for this workspace' };
+  const snap = loadJson(path.join(snapshotDir, 'metrics.json'));
+  if (snap.missing) return { ok: false, error: 'metrics source missing — neither live runs.jsonl nor the hosted snapshot is present' };
+  if (!snap.ok) return { ok: false, error: snap.error };
+  const m = snap.data || {};
+  return { ok: true, empty: false, source: 'snapshot', data: {
+    total_runs: m.total_runs, avg_corrections_per_run: m.avg_corrections_per_run,
+    runs_needing_correction: m.runs_needing_correction, share_runs_corrected: m.share_runs_corrected,
+    per_initiative: Array.isArray(m.per_initiative) ? m.per_initiative.slice(0, 12) : [],
+  } };
+}
+
+// ── radar: prefer a live pmos/state/radar.json; fall back to the snapshot's radar_all_sections.json ──
+function radar({ stateDir, snapshotDir }) {
+  let src = null, source = null;
+  if (stateDir) {
+    const live = loadJson(path.join(stateDir, 'radar.json'));
+    if (live.ok) { src = live.data; source = 'file-mode'; }
+    else if (live.ok === false) return { ok: false, error: live.error };
+  }
+  if (!src) {
+    if (!snapshotDir) return { ok: false, error: 'no radar source — no live radar.json and no hosted snapshot for this workspace' };
+    const snap = loadJson(path.join(snapshotDir, 'radar_all_sections.json'));
+    if (snap.missing) return { ok: false, error: 'radar source missing — neither live radar.json nor the hosted snapshot is present' };
+    if (!snap.ok) return { ok: false, error: snap.error };
+    src = snap.data; source = 'snapshot';
+  }
+  const d = src || {};
+  const gates = Array.isArray(d.eval_gates) ? d.eval_gates : [];
+  const passing = gates.filter((g) => reviewGate.isReviewPass(g.verdict, g.score)).length;
+  const wms = (Array.isArray(d.watermelons) ? d.watermelons : []).map((w) => ({
+    id: w.id, title: w.title, rag: w.rag,
+    verdict: w.latest_eval_verdict, score: w.latest_eval_score, corrections: w.avg_human_corrections,
+  }));
+  const calRaw = Array.isArray(d.calibration) ? d.calibration[0] : d.calibration;
+  const calibration = calRaw ? {
+    n: calRaw.n, kappa: calRaw.kappa, tnr: calRaw.tnr, status: calRaw.status,
+    meets_d40: !!calRaw.meets_d40_kappa, caveat: calRaw.leakage_caveat || null,
+  } : null;
+  const okr = (Array.isArray(d.okr_pulse) ? d.okr_pulse : []).slice(0, 8).map((o) => ({
+    objective: o.objective, kr: o.kr, progress: o.progress_pct, pulse: o.pulse,
+  }));
+  return { ok: true, empty: false, source, data: {
+    // watermelon flags = anything not green (amber/red) leads; the whole point is to surface drift
+    watermelons: wms,
+    flags: wms.filter((w) => w.rag && String(w.rag).toLowerCase() !== 'green').length,
+    eval_gate: { total: gates.length, passing, pass_rate: gates.length ? +(passing / gates.length).toFixed(3) : null },
+    calibration, okr_pulse: okr,
+  } };
+}
+
+/*
+ * ── workflow: where each initiative is, what is next, what is blocking ────────────────────────
+ *
+ * The one surface that answers "where am I in the loop" without the PM reconstructing it from
+ * files. It renders the SAME ladder the CLI and the Initiative Gate print, from the same engine —
+ * `scripts/workflow-state.js` — so the panel can never disagree with what CI is about to say.
+ *
+ * The engine is the one BUNDLED WITH THE WORKSPACE, pointed at the opened repo via its `root`
+ * option. It is deliberately not `require`d out of the opened directory: the engine only reads
+ * files and runs `git -C <root> log`, so no code from a workspace the PM merely opened is ever
+ * executed. An install that does not carry the engine gets an honest error, never a blank panel.
+ *
+ * WHERE THE ENGINE ACTUALLY LIVES — the defect this list exists to close (incident
+ * kit-workflow-engine-missing). "Bundled with the workspace" was the INTENT above; packaging never
+ * implemented it. `npm-pkg/package.json` ships only bin/ payload/ workspace/, so in a published
+ * install there is no repo two levels up and `../../scripts/workflow-state.js` resolves to nothing.
+ * Every adopter row read "ladder unreadable" from 0.11.0 back to whenever this surface shipped —
+ * the ladder had never once run outside a PMOS checkout. Two locations, tried in order:
+ *
+ *   1. `../../scripts/workflow-state.js` — a repo checkout (PMOS-self, any dev clone). Preferred on
+ *      purpose: it is the very file `.github/scripts/initiative-gate.sh` executes, so a developer's
+ *      panel can never disagree with what CI is about to print on their PR.
+ *   2. `lib/engine/workflow-state.js` — the copy the publish step vendors into the bundle. This is
+ *      what an adopter runs, and the only reason the ladder derives at all outside this repo.
+ *
+ * ABSENT and BROKEN are answered differently, because they are different facts (R10). A path that
+ * does not exist means "try the next one"; a path that exists and throws is a real fault in an
+ * engine that IS installed, and reporting that as "not present" would send the PM looking for a
+ * packaging bug they do not have.
+ */
+const ENGINE_PATHS = [
+  path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js'),
+  path.join(__dirname, 'engine', 'workflow-state.js'),
+];
+function loadEngine() {
+  const tried = [];
+  for (const p of ENGINE_PATHS) {
+    if (!fs.existsSync(p)) { tried.push(p); continue; }
+    try { return { ok: true, engine: require(p), from: p }; }
+    catch (e) {
+      return { ok: false, error: `the workflow engine at ${p} is installed but failed to load — ${String((e && e.message) || e).slice(0, 160)}` };
+    }
+  }
+  return { ok: false, error: `the workflow engine is not present in this install — the ladder cannot be derived here (looked in: ${tried.join(', ')})` };
+}
+function workflow({ root }) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow surface' };
+  const loaded = loadEngine();
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const engine = loaded.engine;
+  let ids;
+  try { ids = engine.listInitiatives(root); }
+  catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
+  if (!ids.length) return { ok: true, empty: true, source: 'file-mode' };
+
+  /*
+   * THE TRUNK, not the pull request (workflow-status-sweep R-3).
+   *
+   * This used to be `engine.commitRange(root)` — merge-base(origin/main, HEAD)..HEAD — and the trap
+   * is documented three lines below in words that were written and then not acted on: on `main`, or
+   * on a branch level with it, that range is EMPTY with `range.ok === true`. Nothing reads as
+   * degraded, every `build` rung legitimately reports `pending`, and the four-panel fold rolls
+   * BUILD/EVAL/ACCEPTED to 0/3 for every initiative in the repository — including ones that shipped
+   * months ago. The PM opens the panel to ask what is delivered and is told nothing is.
+   *
+   * So the panel asks the question the CLI board already asks — "where does this initiative stand?",
+   * which only the trunk can answer — and passes the PR range alongside as `changeRange`, which is
+   * what `● in this change` means and the one thing the trunk range genuinely cannot answer. Same
+   * split, same reasons, stated in `historyRange`'s own header. The `build` rung is attributed per
+   * initiative now (R-2), so a trunk-wide range no longer means a trunk-wide answer.
+   */
+  const range = engine.historyRange(root);
+  const changeRange = engine.commitRange(root);
+  // ONE delivery index for the board, built once and shared, exactly as the CLI board does.
+  let deliveryIndex = null;
+  try { deliveryIndex = require(path.join(path.dirname(loaded.from), 'delivery-index.js')).deliveryIndex(root, ids, { recordsDir: engine.layout(root).initiatives }); }
+  catch { deliveryIndex = null; }   // absent → each ladder builds its own; the engine handles it
+  const bi = gitInfo.branchInfo(root);
+  const scope = {
+    branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
+    branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
+    commits: range.ok ? range.shas.length : null,
+    whole_history: range.ok ? !!range.wholeHistory : null,
+    // Kept, and now describing `changeRange` rather than the derivation range. It is no longer the
+    // trap it names — the derivation cannot land in it — but a consumer that wants to say "nothing
+    // in this branch touches these initiatives" still needs the fact, and deleting a field because
+    // the bug it documented was fixed is how the next reader loses the reason.
+    empty_range: changeRange.ok ? changeRange.shas.length === 0 : null,
+    change_commits: changeRange.ok ? changeRange.shas.length : null,
+  };
+  const rows = ids.map((id) => {
+    try { return engine.computeWorkflow(id, { root, range, changeRange, deliveryIndex }); }
+    catch (e) { return { ok: false, id, error: String((e && e.message) || 'derivation failed').slice(0, 160) }; }
+  });
+  // Same `inFlight` the CLI and the gate use — the panel must not invent its own idea of what is
+  // open. Filtering by `legacy` here was a real bug: on main every record is legacy, so the panel
+  // read "0 in flight" against 93 initiatives, blank at exactly the moment someone opens it.
+  const { shown, hidden, total } = engine.inFlight(rows);
+  const shape = (r) => (r.ok ? {
+    id: r.id, title: r.title, lane: r.lane, stage: r.stage, legacy: r.legacy,
+    in_change: r.in_change, anchor: r.anchor,
+    record: r.record, blockers: r.blockers, next: r.next,
+    steps: r.steps.map((s) => ({ key: s.key, status: s.status, evidence: s.evidence, next: s.next, blocking: s.blocking, rule: s.rule })),
+  } : { id: r.id, error: r.error });
+  return {
+    ok: true, empty: false, source: 'file-mode',
+    data: {
+      live: shown.map(shape),
+      hidden,                       // reported on the client — a silent cap reads as "that is all"
+      total,
+      accepted: rows.filter((r) => r.ok && r.accepted).length,
+      // D70 — stopped initiatives are off the board and not gating, but listed, never dropped silently.
+      stopped: rows.filter((r) => r.ok && r.stopped).map((r) => ({ id: r.id, title: r.title, state: r.stopped.state, reason: r.stopped.reason, at: r.stopped.at, pm: r.stopped.pm })),
+      unreadable: rows.filter((r) => !r.ok).map(shape),
+      blocked: shown.filter((r) => r.ok && r.blockers.length).length,
+      degraded: range.ok ? null : range.reason,
+      scope,                        // R5 — the branch this ladder was derived from; never omit it
+      enforced_from: engine.ENFORCED_FROM,
+    },
+  };
+}
+
+// ENGINE_PATHS/loadEngine are exported for the packaging guard in workspace/test.js: the incident
+// that made them a list was invisible to every unit test precisely because resolution was inline.
+/* ONE initiative's ladder, derived on demand.
+ *
+ * WHY THIS IS SEPARATE FROM `workflow`. The board caps what it returns (`inFlight`) and reports the
+ * remainder as `hidden` — 12 shown against 93 hidden in this repository. That cap is right for a
+ * board, which is a list of what is in flight. It is wrong for a PANEL, which is asked about one
+ * initiative the PM picked by name: reading the capped list and finding nothing there means "not in
+ * the top twelve", and a panel that renders that as "no initiative record" states something false
+ * about 93 of 105 records. This derives the one that was asked for, so the answer is about the
+ * initiative rather than about its rank.
+ *
+ * It is safe on the request path for the same reason the board is not: this shells git once for the
+ * commit range and runs the engine ONCE, rather than 105 times. `workflow` still owns the board.
+ */
+function ladder({ root, id }) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the ladder' };
+  if (!id) return { ok: false, error: 'no initiative id given' };
+  const loaded = loadEngine();
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const engine = loaded.engine;
+  // ABSENT and BROKEN are different facts and must not share an answer. The engine returns
+  // `ok:false` for BOTH "there is no record with this id" and "the record is there and unreadable",
+  // and collapsing them makes the panel paint a red "read failed" over an initiative that simply
+  // does not exist — overstating a missing file as a fault. The initiative list is the arbiter:
+  // an id the repository does not know is an empty read, and only an id it DOES know can fail one.
+  let known = null;
+  try { known = engine.listInitiatives(root); } catch { known = null; }
+  if (Array.isArray(known) && !known.includes(id)) return { ok: true, empty: true, row: null };
+  // The trunk, for the reason `workflow` above states at length: this is asked about ONE initiative
+  // the PM named, and "where does it stand" is a question the pull-request range cannot answer — on
+  // main it is empty, so the panel reported `BUILD 0/3` on delivered work (R-3).
+  let range, changeRange, row;
+  try { range = engine.historyRange(root); }
+  catch (e) { return { ok: false, error: 'could not resolve the commit range: ' + String((e && e.message) || 'error').slice(0, 120) }; }
+  try { changeRange = engine.commitRange(root); } catch { changeRange = { ok: false }; }
+  try { row = engine.computeWorkflow(id, { root, range, changeRange }); }
+  catch (e) { return { ok: false, error: `could not derive the ladder for ${id}: ` + String((e && e.message) || 'error').slice(0, 160) }; }
+  if (row && row.ok === false) return { ok: false, error: row.error || `the record for ${id} could not be read` };
+  const bi = gitInfo.branchInfo(root);
+  return {
+    ok: true,
+    empty: !row,                        // no such record — distinct from a read that failed
+    row: row || null,
+    scope: {
+      branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
+      branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
+      commits: range.ok ? range.shas.length : null,
+      whole_history: range.ok ? !!range.wholeHistory : null,
+      empty_range: changeRange.ok ? changeRange.shas.length === 0 : null,
+      change_commits: changeRange.ok ? changeRange.shas.length : null,
+    },
+  };
+}
+
+module.exports = { metrics, radar, workflow, ladder, computeMetricsFromRuns, loadJson, loadJsonl, ENGINE_PATHS, loadEngine };