@haystackeditor/cli 0.15.30 → 0.16.0

package/dist/commands/verify-core.js

@@ -1,789 +0,0 @@
-// Shared plumbing for the cloud-verifier operator surface: `haystack verify
-// status|watch|list|show|artifacts` and the `haystack verify mcp` tools.
-//
-// Run state lives in two places with different strengths. The control plane
-// (Vite middleware) resolves aliases and knows whether the orchestrator that
-// owns a run is still alive — a run.json can sit at `running` forever after a
-// dev-server restart, and only the server reports that honestly. Disk
-// (.haystack/verify/runs/<runId>/run.json) survives the server being down and
-// is the only way to enumerate runs. So: server first, disk fallback, and a
-// disk-read of a non-terminal run is reported as stale rather than live.
-//
-// Types here are a hand-maintained mirror of src/features/cloud-verifier/types.ts
-// (the CLI ships standalone and cannot import the web app's sources), same as
-// the SPECIMENS list in verify.ts.
-import { createHash } from 'node:crypto';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-export const DEFAULT_CONTROL_PLANE = 'http://127.0.0.1:3000';
-export const TERMINAL_RUN_STATUSES = new Set(['complete', 'failed']);
-// ---------- locating things ----------
-export function resolveServer(explicit) {
-    return (explicit || process.env.HAYSTACK_VERIFY_SERVER || DEFAULT_CONTROL_PLANE).replace(/\/+$/, '');
-}
-// ---------- auth ----------
-//
-// The demo control plane is open on localhost; a shared or cloud control plane
-// sets HAYSTACK_VERIFY_AUTH_TOKEN and rejects unauthenticated requests. The
-// client sends its token (--token / HAYSTACK_VERIFY_TOKEN) as a Bearer header
-// on every control-plane request. The token is only ever sent to the server
-// the operator explicitly chose — never inferred from product login state.
-let explicitVerifyToken = null;
-export function setVerifyToken(token) {
-    explicitVerifyToken = token || null;
-}
-export function verifyAuthHeaders() {
-    const token = explicitVerifyToken ?? process.env.HAYSTACK_VERIFY_TOKEN ?? null;
-    return token ? { authorization: `Bearer ${token}` } : {};
-}
-export class VerifyUnauthorizedError extends Error {
-    constructor(server) {
-        super(`Control plane at ${server} requires a token (HTTP 401). Pass --token or set HAYSTACK_VERIFY_TOKEN to the value of the server's HAYSTACK_VERIFY_AUTH_TOKEN.`);
-    }
-}
-/**
- * Find the repository that holds .haystack/verify — explicit flag, then
- * HAYSTACK_VERIFY_REPO, then walking up from cwd. Null when nothing matches;
- * server-backed commands still work without it.
- */
-export function discoverVerifyRoot(explicit) {
-    const candidates = [explicit, process.env.HAYSTACK_VERIFY_REPO].filter((v) => Boolean(v));
-    for (const candidate of candidates) {
-        const resolved = path.resolve(candidate);
-        if (fs.existsSync(path.join(resolved, '.haystack', 'verify')))
-            return resolved;
-        // A configured root is an instruction, not a hint: report it unusable
-        // rather than silently walking somewhere else.
-        throw new Error(`${resolved} has no .haystack/verify directory`);
-    }
-    let dir = process.cwd();
-    for (;;) {
-        if (fs.existsSync(path.join(dir, '.haystack', 'verify')))
-            return dir;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
-}
-export function runsRoot(repoRoot) {
-    return path.join(repoRoot, '.haystack', 'verify', 'runs');
-}
-export function runDir(repoRoot, runId) {
-    return path.join(runsRoot(repoRoot), runId);
-}
-function isMissingFileError(error) {
-    return typeof error === 'object'
-        && error !== null
-        && 'code' in error
-        && error.code === 'ENOENT';
-}
-function runRecordReadError(runJsonPath, error) {
-    return new Error(`Could not read verifier run record ${runJsonPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-}
-/**
- * Read when a run began from the record itself. updatedAt and mtime both move
- * when cleanup or a migration rewrites old runs and therefore cannot define
- * "latest".
- */
-export function runStartedAtMs(runJsonPath) {
-    try {
-        const run = JSON.parse(fs.readFileSync(runJsonPath, 'utf8'));
-        if (typeof run.createdAt === 'string') {
-            const recorded = Date.parse(run.createdAt);
-            if (Number.isFinite(recorded))
-                return recorded;
-        }
-    }
-    catch (error) {
-        if (isMissingFileError(error))
-            return null;
-        throw runRecordReadError(runJsonPath, error);
-    }
-    return null;
-}
-export function listRunDirs(repoRoot) {
-    let entries;
-    try {
-        entries = fs.readdirSync(runsRoot(repoRoot));
-    }
-    catch {
-        return [];
-    }
-    return entries
-        .filter(name => name.startsWith('run-'))
-        .map(name => ({
-        runId: name,
-        startedAt: runStartedAtMs(path.join(runsRoot(repoRoot), name, 'run.json')),
-    }))
-        .filter((entry) => (entry.startedAt !== null))
-        .sort((a, b) => b.startedAt - a.startedAt);
-}
-/** Same alias rules as the control plane: run id verbatim, `latest`, or a chapter id. */
-export function resolveRunIdOnDisk(repoRoot, requested) {
-    if (requested.startsWith('run-'))
-        return requested;
-    const prefix = requested === 'latest' ? 'run-' : `run-${requested}-`;
-    const match = listRunDirs(repoRoot).find(entry => entry.runId.startsWith(prefix));
-    return match?.runId ?? requested;
-}
-export function loadRunFromDisk(repoRoot, runId) {
-    const runJsonPath = path.join(runDir(repoRoot, runId), 'run.json');
-    try {
-        return JSON.parse(fs.readFileSync(runJsonPath, 'utf8'));
-    }
-    catch (error) {
-        if (isMissingFileError(error))
-            return null;
-        throw runRecordReadError(runJsonPath, error);
-    }
-}
-export async function fetchRunFromServer(server, idOrAlias) {
-    let response;
-    try {
-        response = await fetch(`${server}/api/cloud-verifier/runs/${encodeURIComponent(idOrAlias)}`, {
-            headers: verifyAuthHeaders(),
-        });
-    }
-    catch (error) {
-        return { outcome: 'unreachable', reason: error instanceof Error ? error.message : String(error) };
-    }
-    if (response.status === 404)
-        return { outcome: 'not_found' };
-    if (response.status === 401)
-        return { outcome: 'unauthorized' };
-    if (!response.ok)
-        return { outcome: 'unreachable', reason: `control plane returned ${response.status}` };
-    return { outcome: 'ok', run: (await response.json()) };
-}
-export async function loadRunAuto(options) {
-    const fetched = await fetchRunFromServer(options.server, options.selector);
-    if (fetched.outcome === 'ok')
-        return { run: fetched.run, source: 'server', stale: false };
-    // A 401 is a misconfiguration, not an outage — falling back to disk would
-    // silently mask it (and a remote control plane has no local disk anyway).
-    if (fetched.outcome === 'unauthorized')
-        throw new VerifyUnauthorizedError(options.server);
-    if (options.repoRoot) {
-        const runId = resolveRunIdOnDisk(options.repoRoot, options.selector);
-        const run = loadRunFromDisk(options.repoRoot, runId);
-        if (run) {
-            return { run, source: 'disk', stale: !TERMINAL_RUN_STATUSES.has(run.status) };
-        }
-    }
-    if (fetched.outcome === 'not_found') {
-        throw new Error(`Run "${options.selector}" not found on the control plane${options.repoRoot ? ' or on disk' : ''}.`);
-    }
-    throw new Error(`Run "${options.selector}" is not readable: control plane at ${options.server} is unreachable (${fetched.reason})`
-        + (options.repoRoot ? ` and no matching run exists under ${runsRoot(options.repoRoot)}.`
-            : ' and no .haystack/verify directory was found from the current directory (run from the repository, or set HAYSTACK_VERIFY_REPO).'));
-}
-export function isTerminal(run) {
-    return TERMINAL_RUN_STATUSES.has(run.status);
-}
-function rowOfRun(run) {
-    const bisect = run.chapters.find(chapter => chapter.bisect)?.bisect;
-    return {
-        run_id: run.runId,
-        chapters: run.chapters.map(chapter => chapter.chapterId),
-        status: run.status,
-        age: formatAge(run.createdAt),
-        created_at: run.createdAt,
-        updated_at: run.updatedAt,
-        tests: run.summary.total,
-        passed: run.summary.passed,
-        failed: run.summary.failed,
-        could_not_run: run.summary.infraErrors + (run.summary.inconclusive ?? 0),
-        culprit_sha: bisect?.culpritSha ?? null,
-    };
-}
-/**
- * List runs, newest first. Prefers the control plane's GET /runs (present on
- * servers with the operator API; required for a remote control plane) and
- * falls back to enumerating the runs directory.
- */
-export async function listRunRows(options) {
-    let serverReason = 'unreachable';
-    try {
-        const response = await fetch(`${options.server}/api/cloud-verifier/runs?limit=${options.limit}`, {
-            headers: verifyAuthHeaders(),
-        });
-        if (response.status === 401)
-            throw new VerifyUnauthorizedError(options.server);
-        if (response.ok) {
-            const body = (await response.json());
-            if (Array.isArray(body.runs)) {
-                // Recompute ages locally so they do not drift with server response caching.
-                const rows = body.runs.map(row => ({
-                    ...row,
-                    age: formatAge(row.created_at || row.updated_at) ?? row.age,
-                }));
-                return { rows, source: 'server', total: body.total ?? rows.length };
-            }
-        }
-        // A 404 is an older control plane without the list route; use disk.
-        serverReason = `HTTP ${response.status}`;
-    }
-    catch (error) {
-        if (error instanceof VerifyUnauthorizedError)
-            throw error;
-        serverReason = error instanceof Error ? error.message : String(error);
-    }
-    if (!options.repoRoot) {
-        throw new Error(`Cannot list runs: the control plane at ${options.server} has no run-list endpoint (${serverReason}) `
-            + 'and no .haystack/verify directory was found locally (run from the repository or set HAYSTACK_VERIFY_REPO).');
-    }
-    const entries = listRunDirs(options.repoRoot);
-    const rows = entries.slice(0, options.limit)
-        .map(entry => loadRunFromDisk(options.repoRoot, entry.runId))
-        .filter((run) => run !== null)
-        .map(rowOfRun);
-    return { rows, source: 'disk', total: entries.length };
-}
-// ---------- summarisation (findings, not run.json) ----------
-export function riskCellIdFor(chapterId, cellKey) {
-    return `cell-${createHash('sha256').update(`${chapterId}|${cellKey}`).digest('hex').slice(0, 12)}`;
-}
-/**
- * Recover the planner's cellKey from artifact filenames (`<cellKey>-<side>-…`).
- * run.json stores only the hashed riskCellId; the key is friendlier to type.
- */
-/**
- * Basename of an evidence artifactUrl. The executor URL-encodes the whole
- * relative path (`<chapter>%2Fartifacts%2F<file>`), so decode before taking
- * the last path segment.
- */
-export function artifactFileOf(artifactUrl) {
-    const decoded = decodeURIComponent(artifactUrl);
-    return decoded.split('/').pop() ?? decoded;
-}
-/** Relative artifact path under the run's chapters/ dir, from an evidence URL. */
-export function artifactRelOf(artifactUrl) {
-    const decoded = decodeURIComponent(artifactUrl);
-    const match = decoded.match(/\/artifacts\/(.+)$/);
-    return match ? match[1] : null;
-}
-export function cellKeyOf(cell) {
-    for (const universe of [cell.head, cell.base]) {
-        for (const evidence of universe.evidence) {
-            if (!evidence.artifactUrl)
-                continue;
-            const file = artifactFileOf(evidence.artifactUrl);
-            const marker = `-${universe.side}-`;
-            const index = file.indexOf(marker);
-            if (index > 0)
-                return file.slice(0, index);
-        }
-    }
-    return null;
-}
-function liveEnvironment(cell) {
-    for (const universe of [cell.head, cell.base]) {
-        if (!universe.browserUrl)
-            continue;
-        if (universe.status !== 'running')
-            continue;
-        const expiresAt = universe.expiresAt ?? null;
-        const expired = expiresAt ? Date.parse(expiresAt) < Date.now() : false;
-        return { url: universe.browserUrl, expiresAt, expired };
-    }
-    return null;
-}
-export function formatDurationMs(ms) {
-    if (typeof ms !== 'number' || !Number.isFinite(ms))
-        return null;
-    if (ms < 1000)
-        return `${Math.round(ms)}ms`;
-    const seconds = Math.round(ms / 1000);
-    if (seconds < 60)
-        return `${seconds}s`;
-    const minutes = Math.floor(seconds / 60);
-    if (minutes < 60)
-        return `${minutes}m${String(seconds % 60).padStart(2, '0')}s`;
-    const hours = Math.floor(minutes / 60);
-    if (hours < 48)
-        return `${hours}h${String(minutes % 60).padStart(2, '0')}m`;
-    return `${Math.floor(hours / 24)}d${hours % 24}h`;
-}
-export function formatAge(iso) {
-    if (!iso)
-        return null;
-    const delta = Date.now() - Date.parse(iso);
-    if (Number.isNaN(delta))
-        return null;
-    return formatDurationMs(Math.abs(delta));
-}
-export function formatUntil(iso) {
-    if (!iso)
-        return null;
-    const delta = Date.parse(iso) - Date.now();
-    if (Number.isNaN(delta))
-        return null;
-    return delta <= 0 ? 'expired' : `in ${formatDurationMs(delta)}`;
-}
-/**
- * Parse an assertion summary of the executor's fixed shape:
- * `<comparison> — base=<json> head=<json> → PASS|FAIL|UNMEASURABLE`.
- * Fallback for runs whose executor did not yet attach structured details to
- * assertion evidence; the structured path always wins when present.
- */
-function readingFromSummary(label, summary) {
-    const arrow = summary.lastIndexOf(' → ');
-    if (arrow < 0)
-        return null;
-    const result = summary.slice(arrow + ' → '.length).trim();
-    if (!['PASS', 'FAIL', 'UNMEASURABLE'].includes(result))
-        return null;
-    const head = summary.slice(0, arrow);
-    const baseAt = head.indexOf(' — base=');
-    if (baseAt < 0)
-        return null;
-    const comparison = head.slice(0, baseAt);
-    const rest = head.slice(baseAt + ' — base='.length);
-    const headAt = rest.indexOf(' head=');
-    if (headAt < 0)
-        return null;
-    const parse = (raw) => {
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return raw;
-        }
-    };
-    const baseValue = parse(rest.slice(0, headAt));
-    const headValue = parse(rest.slice(headAt + ' head='.length));
-    return {
-        metric: label,
-        comparison,
-        base: baseValue ?? null,
-        head: headValue ?? null,
-        changed: JSON.stringify(baseValue ?? null) !== JSON.stringify(headValue ?? null),
-        result: result === 'UNMEASURABLE' ? 'unmeasurable' : result === 'PASS' ? 'pass' : 'fail',
-    };
-}
-/** Frozen-oracle readings for one cell, extracted from its assertion evidence. */
-export function oracleReadingsOf(cell) {
-    const readings = [];
-    const seen = new Set();
-    for (const universe of [cell.head, cell.base]) {
-        for (const evidence of universe.evidence) {
-            if (evidence.kind !== 'assertion')
-                continue;
-            const details = (evidence.details ?? null);
-            const reading = details && 'pass' in details
-                ? {
-                    metric: String(details.metric ?? evidence.label),
-                    comparison: String(details.comparison ?? ''),
-                    base: details.baseValue ?? null,
-                    head: details.headValue ?? null,
-                    changed: JSON.stringify(details.baseValue ?? null) !== JSON.stringify(details.headValue ?? null),
-                    result: details.missing ? 'unmeasurable' : details.pass ? 'pass' : 'fail',
-                }
-                : readingFromSummary(evidence.label, evidence.summary);
-            if (!reading)
-                continue;
-            const key = `${reading.metric}|${reading.comparison}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            readings.push(reading);
-        }
-    }
-    return readings;
-}
-function findingOf(chapter, cell) {
-    const live = liveEnvironment(cell);
-    return {
-        chapter_id: chapter.chapterId,
-        ordinal: cell.ordinal,
-        title: cell.title,
-        severity: cell.severity ?? null,
-        verdict: cell.agentJudgment?.verdict ?? null,
-        summary: cell.agentJudgment ? cell.agentJudgment.explanation.split('\n\n')[0] : null,
-        changed_readings: oracleReadingsOf(cell)
-            .filter(reading => reading.result !== 'pass')
-            .map(reading => reading.result === 'unmeasurable'
-            ? `${reading.metric}: unmeasurable`
-            : `${reading.metric}: ${JSON.stringify(reading.base)} → ${JSON.stringify(reading.head)}`),
-        live_url: live && !live.expired ? live.url : null,
-    };
-}
-export function summarizeRun(loaded, server) {
-    const { run } = loaded;
-    const liveEnvironments = [];
-    const findings = [];
-    const problems = [];
-    // The control plane marks an orphaned run by rewriting its status to
-    // `failed` and appending a synthetic evt-stale event; surface that the same
-    // way as our own disk-side stale detection. The marking can be a false
-    // positive (a dev-server restart loses the in-memory registry while the old
-    // orchestrator keeps running), so a recently-advancing run.json softens it.
-    const staleMarked = run.events.some(event => event.eventId.startsWith('evt-stale-'));
-    const stale = loaded.stale || staleMarked;
-    const possiblyAlive = stale && Date.now() - Date.parse(run.updatedAt) < 60_000;
-    if (stale) {
-        problems.push(possiblyAlive
-            ? 'The control plane lost track of this run (dev-server restart), but run.json advanced within the last minute — it may still be progressing. `haystack verify watch` will confirm.'
-            : 'Run is not terminal but no orchestrator is driving it (control plane down or restarted mid-run). Start a new run.');
-    }
-    // Once nothing can drive the run further, a cell still in a live phase will
-    // never finish — that is a could-not-run, not a verdict.
-    const runDead = (stale && !possiblyAlive) || (TERMINAL_RUN_STATUSES.has(run.status) && !stale);
-    const cellTerminal = new Set(['passed', 'failed', 'infra_error', 'inconclusive']);
-    let stuckCells = 0;
-    const chapters = run.chapters.map(chapter => {
-        const mode = chapter.executionMode === 'bisect' ? 'bisect' : 'risk_cells';
-        const tests = (chapter.riskCells ?? []).map(cell => {
-            if (runDead && !cellTerminal.has(cell.status)) {
-                stuckCells += 1;
-                problems.push(`Test ${cell.ordinal} ("${cell.title}") never finished (still ${cell.status} when the run died) — not a verdict about the change.`);
-            }
-            // Older executors report a cell whose oracles could not be measured as
-            // `inconclusive` (newer ones fail the run instead). Either way it is our
-            // gap, never a verdict.
-            if (cell.status === 'inconclusive') {
-                problems.push(`Test ${cell.ordinal} ("${cell.title}") was inconclusive — one or more readings could not be measured. That is a harness gap, not a verdict about the change.`);
-            }
-            const live = liveEnvironment(cell);
-            if (live && !live.expired) {
-                liveEnvironments.push({
-                    chapter_id: chapter.chapterId,
-                    ordinal: cell.ordinal,
-                    title: cell.title,
-                    url: live.url,
-                    expires_at: live.expiresAt,
-                    expires: formatUntil(live.expiresAt),
-                });
-            }
-            if (cell.status === 'infra_error') {
-                problems.push(cell.infrastructureError
-                    ? `Test ${cell.ordinal} ("${cell.title}") could not run — ${cell.infrastructureError.reason}: ${cell.infrastructureError.message}`
-                    : `Test ${cell.ordinal} ("${cell.title}") could not run — infrastructure failure, not a verdict about the change.`);
-            }
-            if (cell.status === 'failed') {
-                findings.push(findingOf(chapter, cell));
-            }
-            return {
-                ordinal: cell.ordinal,
-                cell_id: cell.riskCellId,
-                cell_key: cellKeyOf(cell),
-                title: cell.title,
-                status: cell.status,
-                severity: cell.severity ?? null,
-                verdict: cell.agentJudgment?.verdict ?? null,
-                duration: formatDurationMs(cell.durationMs),
-                live_url: live && !live.expired ? live.url : null,
-                live_expires_at: live && !live.expired ? live.expiresAt : null,
-                live_expires: live && !live.expired ? formatUntil(live.expiresAt) : null,
-            };
-        });
-        let bisect = null;
-        if (chapter.bisect) {
-            const byStatus = {};
-            for (const probe of chapter.bisect.probes) {
-                byStatus[probe.status] = (byStatus[probe.status] ?? 0) + 1;
-            }
-            bisect = {
-                status: chapter.bisect.status,
-                signal: chapter.bisect.signal,
-                total_candidates: chapter.bisect.totalCandidates,
-                probes_total: chapter.bisect.probes.length,
-                probes_by_status: byStatus,
-                culprit_sha: chapter.bisect.culpritSha ?? null,
-                culprit_subject: chapter.bisect.culpritSubject ?? null,
-                parent_sha: chapter.bisect.parentSha ?? null,
-            };
-            if (['inconclusive', 'error'].includes(chapter.bisect.status)) {
-                problems.push(`Bisect chapter ${chapter.chapterId} ended ${chapter.bisect.status} — no culprit isolated.`);
-            }
-            if (chapter.bisect.culpritSha) {
-                findings.push({
-                    chapter_id: chapter.chapterId,
-                    ordinal: 0,
-                    title: `First bad commit: ${chapter.bisect.culpritSha.slice(0, 8)} ${chapter.bisect.culpritSubject ?? ''}`.trim(),
-                    severity: null,
-                    verdict: 'culprit',
-                    summary: chapter.bisect.signal,
-                    changed_readings: chapter.bisect.parentSha ? [`clean parent: ${chapter.bisect.parentSha.slice(0, 8)}`] : [],
-                    live_url: null,
-                });
-            }
-        }
-        if (chapter.status === 'failed' && mode === 'risk_cells' && tests.length === 0) {
-            problems.push(`Chapter ${chapter.chapterId} failed before any test ran (see events).`);
-        }
-        return {
-            chapter_id: chapter.chapterId,
-            execution_mode: mode,
-            analysis_mode: chapter.analysisMode ?? null,
-            label: chapter.label,
-            repository: chapter.repository,
-            pull_request: chapter.pullRequest,
-            status: chapter.status,
-            tests,
-            bisect,
-        };
-    });
-    if (run.summary.infraErrors > 0) {
-        problems.push(`${run.summary.infraErrors} test(s) could not run at all; they are excluded from pass/fail.`);
-    }
-    const lastEvent = run.events.length > 0 ? run.events[run.events.length - 1] : null;
-    return {
-        schema_version: '1.0.0',
-        run_id: run.runId,
-        status: stale ? 'failed' : run.status,
-        stale,
-        source: loaded.source,
-        created_at: run.createdAt,
-        updated_at: run.updatedAt,
-        age: formatAge(run.createdAt),
-        counts: {
-            total: run.summary.total,
-            completed: run.summary.completed,
-            passed: run.summary.passed,
-            failed: run.summary.failed,
-            could_not_run: run.summary.infraErrors + (run.summary.inconclusive ?? 0) + stuckCells,
-        },
-        findings,
-        chapters,
-        live_environments: liveEnvironments,
-        problems,
-        last_event: lastEvent ? { at: lastEvent.at, phase: lastEvent.phase, message: lastEvent.message } : null,
-        results_url: `${server}/dev/verify/${run.runId}`,
-    };
-}
-/**
- * Exit-code policy shared by `verify watch` and callers of the MCP wait tool:
- * 0 — everything that ran passed (a found bisect culprit counts as success);
- * 1 — at least one test failed;
- * 2 — the run itself broke, went stale, or some test could not run.
- */
-export function exitCodeFor(summary) {
-    const bisectBroken = summary.chapters.some(chapter => chapter.bisect && ['inconclusive', 'error'].includes(chapter.bisect.status));
-    if (summary.stale || summary.counts.could_not_run > 0 || bisectBroken)
-        return 2;
-    if (summary.status === 'failed' && summary.counts.total === 0)
-        return 2;
-    if (summary.counts.failed > 0)
-        return 1;
-    return 0;
-}
-/** Match a test by ordinal, riskCellId, planner cellKey, or title substring. */
-export function findCell(run, selector) {
-    const cells = run.chapters.flatMap(chapter => (chapter.riskCells ?? []).map(cell => ({ chapter, cell })));
-    if (cells.length === 0) {
-        throw new Error(`Run ${run.runId} has no risk cells (execution mode: ${run.chapters.map(c => c.executionMode ?? 'risk_cells').join(', ')}).`);
-    }
-    const ordinal = Number(selector);
-    const matches = cells.filter(({ chapter, cell }) => cell.riskCellId === selector
-        || (Number.isInteger(ordinal) && ordinal > 0 && cell.ordinal === ordinal)
-        || riskCellIdFor(chapter.chapterId, selector) === cell.riskCellId
-        || cellKeyOf(cell) === selector
-        || cell.title.toLowerCase().includes(selector.toLowerCase()));
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length === 0) {
-        throw new Error(`No test matches "${selector}". Tests:\n`
-            + cells.map(({ cell }) => `  ${cell.ordinal}. ${cell.title} (${cell.riskCellId})`).join('\n'));
-    }
-    throw new Error(`"${selector}" is ambiguous. Matches:\n`
-        + matches.map(({ cell }) => `  ${cell.ordinal}. ${cell.title} (${cell.riskCellId})`).join('\n'));
-}
-/**
- * Resolve a cell for an operator action without using its free-text title.
- * Ordinals are scoped by the exact run, while riskCellId and planner cellKey
- * are stable structured identifiers carried by the run.
- */
-export function findCellByStableSelector(run, selector) {
-    const cells = run.chapters.flatMap(chapter => (chapter.riskCells ?? []).map(cell => ({ chapter, cell })));
-    if (cells.length === 0) {
-        throw new Error(`Run ${run.runId} has no risk cells (execution mode: `
-            + `${run.chapters.map(c => c.executionMode ?? 'risk_cells').join(', ')}).`);
-    }
-    const ordinal = Number(selector);
-    const matches = cells.filter(({ chapter, cell }) => cell.riskCellId === selector
-        || (Number.isInteger(ordinal) && ordinal > 0 && cell.ordinal === ordinal)
-        || riskCellIdFor(chapter.chapterId, selector) === cell.riskCellId
-        || cellKeyOf(cell) === selector);
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length === 0) {
-        throw new Error(`No test has stable selector "${selector}". Use an ordinal, riskCellId, `
-            + `or exact planner cellKey:\n`
-            + cells
-                .map(({ cell }) => `  ${cell.ordinal}. ${cell.title} (${cell.riskCellId})`)
-                .join('\n'));
-    }
-    throw new Error(`"${selector}" is ambiguous. Use a riskCellId instead:\n`
-        + matches
-            .map(({ cell }) => `  ${cell.ordinal}. ${cell.title} (${cell.riskCellId})`)
-            .join('\n'));
-}
-function universeDetail(universe, opts) {
-    const network = [];
-    const sdkLog = [];
-    const driverFailures = [];
-    const artifacts = [];
-    for (const evidence of universe.evidence) {
-        if (evidence.kind === 'network' && opts.timeline) {
-            const details = (evidence.details ?? {});
-            network.push({
-                sequence: typeof details.sequence === 'number' ? details.sequence : null,
-                offset_ms: typeof details.offsetMs === 'number' ? details.offsetMs : null,
-                method: typeof details.method === 'string' ? details.method : null,
-                path: typeof details.path === 'string' ? details.path : evidence.label,
-                status: typeof evidence.value === 'string' ? evidence.value : String(details.status ?? ''),
-                channel: typeof details.channel === 'string' ? details.channel : null,
-                event_name: typeof details.eventName === 'string' ? details.eventName : null,
-                step: evidence.step ? `${evidence.step.ordinal}. ${evidence.step.name}` : null,
-            });
-        }
-        else if (evidence.kind === 'log') {
-            if (evidence.label === 'driver failure')
-                driverFailures.push(evidence.summary);
-            else
-                sdkLog.push(evidence.summary);
-        }
-        else if (['screenshot', 'dom', 'video'].includes(evidence.kind) && evidence.artifactUrl) {
-            artifacts.push({
-                kind: evidence.kind,
-                label: evidence.label,
-                url: evidence.artifactUrl,
-                file: artifactFileOf(evidence.artifactUrl),
-            });
-        }
-    }
-    network.sort((a, b) => (a.sequence ?? 0) - (b.sequence ?? 0));
-    return {
-        universe_id: universe.universeId,
-        status: universe.status,
-        sandbox_id: universe.sandboxId ?? null,
-        state_provider: universe.stateProvider ?? null,
-        snapshot_id: universe.snapshotId ?? null,
-        fork_id: universe.forkId ?? null,
-        execution_id: universe.executionId ?? null,
-        state_layers: universe.stateLayers ?? [],
-        network,
-        sdk_log: sdkLog,
-        driver_failures: driverFailures,
-        artifacts,
-    };
-}
-export function cellDetail(run, match, opts) {
-    const { chapter, cell } = match;
-    const timeline = opts?.timeline !== false;
-    const readings = oracleReadingsOf(cell);
-    const live = liveEnvironment(cell);
-    const verdict = cell.agentJudgment?.verdict ?? null;
-    const finding = cell.agentJudgment
-        ? `${cell.title}: ${verdict === 'regression' ? 'regressed' : verdict}. ${cell.agentJudgment.explanation.split(/(?<=\.)\s/)[0]}`
-        : null;
-    return {
-        schema_version: '1.0.0',
-        run_id: run.runId,
-        chapter_id: chapter.chapterId,
-        ordinal: cell.ordinal,
-        cell_id: cell.riskCellId,
-        cell_key: cellKeyOf(cell),
-        title: cell.title,
-        status: cell.status,
-        severity: cell.severity ?? null,
-        duration: formatDurationMs(cell.durationMs),
-        finding,
-        verdict,
-        explanation: cell.agentJudgment?.explanation ?? null,
-        intent_evidence: cell.agentJudgment?.intentEvidence ?? null,
-        infrastructure_error: cell.infrastructureError ?? null,
-        rationale: cell.rationale ?? null,
-        observable_consequence: cell.observableConsequence ?? null,
-        oracle_readings: readings,
-        readings_changed: readings.filter(reading => reading.changed || reading.result !== 'pass'),
-        live_environment: live && !live.expired
-            ? { url: live.url, expires_at: live.expiresAt, expires: formatUntil(live.expiresAt) }
-            : null,
-        base: universeDetail(cell.base, { timeline }),
-        head: universeDetail(cell.head, { timeline }),
-    };
-}
-/**
- * Poll until the run reaches a terminal state. The terminal predicate is the
- * run status alone — never a cell's: a cell legitimately sits in
- * `provisioning` for minutes while sandbox creation retries.
- *
- * A stale marking (from the control plane, or from a disk read with no
- * reachable server) is treated with suspicion rather than as terminal: a Vite
- * restart re-creates the plugin's in-memory run registry while the old
- * orchestrator can keep running in the same process, so "no orchestrator is
- * driving this run" can be false. As long as run.json keeps advancing, the run
- * is alive regardless of what the registry thinks; staleness is only accepted
- * after a no-progress grace period.
- */
-export async function waitForTerminal(options) {
-    const intervalMs = options.intervalMs ?? 3000;
-    const staleGraceMs = Math.max(20_000, intervalMs * 4);
-    const deadline = options.timeoutMs ? Date.now() + options.timeoutMs : null;
-    const callbacks = options.callbacks ?? {};
-    // Pin the alias to a concrete run id on first load so `latest` cannot slide
-    // to a different run started mid-watch.
-    let pinned = null;
-    const seenEvents = new Set();
-    const cellStatuses = new Map();
-    let first = true;
-    let lastUpdatedAt = '';
-    let noProgressSince = null;
-    for (;;) {
-        const loaded = await loadRunAuto({
-            server: options.server,
-            repoRoot: options.repoRoot,
-            selector: pinned ?? options.selector,
-        });
-        if (!pinned) {
-            pinned = loaded.run.runId;
-            callbacks.onResolved?.(pinned);
-        }
-        for (const event of loaded.run.events) {
-            if (seenEvents.has(event.eventId))
-                continue;
-            seenEvents.add(event.eventId);
-            // The backlog before we attached is context, not progress; report it only
-            // via the first snapshot, then stream genuinely new events.
-            if (!first)
-                callbacks.onEvent?.(event);
-        }
-        for (const chapter of loaded.run.chapters) {
-            for (const cell of chapter.riskCells ?? []) {
-                const previous = cellStatuses.get(cell.riskCellId);
-                cellStatuses.set(cell.riskCellId, cell.status);
-                if (!first && previous && previous !== cell.status) {
-                    callbacks.onCellChange?.(chapter.chapterId, cell, previous);
-                }
-            }
-        }
-        first = false;
-        const staleMarked = loaded.stale || loaded.run.events.some(event => event.eventId.startsWith('evt-stale-'));
-        if (isTerminal(loaded.run) && !staleMarked) {
-            return { loaded, timedOut: false, endReason: 'terminal' };
-        }
-        const progressed = loaded.run.updatedAt !== lastUpdatedAt;
-        lastUpdatedAt = loaded.run.updatedAt;
-        if (staleMarked) {
-            if (progressed) {
-                noProgressSince = null;
-            }
-            else {
-                noProgressSince = noProgressSince ?? Date.now();
-                if (Date.now() - noProgressSince > staleGraceMs) {
-                    return { loaded, timedOut: false, endReason: 'stale' };
-                }
-            }
-        }
-        else {
-            noProgressSince = null;
-        }
-        if (deadline && Date.now() > deadline) {
-            return { loaded, timedOut: true, endReason: 'timeout' };
-        }
-        await new Promise(resolve => setTimeout(resolve, intervalMs));
-    }
-}