@haystackeditor/cli 0.15.30 → 0.16.0

package/dist/commands/verify-ops.js

@@ -1,1148 +0,0 @@
-// Operator commands over cloud-verifier runs: status, watch, list, show,
-// artifacts. Data plumbing lives in verify-core.ts (shared with the MCP
-// server); this file is terminal rendering and exit codes.
-import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import chalk from 'chalk';
-import { artifactFileOf, cellDetail, discoverVerifyRoot, exitCodeFor, findCell, findCellByStableSelector, loadRunAuto, listRunRows, resolveServer, runDir, setVerifyToken, summarizeRun, verifyAuthHeaders, waitForTerminal, } from './verify-core.js';
-function statusGlyph(status) {
-    switch (status) {
-        case 'passed': return chalk.green('✓');
-        case 'failed': return chalk.red('✗');
-        case 'infra_error': return chalk.yellow('⚠');
-        case 'inconclusive': return chalk.yellow('?');
-        case 'queued': return chalk.dim('·');
-        default: return chalk.cyan('◷');
-    }
-}
-function emitJson(payload) {
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-}
-function renderStatus(summary) {
-    const state = summary.stale ? `${chalk.red('failed')} ${chalk.dim('(stale — orchestrator gone)')}`
-        : summary.status === 'complete' ? chalk.green(summary.status)
-            : summary.status === 'failed' ? chalk.red(summary.status)
-                : chalk.cyan(summary.status);
-    console.log(`${chalk.bold(summary.run_id)} — ${state}${summary.age ? chalk.dim(` (started ${summary.age} ago)`) : ''}`);
-    for (const chapter of summary.chapters) {
-        console.log(`${chalk.dim(chapter.repository)} ${chapter.pull_request} — ${chapter.label}`);
-        if (chapter.execution_mode === 'bisect' && chapter.bisect) {
-            const b = chapter.bisect;
-            const probeBits = Object.entries(b.probes_by_status).map(([k, v]) => `${v} ${k}`).join(', ');
-            console.log(`  bisect ${b.status} — ${b.probes_total}/${b.total_candidates} candidates probed${probeBits ? ` (${probeBits})` : ''}`);
-            if (b.culprit_sha) {
-                console.log(`  ${chalk.red('culprit')} ${b.culprit_sha.slice(0, 8)} ${b.culprit_subject ?? ''}${b.parent_sha ? chalk.dim(` (clean parent ${b.parent_sha.slice(0, 8)})`) : ''}`);
-            }
-            continue;
-        }
-        for (const test of chapter.tests) {
-            const verdict = test.verdict ? chalk.dim(` ${test.verdict}`) : '';
-            const duration = test.duration ? chalk.dim(` (${test.duration})`) : '';
-            const severity = test.severity ? chalk.dim(` [${test.severity}]`) : '';
-            console.log(`  ${statusGlyph(test.status)} ${test.ordinal}. ${test.title}${severity}${verdict}${duration}`);
-        }
-    }
-    const c = summary.counts;
-    const bisectOnly = c.total === 0 && summary.chapters.some(chapter => chapter.execution_mode === 'bisect');
-    if (!bisectOnly) {
-        console.log('');
-        console.log(`${c.total} tests: ${chalk.green(`${c.passed} passed`)}, ${c.failed > 0 ? chalk.red(`${c.failed} failed`) : `${c.failed} failed`}${c.could_not_run > 0 ? `, ${chalk.yellow(`${c.could_not_run} could not run`)}` : ''}`);
-    }
-    if (summary.live_environments.length > 0) {
-        console.log('');
-        console.log(chalk.bold('Live environments (failing tests):'));
-        for (const env of summary.live_environments) {
-            console.log(`  ${env.ordinal}. ${chalk.cyan(env.url)} ${chalk.dim(`expires ${env.expires ?? env.expires_at ?? 'unknown'}`)}`);
-        }
-    }
-    if (summary.problems.length > 0) {
-        console.log('');
-        console.log(chalk.yellow.bold('Problems (ours, not findings):'));
-        for (const problem of summary.problems)
-            console.log(`  ${chalk.yellow('!')} ${problem}`);
-    }
-    if (!isTerminalStatus(summary) && summary.last_event) {
-        console.log('');
-        console.log(chalk.dim(`Last event [${summary.last_event.phase}] ${summary.last_event.message}`));
-    }
-    console.log('');
-    console.log(chalk.dim(`Results: ${summary.results_url}`));
-}
-function isTerminalStatus(summary) {
-    return ['complete', 'failed'].includes(summary.status);
-}
-export async function verifyStatusCommand(runSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector || 'latest' });
-    const summary = summarizeRun(loaded, server);
-    if (options.json)
-        return emitJson(summary);
-    renderStatus(summary);
-}
-export async function verifyWatchCommand(runSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const intervalMs = Math.max(1000, Number(options.interval ?? 3) * 1000);
-    const timeoutMs = options.timeout ? Number(options.timeout) * 60_000 : undefined;
-    if ((options.interval && Number.isNaN(Number(options.interval))) || (options.timeout && Number.isNaN(Number(options.timeout)))) {
-        throw new Error('--interval and --timeout take numbers (seconds and minutes respectively)');
-    }
-    const quiet = Boolean(options.json);
-    const result = await waitForTerminal({
-        server,
-        repoRoot,
-        selector: runSelector || 'latest',
-        intervalMs,
-        timeoutMs,
-        callbacks: quiet ? {} : {
-            onResolved: runId => console.error(chalk.dim(`Watching ${runId} (poll every ${intervalMs / 1000}s)…`)),
-            onEvent: event => console.error(`${chalk.dim(`[${event.phase}]`)} ${event.message}`),
-            onCellChange: (_chapterId, cell, previous) => console.error(`  ${statusGlyph(cell.status)} test ${cell.ordinal} ${chalk.dim(cell.title.slice(0, 70))}: ${previous} → ${chalk.bold(cell.status)}`),
-        },
-    });
-    const summary = summarizeRun(result.loaded, server);
-    if (result.timedOut) {
-        if (options.json)
-            emitJson({ ...summary, timed_out: true });
-        else
-            console.error(chalk.yellow(`Timed out after ${options.timeout}m; run is still ${summary.status}.`));
-        process.exitCode = 2;
-        return;
-    }
-    if (options.json) {
-        emitJson({ ...summary, timed_out: false });
-    }
-    else {
-        console.error('');
-        renderStatus(summary);
-    }
-    process.exitCode = exitCodeFor(summary);
-}
-export async function verifyListCommand(options) {
-    setVerifyToken(options.token);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const limit = options.limit ? Number(options.limit) : 20;
-    if (Number.isNaN(limit) || limit < 1)
-        throw new Error('--limit takes a positive number');
-    const server = resolveServer(options.server);
-    const { rows, source, total } = await listRunRows({ server, repoRoot, limit });
-    if (options.json) {
-        return emitJson({ schema_version: '1.0.0', source, total, runs: rows });
-    }
-    if (rows.length === 0) {
-        console.log(chalk.dim('No runs found.'));
-        return;
-    }
-    const idWidth = Math.max(...rows.map(row => row.run_id.length));
-    for (const row of rows) {
-        const verdicts = row.tests > 0
-            ? `${chalk.green(`${row.passed}✓`)} ${row.failed > 0 ? chalk.red(`${row.failed}✗`) : `${row.failed}✗`}${row.could_not_run ? chalk.yellow(` ${row.could_not_run}⚠`) : ''}`
-            : row.culprit_sha ? `culprit ${row.culprit_sha.slice(0, 8)}` : chalk.dim('—');
-        const status = row.status === 'complete' ? chalk.green(row.status)
-            : row.status === 'failed' ? chalk.red(row.status) : chalk.cyan(row.status);
-        console.log(`${row.run_id.padEnd(idWidth)}  ${status.padEnd(10)}  ${verdicts}  ${chalk.dim(`${row.age} ago`)}`);
-    }
-    if (total > rows.length) {
-        console.log(chalk.dim(`… ${total - rows.length} older run(s); use --limit to see more.`));
-    }
-    console.log(chalk.dim(`\nDetails: haystack verify status <run>  ·  UI: ${server}/dev/verify/<run>`));
-}
-function renderTimeline(label, universe) {
-    console.log(chalk.bold(`  ${label} timeline (${universe.network.length} requests)`));
-    for (const entry of universe.network) {
-        const offset = entry.offset_ms !== null ? `+${(entry.offset_ms / 1000).toFixed(1)}s`.padStart(7) : '       ';
-        const eventName = entry.event_name ? chalk.dim(` (${entry.event_name})`) : '';
-        const bad = entry.status.startsWith('failed') || /^HTTP [45]/.test(entry.status);
-        console.log(`    ${chalk.dim(offset)} ${entry.method ?? 'GET'} ${entry.path} ${bad ? chalk.red(entry.status) : chalk.dim(entry.status)}${eventName}`);
-    }
-}
-function renderSdkLog(label, universe) {
-    if (universe.sdk_log.length === 0)
-        return;
-    console.log(chalk.bold(`  ${label} SDK log (${universe.sdk_log.length} lines)`));
-    for (const line of universe.sdk_log)
-        console.log(`    ${chalk.dim(line)}`);
-}
-function renderShow(detail) {
-    const glyph = statusGlyph(detail.status);
-    console.log(`${glyph} ${chalk.bold(`Test ${detail.ordinal}: ${detail.title}`)}`);
-    console.log(chalk.dim(`  ${detail.run_id} · ${detail.chapter_id} · ${detail.cell_id}${detail.severity ? ` · ${detail.severity}` : ''}${detail.duration ? ` · ${detail.duration}` : ''}`));
-    console.log('');
-    if (detail.status === 'infra_error') {
-        console.log(chalk.yellow('  This test could not run (infrastructure failure). That is our defect, not a verdict about the change.'));
-        if (detail.infrastructure_error) {
-            console.log(chalk.yellow(`  ${detail.infrastructure_error.reason}: ${detail.infrastructure_error.message}`));
-        }
-        for (const failure of [...detail.base.driver_failures, ...detail.head.driver_failures]) {
-            console.log(chalk.yellow(`  ${failure}`));
-        }
-    }
-    if (detail.verdict) {
-        console.log(`  ${chalk.bold('Verdict:')} ${detail.verdict}`);
-        if (detail.explanation)
-            console.log(`  ${detail.explanation.split('\n').join('\n  ')}`);
-        if (detail.intent_evidence)
-            console.log(chalk.dim(`  Intent evidence: ${detail.intent_evidence}`));
-        console.log('');
-    }
-    if (detail.oracle_readings.length > 0) {
-        console.log(chalk.bold('  Readings'));
-        for (const reading of detail.oracle_readings) {
-            const mark = reading.result === 'pass' ? chalk.green('pass') : reading.result === 'fail' ? chalk.red('FAIL') : chalk.yellow('unmeasurable');
-            const change = reading.changed ? chalk.yellow(`${JSON.stringify(reading.base)} → ${JSON.stringify(reading.head)}`) : chalk.dim(`${JSON.stringify(reading.head)} (unchanged)`);
-            console.log(`    ${mark.padEnd(6)} ${reading.metric} ${chalk.dim(`[${reading.comparison}]`)} ${change}`);
-        }
-        console.log('');
-    }
-    for (const failure of detail.base.driver_failures)
-        console.log(chalk.yellow(`  base driver failure: ${failure}`));
-    for (const failure of detail.head.driver_failures)
-        console.log(chalk.yellow(`  head driver failure: ${failure}`));
-    renderTimeline('base', detail.base);
-    renderTimeline('head', detail.head);
-    console.log('');
-    renderSdkLog('base', detail.base);
-    renderSdkLog('head', detail.head);
-    const artifactCount = detail.base.artifacts.length + detail.head.artifacts.length;
-    if (artifactCount > 0) {
-        console.log('');
-        console.log(chalk.dim(`  ${artifactCount} artifacts (screenshots/DOM/video) — fetch with: haystack verify artifacts ${detail.run_id} --cell ${detail.ordinal}`));
-    }
-    if (detail.live_environment) {
-        console.log('');
-        console.log(`  ${chalk.bold('Live environment:')} ${chalk.cyan(detail.live_environment.url)} ${chalk.dim(`expires ${detail.live_environment.expires ?? ''}`)}`);
-    }
-}
-export async function verifyShowCommand(runSelector, cellSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector });
-    const match = findCell(loaded.run, cellSelector);
-    const detail = cellDetail(loaded.run, match, { timeline: options.timeline !== false });
-    if (options.json)
-        return emitJson(detail);
-    renderShow(detail);
-}
-/** Collect artifact URLs (evidence-declared) for optional per-cell filtering. */
-function artifactFilesForCell(run, cellSelector) {
-    const match = findCell(run, cellSelector);
-    const files = new Set();
-    for (const universe of [match.cell.base, match.cell.head]) {
-        for (const evidence of universe.evidence) {
-            if (!evidence.artifactUrl)
-                continue;
-            files.add(artifactFileOf(evidence.artifactUrl));
-        }
-    }
-    return files;
-}
-export async function verifyArtifactsCommand(runSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector });
-    const run = loaded.run;
-    const outRoot = path.resolve(options.out || `verify-artifacts/${run.runId}`);
-    const cellFilter = options.cell ? artifactFilesForCell(run, options.cell) : null;
-    const copied = [];
-    const skipped = [];
-    const localRunDir = repoRoot ? runDir(repoRoot, run.runId) : null;
-    if (localRunDir && fs.existsSync(path.join(localRunDir, 'chapters'))) {
-        // Same machine as the control plane: copy straight from the run directory.
-        for (const chapter of run.chapters) {
-            const artifactsDir = path.join(localRunDir, 'chapters', chapter.chapterId, 'artifacts');
-            if (!fs.existsSync(artifactsDir))
-                continue;
-            const destDir = path.join(outRoot, chapter.chapterId);
-            fs.mkdirSync(destDir, { recursive: true });
-            for (const file of fs.readdirSync(artifactsDir)) {
-                if (cellFilter && !cellFilter.has(file)) {
-                    skipped.push(file);
-                    continue;
-                }
-                const source = path.join(artifactsDir, file);
-                if (!fs.statSync(source).isFile())
-                    continue;
-                fs.copyFileSync(source, path.join(destDir, file));
-                copied.push({ file: path.join(chapter.chapterId, file), bytes: fs.statSync(source).size });
-            }
-        }
-    }
-    else {
-        // No disk access to the run — pull every evidence-declared artifact over HTTP.
-        const urls = new Map();
-        for (const chapter of run.chapters) {
-            for (const cell of chapter.riskCells ?? []) {
-                for (const universe of [cell.base, cell.head]) {
-                    for (const evidence of universe.evidence) {
-                        if (!evidence.artifactUrl)
-                            continue;
-                        const file = artifactFileOf(evidence.artifactUrl);
-                        if (cellFilter && !cellFilter.has(file))
-                            continue;
-                        urls.set(`${chapter.chapterId}/${file}`, evidence.artifactUrl);
-                    }
-                }
-            }
-        }
-        for (const [rel, url] of urls) {
-            const response = await fetch(`${server}${url}`, { headers: verifyAuthHeaders() });
-            if (!response.ok) {
-                skipped.push(`${rel} (HTTP ${response.status})`);
-                continue;
-            }
-            const bytes = Buffer.from(await response.arrayBuffer());
-            const dest = path.join(outRoot, rel);
-            fs.mkdirSync(path.dirname(dest), { recursive: true });
-            fs.writeFileSync(dest, bytes);
-            copied.push({ file: rel, bytes: bytes.length });
-        }
-    }
-    const totalBytes = copied.reduce((sum, entry) => sum + entry.bytes, 0);
-    if (options.json) {
-        return emitJson({
-            schema_version: '1.0.0',
-            run_id: run.runId,
-            out_dir: outRoot,
-            copied: copied.length,
-            total_bytes: totalBytes,
-            skipped_by_filter: options.cell ? skipped.length : 0,
-            files: copied.map(entry => entry.file),
-        });
-    }
-    if (copied.length === 0) {
-        console.log(chalk.yellow(`No artifacts ${options.cell ? `matching test "${options.cell}" ` : ''}found for ${run.runId}.`));
-        process.exitCode = 1;
-        return;
-    }
-    console.log(`${chalk.green('✓')} ${copied.length} artifacts (${(totalBytes / 1024 / 1024).toFixed(1)}MB) → ${chalk.bold(outRoot)}`);
-    const byKind = new Map();
-    for (const entry of copied) {
-        const ext = path.extname(entry.file) || 'other';
-        byKind.set(ext, (byKind.get(ext) ?? 0) + 1);
-    }
-    console.log(chalk.dim(`  ${[...byKind.entries()].map(([ext, count]) => `${count} ${ext.replace('.', '')}`).join(', ')}`));
-}
-// ---------- findings ----------
-export async function verifyFindingsCommand(runSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector || 'latest' });
-    const summary = summarizeRun(loaded, server);
-    if (options.json) {
-        return emitJson({
-            schema_version: '1.0.0',
-            run_id: summary.run_id,
-            status: summary.status,
-            counts: summary.counts,
-            findings: summary.findings,
-            problems: summary.problems,
-        });
-    }
-    if (summary.findings.length === 0 && summary.problems.length === 0) {
-        console.log(`${chalk.green('✓')} ${summary.run_id}: nothing broke — ${summary.counts.passed}/${summary.counts.total} tests passed.`);
-        return;
-    }
-    // The digest keeps only the explanation's first paragraph; --full goes back
-    // to the run for the whole thing.
-    const fullExplanations = new Map();
-    if (options.full) {
-        for (const chapter of loaded.run.chapters) {
-            for (const cell of chapter.riskCells ?? []) {
-                if (cell.agentJudgment) {
-                    fullExplanations.set(`${chapter.chapterId}|${cell.ordinal}`, cell.agentJudgment.explanation);
-                }
-            }
-        }
-    }
-    console.log(`${chalk.bold(summary.run_id)} — ${summary.findings.length} finding(s)`);
-    for (const finding of summary.findings) {
-        console.log('');
-        const head = finding.verdict === 'culprit'
-            ? `${chalk.red('◉')} ${chalk.bold(finding.title)}`
-            : `${chalk.red('✗')} ${finding.ordinal}. ${chalk.bold(finding.title)}${finding.severity ? chalk.dim(` [${finding.severity}]`) : ''} — ${finding.verdict ?? 'failed'}`;
-        console.log(head);
-        for (const reading of finding.changed_readings)
-            console.log(`   ${chalk.yellow(reading)}`);
-        if (finding.summary) {
-            const full = fullExplanations.get(`${finding.chapter_id}|${finding.ordinal}`);
-            const text = options.full
-                ? full ?? finding.summary
-                : finding.summary.length > 320 ? `${finding.summary.slice(0, 320)}… (--full for the rest)` : finding.summary;
-            console.log(`   ${chalk.dim(text.split('\n').join('\n   '))}`);
-        }
-        if (finding.live_url)
-            console.log(`   live: ${chalk.cyan(finding.live_url)}`);
-    }
-    if (summary.problems.length > 0) {
-        console.log('');
-        console.log(chalk.yellow.bold('Problems (ours, not findings):'));
-        for (const problem of summary.problems)
-            console.log(`  ${chalk.yellow('!')} ${problem}`);
-    }
-    console.log('');
-    console.log(chalk.dim(`Full detail per test: haystack verify show ${summary.run_id} <n>`));
-}
-// ---------- open / shell ----------
-function launch(target) {
-    const platform = process.platform;
-    const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = platform === 'win32' ? ['/c', 'start', '', target] : [target];
-    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
-    child.unref();
-}
-/**
- * Open one piece of a run: a live environment (`--live`), a specific artifact
- * by file name, or a cell's video/screenshot/DOM snapshot picked by
- * --side/--step/--kind.
- */
-export async function verifyOpenCommand(runSelector, target, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector });
-    const run = loaded.run;
-    // A file name (has an extension) opens that artifact directly, from any cell.
-    if (/\.[a-z0-9]+$/i.test(target) && !options.live) {
-        const fileName = path.posix.basename(target);
-        const localRunDir = repoRoot ? runDir(repoRoot, run.runId) : null;
-        if (localRunDir) {
-            for (const chapter of run.chapters) {
-                const candidate = path.join(localRunDir, 'chapters', chapter.chapterId, 'artifacts', fileName);
-                if (fs.existsSync(candidate)) {
-                    launch(candidate);
-                    console.log(`${chalk.green('✓')} opened ${candidate}`);
-                    return;
-                }
-            }
-        }
-        // Fall back to the control plane's artifact endpoint.
-        for (const chapter of run.chapters) {
-            const url = `${server}/api/cloud-verifier/runs/${run.runId}/artifacts/${encodeURIComponent(`${chapter.chapterId}/artifacts/${fileName}`)}`;
-            const response = await fetch(url, { headers: verifyAuthHeaders() });
-            if (!response.ok)
-                continue;
-            const dest = path.join(os.tmpdir(), 'haystack-verify-artifacts', run.runId, fileName);
-            fs.mkdirSync(path.dirname(dest), { recursive: true });
-            fs.writeFileSync(dest, Buffer.from(await response.arrayBuffer()));
-            launch(dest);
-            console.log(`${chalk.green('✓')} opened ${dest}`);
-            return;
-        }
-        throw new Error(`Artifact "${fileName}" not found in ${run.runId}. List artifacts with: haystack verify show ${run.runId} <test> or verify artifacts.`);
-    }
-    const match = findCell(run, target);
-    const detail = cellDetail(run, match, { timeline: false });
-    if (options.live) {
-        if (!detail.live_environment) {
-            throw new Error(`Test ${detail.ordinal} has no live environment${detail.status === 'failed' ? ' any more — it expired (failing tests keep one for 90 minutes). Re-run the chapter for a fresh one.' : ' — only failing tests keep one alive.'}`);
-        }
-        launch(detail.live_environment.url);
-        console.log(`${chalk.green('✓')} opened ${chalk.cyan(detail.live_environment.url)} ${chalk.dim(`(expires ${detail.live_environment.expires ?? ''})`)}`);
-        return;
-    }
-    const side = options.side === 'base' ? detail.base : detail.head;
-    const sideName = options.side === 'base' ? 'base' : 'head';
-    let pick;
-    if (options.step) {
-        const stepOrdinal = Number(options.step);
-        const wantKind = options.kind ?? 'screenshot';
-        pick = side.artifacts.find(artifact => artifact.kind === wantKind && artifact.label.startsWith(`step ${stepOrdinal}:`));
-    }
-    else if (options.kind) {
-        pick = side.artifacts.find(artifact => artifact.kind === options.kind);
-    }
-    else {
-        pick = side.artifacts.find(artifact => artifact.kind === 'video')
-            ?? side.artifacts.filter(artifact => artifact.kind === 'screenshot').pop();
-    }
-    if (!pick) {
-        const available = side.artifacts.map(artifact => `  ${artifact.kind.padEnd(10)} ${artifact.label} — ${artifact.file}`).join('\n');
-        throw new Error(`No matching artifact on the ${sideName} side of test ${detail.ordinal}. Available:\n${available || '  (none)'}`);
-    }
-    await verifyOpenCommand(runSelector, pick.file, { ...options, live: false });
-}
-/** Copy an artifact to destDir (from the run directory, else the control plane). Returns the local path or null. */
-async function materializeArtifact(run, repoRoot, server, fileName, destDir) {
-    const dest = path.join(destDir, fileName);
-    const localRunDir = repoRoot ? runDir(repoRoot, run.runId) : null;
-    if (localRunDir) {
-        for (const chapter of run.chapters) {
-            const candidate = path.join(localRunDir, 'chapters', chapter.chapterId, 'artifacts', fileName);
-            if (fs.existsSync(candidate)) {
-                fs.mkdirSync(destDir, { recursive: true });
-                fs.copyFileSync(candidate, dest);
-                return dest;
-            }
-        }
-    }
-    for (const chapter of run.chapters) {
-        const url = `${server}/api/cloud-verifier/runs/${run.runId}/artifacts/${encodeURIComponent(`${chapter.chapterId}/artifacts/${fileName}`)}`;
-        const response = await fetch(url, { headers: verifyAuthHeaders() });
-        if (!response.ok)
-            continue;
-        fs.mkdirSync(destDir, { recursive: true });
-        fs.writeFileSync(dest, Buffer.from(await response.arrayBuffer()));
-        return dest;
-    }
-    return null;
-}
-const escapeHtml = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-/**
- * The same viewer as the results page (CloudVerifierPage RenderCompare): one
- * fixed frame per step whose content is swapped in place — 1 "what changed"
- * (computed magenta diff), 2 "before", 3 "after"; arrow keys step. Comparing
- * two near-identical images is a question about the same pixels, so the thing
- * to change is what occupies them; making the eye travel between copies is
- * precisely what hides a subtle difference. The magenta diff is computed
- * client-side with the product's algorithm: channel delta > 12 → magenta
- * (a colour no real interface ships), everything else lightened toward white.
- */
-function renderDiffHtml(detail, steps, videos) {
-    const stepSections = steps.map(step => {
-        const badge = step.identical === null
-            ? '<span class="badge missing">one side missing</span>'
-            : step.identical
-                ? '<span class="badge same">pixel-identical</span>'
-                : '<span class="badge diff">differs</span>';
-        return `
-    <section class="step" data-base="${step.base ?? ''}" data-head="${step.head ?? ''}">
-      <h2>step ${step.ordinal}: ${escapeHtml(step.name)} ${badge}</h2>
-      <nav class="render-jump" aria-label="Which render to show"></nav>
-      <figure>
-        <figcaption></figcaption>
-        <div class="frame"></div>
-      </figure>
-    </section>`;
-    }).join('\n');
-    const videoSection = videos.base || videos.head ? `
-  <section>
-    <h2>full visit</h2>
-    <div class="videos">
-      <div class="pane"><h3>before</h3>${videos.base ? `<video controls muted src="${encodeURI(videos.base)}"></video>` : '<div class="missing-pane">no base video</div>'}</div>
-      <div class="pane"><h3>after</h3>${videos.head ? `<video controls muted src="${encodeURI(videos.head)}"></video>` : '<div class="missing-pane">no head video</div>'}</div>
-    </div>
-  </section>` : '';
-    return `<!doctype html>
-<html><head><meta charset="utf-8"><title>${escapeHtml(detail.run_id)} — test ${detail.ordinal} screenshot diff</title>
-<style>
-  body { font: 14px -apple-system, system-ui, sans-serif; margin: 24px; background: #111; color: #ddd; }
-  h1 { font-size: 18px; } h2 { font-size: 15px; margin: 28px 0 8px; } h3 { font-size: 12px; color: #999; margin: 4px 0; }
-  .badge { font-size: 11px; padding: 2px 8px; border-radius: 10px; margin-left: 8px; vertical-align: middle; }
-  .same { background: #14432a; color: #7bd88f; } .diff { background: #4a2a12; color: #f0a45d; } .missing { background: #333; color: #aaa; }
-  .render-jump { display: flex; gap: 6px; align-items: center; margin: 6px 0; }
-  .render-jump button { background: #222; color: #ddd; border: 1px solid #444; border-radius: 4px; padding: 4px 10px; cursor: pointer; display: inline-flex; gap: 6px; align-items: center; }
-  .render-jump button[aria-pressed="true"] { background: #2d4a7a; border-color: #4a7ab5; }
-  .render-jump kbd { background: #111; border: 1px solid #555; border-radius: 3px; padding: 0 5px; font-size: 11px; }
-  .render-jump .hint { color: #777; font-size: 12px; margin-left: 8px; }
-  figure { margin: 0; } figcaption { font-size: 11px; letter-spacing: 0.06em; color: #999; margin: 4px 0; }
-  .frame img { width: 100%; border: 1px solid #333; border-radius: 4px; display: block; }
-  .pending, .missing-pane { padding: 40px; border: 1px dashed #444; border-radius: 4px; color: #777; text-align: center; }
-  .videos { display: flex; gap: 12px; } .videos .pane { flex: 1; min-width: 0; } video { width: 100%; border: 1px solid #333; border-radius: 4px; display: block; }
-  .meta { color: #888; }
-</style></head>
-<body>
-<h1>test ${detail.ordinal}: ${escapeHtml(detail.title)}</h1>
-<p class="meta">${escapeHtml(detail.run_id)} · ${escapeHtml(detail.chapter_id)} · ${detail.status}${detail.verdict ? ` · ${escapeHtml(detail.verdict)}` : ''}</p>
-${stepSections}
-${videoSection}
-<script>
-  const DELTA = 12;
-  const load = src => new Promise((resolve, reject) => {
-    const image = new Image();
-    image.onload = () => resolve(image);
-    image.onerror = () => reject(new Error('could not load image'));
-    image.src = src;
-  });
-
-  // The product's diff render: magenta where the pixels moved, everything
-  // else washed toward white so the magenta is unmissable.
-  async function diffRender(baseSrc, headSrc) {
-    const [before, after] = await Promise.all([load(baseSrc), load(headSrc)]);
-    // Renders of different sizes cannot be compared pixel for pixel; show
-    // nothing rather than paint a misleading picture.
-    if (before.naturalWidth !== after.naturalWidth || before.naturalHeight !== after.naturalHeight) return null;
-    const width = after.naturalWidth, height = after.naturalHeight;
-    const read = image => {
-      const canvas = document.createElement('canvas');
-      canvas.width = width; canvas.height = height;
-      const context = canvas.getContext('2d');
-      context.drawImage(image, 0, 0);
-      return context.getImageData(0, 0, width, height);
-    };
-    const previous = read(before).data;
-    const out = read(after);
-    const data = out.data;
-    for (let i = 0; i < data.length; i += 4) {
-      const delta = Math.max(
-        Math.abs(data[i] - previous[i]),
-        Math.abs(data[i + 1] - previous[i + 1]),
-        Math.abs(data[i + 2] - previous[i + 2]),
-      );
-      if (delta > DELTA) { data[i] = 255; data[i + 1] = 0; data[i + 2] = 200; }
-      else {
-        data[i] = data[i] + (255 - data[i]) * 0.55;
-        data[i + 1] = data[i + 1] + (255 - data[i + 1]) * 0.55;
-        data[i + 2] = data[i + 2] + (255 - data[i + 2]) * 0.55;
-      }
-    }
-    const canvas = document.createElement('canvas');
-    canvas.width = width; canvas.height = height;
-    canvas.getContext('2d').putImageData(out, 0, 0);
-    return canvas.toDataURL('image/png');
-  }
-
-  const stepStates = [];
-  let view = 0;
-
-  function paint() {
-    for (const state of stepStates) {
-      const current = state.renders[Math.min(view, state.renders.length - 1)];
-      state.nav.replaceChildren(...state.renders.map((render, index) => {
-        const button = document.createElement('button');
-        button.type = 'button';
-        button.setAttribute('aria-pressed', String(render === current));
-        const kbd = document.createElement('kbd');
-        kbd.textContent = String(index + 1);
-        button.append(kbd, render.label);
-        button.addEventListener('click', () => { view = index; paint(); });
-        return button;
-      }));
-      const hint = document.createElement('span');
-      hint.className = 'hint';
-      hint.textContent = 'press a key, or \u2190 \u2192 to step';
-      state.nav.append(hint);
-      state.caption.textContent = current.caption;
-      state.frame.replaceChildren();
-      if (current.url) {
-        const image = document.createElement('img');
-        image.alt = current.key;
-        image.src = current.url;
-        state.frame.append(image);
-      } else {
-        const pending = document.createElement('div');
-        pending.className = 'pending';
-        pending.textContent = current.key === 'differences' ? 'Comparing the two renders\u2026' : 'Screenshot missing';
-        state.frame.append(pending);
-      }
-    }
-  }
-
-  for (const section of document.querySelectorAll('section.step')) {
-    const base = section.dataset.base || null;
-    const head = section.dataset.head || null;
-    const state = {
-      nav: section.querySelector('.render-jump'),
-      caption: section.querySelector('figcaption'),
-      frame: section.querySelector('.frame'),
-      renders: [
-        ...(base && head ? [{ key: 'differences', label: 'what changed', caption: 'WHAT CHANGED \u00b7 comparing\u2026', url: null }] : []),
-        { key: 'before', label: 'before', caption: 'BEFORE \u00b7 without the change', url: base ?? undefined },
-        { key: 'after', label: 'after', caption: 'AFTER \u00b7 with the change', url: head ?? undefined },
-      ],
-    };
-    stepStates.push(state);
-    if (base && head) {
-      diffRender(base, head).then(url => {
-        if (url) {
-          state.renders[0].url = url;
-          state.renders[0].caption = 'WHAT CHANGED \u00b7 everything in magenta';
-        } else {
-          // Sizes differ: drop the computed render rather than mislead.
-          state.renders.shift();
-        }
-        paint();
-      }).catch(() => { state.renders.shift(); paint(); });
-    }
-  }
-
-  window.addEventListener('keydown', event => {
-    if (event.metaKey || event.ctrlKey || event.altKey) return;
-    const target = event.target;
-    if (target && /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName)) return;
-    const index = ['1', '2', '3'].indexOf(event.key);
-    if (index >= 0) view = index;
-    else if (event.key === 'ArrowLeft') view = Math.max(0, view - 1);
-    else if (event.key === 'ArrowRight') view = Math.min(2, view + 1);
-    else return;
-    event.preventDefault();
-    paint();
-  });
-
-  paint();
-</script>
-</body></html>`;
-}
-/**
- * Build the screenshot-diff page for one test and report which steps differ
- * byte-for-byte. Shared by `haystack verify diff` and the MCP verify_diff tool.
- */
-export async function buildScreenshotDiff(options) {
-    const { server, repoRoot } = options;
-    const loaded = await loadRunAuto({ server, repoRoot, selector: options.runSelector });
-    const match = findCell(loaded.run, options.cellSelector);
-    const detail = cellDetail(loaded.run, match, { timeline: false });
-    const outDir = path.resolve(options.outDir
-        || path.join(os.tmpdir(), 'haystack-verify-diff', `${detail.run_id}-cell-${detail.ordinal}`));
-    const assetsDir = path.join(outDir, 'assets');
-    const stepOf = (label) => {
-        const parsed = label.match(/^step (\d+): (.*)$/);
-        return parsed ? { ordinal: Number(parsed[1]), name: parsed[2] } : null;
-    };
-    const shotsBySide = (side) => {
-        const shots = new Map();
-        for (const artifact of side.artifacts) {
-            if (artifact.kind !== 'screenshot')
-                continue;
-            const step = stepOf(artifact.label);
-            if (step)
-                shots.set(step.ordinal, { name: step.name, file: artifact.file });
-        }
-        return shots;
-    };
-    const baseShots = shotsBySide(detail.base);
-    const headShots = shotsBySide(detail.head);
-    const wantStep = options.step ?? null;
-    const ordinals = [...new Set([...baseShots.keys(), ...headShots.keys()])]
-        .filter(ordinal => wantStep === null || ordinal === wantStep)
-        .sort((a, b) => a - b);
-    if (ordinals.length === 0) {
-        const stillRunning = !['passed', 'failed', 'infra_error', 'inconclusive'].includes(detail.status);
-        throw new Error(wantStep !== null
-            ? `No screenshots at step ${wantStep}. Steps with screenshots: ${[...new Set([...baseShots.keys(), ...headShots.keys()])].sort((a, b) => a - b).join(', ') || '(none)'}`
-            : stillRunning
-                ? `Test ${detail.ordinal} is still ${detail.status} — screenshots appear once its flow has run. Wait for the run (verify watch / verify_wait) and retry.`
-                : `Test ${detail.ordinal} has no step screenshots to compare.`);
-    }
-    // Screenshots are embedded as data: URIs — the page computes the magenta
-    // "what changed" render on a canvas, and file:// images would taint it.
-    const dataUri = (file) => `data:image/png;base64,${fs.readFileSync(file).toString('base64')}`;
-    const sha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-    const steps = [];
-    const reported = [];
-    for (const ordinal of ordinals) {
-        const basePick = baseShots.get(ordinal) ?? null;
-        const headPick = headShots.get(ordinal) ?? null;
-        const baseLocal = basePick ? await materializeArtifact(loaded.run, repoRoot, server, basePick.file, assetsDir) : null;
-        const headLocal = headPick ? await materializeArtifact(loaded.run, repoRoot, server, headPick.file, assetsDir) : null;
-        const name = (headPick ?? basePick)?.name ?? `step ${ordinal}`;
-        const identical = baseLocal && headLocal ? sha256(baseLocal) === sha256(headLocal) : null;
-        steps.push({
-            ordinal,
-            name,
-            base: baseLocal ? dataUri(baseLocal) : null,
-            head: headLocal ? dataUri(headLocal) : null,
-            identical,
-        });
-        reported.push({ ordinal, name, identical });
-    }
-    const videoFile = (side) => side.artifacts.find(artifact => artifact.kind === 'video')?.file ?? null;
-    const baseVideoName = videoFile(detail.base);
-    const headVideoName = videoFile(detail.head);
-    const baseVideo = wantStep === null && baseVideoName ? await materializeArtifact(loaded.run, repoRoot, server, baseVideoName, assetsDir) : null;
-    const headVideo = wantStep === null && headVideoName ? await materializeArtifact(loaded.run, repoRoot, server, headVideoName, assetsDir) : null;
-    const htmlPath = path.join(outDir, 'index.html');
-    fs.mkdirSync(outDir, { recursive: true });
-    fs.writeFileSync(htmlPath, renderDiffHtml(detail, steps, {
-        base: baseVideo ? path.join('assets', path.basename(baseVideo)) : null,
-        head: headVideo ? path.join('assets', path.basename(headVideo)) : null,
-    }));
-    return {
-        html: htmlPath,
-        steps: reported,
-        differing: reported.filter(step => step.identical === false).length,
-        identical: reported.filter(step => step.identical === true).length,
-        detail,
-    };
-}
-/**
- * Build and open the base-vs-head screenshot differ for one test — the same
- * viewer as the results page: 1 what changed / 2 before / 3 after, swapped in
- * place, with arrow keys stepping.
- */
-export async function verifyDiffCommand(runSelector, cellSelector, options) {
-    if (options.step && Number.isNaN(Number(options.step)))
-        throw new Error('--step takes a number');
-    setVerifyToken(options.token);
-    const result = await buildScreenshotDiff({
-        server: resolveServer(options.server),
-        repoRoot: discoverVerifyRoot(options.repoRoot),
-        runSelector,
-        cellSelector,
-        step: options.step ? Number(options.step) : undefined,
-        outDir: options.out,
-    });
-    if (options.json) {
-        emitJson({
-            schema_version: '1.0.0',
-            run_id: result.detail.run_id,
-            ordinal: result.detail.ordinal,
-            html: result.html,
-            steps: result.steps,
-            differing: result.differing,
-            identical: result.identical,
-        });
-    }
-    else {
-        console.log(`${chalk.green('✓')} diff ready: ${result.steps.length} step(s) — ${result.differing > 0 ? `${chalk.yellow(`${result.differing} differ`)}${result.identical > 0 ? chalk.dim(`, ${result.identical} identical`) : ''}` : chalk.green('all pixel-identical')}`);
-        console.log(chalk.dim(`  ${result.html} — 1 what changed · 2 before · 3 after`));
-    }
-    if (options.open !== false && !options.json)
-        launch(result.html);
-}
-export async function requestUniverseCleanupStatus(server, forkId) {
-    const response = await fetch(`${server}/api/cloud-verifier/universes/${encodeURIComponent(forkId)}/cleanup`, { headers: verifyAuthHeaders() });
-    if (!response.ok) {
-        let detail = '';
-        try {
-            const body = await response.json();
-            if (typeof body.error === 'string')
-                detail = `: ${body.error}`;
-        }
-        catch { /* status is sufficient */ }
-        throw new Error(`Could not read retained-state cleanup (HTTP ${response.status})${detail}`);
-    }
-    return await response.json();
-}
-export async function verifyCleanupCommand(runSelector, cellSelector, options) {
-    setVerifyToken(options.token);
-    if (options.side && options.side !== 'base' && options.side !== 'head') {
-        throw new Error('--side must be base or head');
-    }
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector });
-    const match = findCellByStableSelector(loaded.run, cellSelector);
-    const side = options.side === 'base' ? 'base' : 'head';
-    const universe = side === 'base' ? match.cell.base : match.cell.head;
-    if (!universe.forkId) {
-        throw new Error(`Test ${match.cell.ordinal}'s ${side} universe has no durable fork ID.`);
-    }
-    const cleanup = await requestUniverseCleanupStatus(server, universe.forkId);
-    const output = {
-        schema_version: '1.0.0',
-        run_id: loaded.run.runId,
-        ordinal: match.cell.ordinal,
-        side,
-        ...cleanup,
-    };
-    if (options.json) {
-        emitJson(output);
-    }
-    else {
-        const glyph = cleanup.status === 'complete'
-            ? chalk.green('✓')
-            : cleanup.status === 'missed'
-                ? chalk.red('✗')
-                : cleanup.status === 'pending'
-                    ? chalk.yellow('◷')
-                    : chalk.cyan('·');
-        console.log(`${glyph} ${chalk.bold(cleanup.status)} cleanup for test `
-            + `${match.cell.ordinal}'s ${side} universe`);
-        console.log(chalk.dim(`  fork ${cleanup.forkId} · catalog ${cleanup.catalogStatus} · checked ${cleanup.checkedAt}`));
-        for (const resource of cleanup.resources) {
-            const region = resource.resource.kind === 'archil-disk'
-                ? ` · ${resource.resource.region}`
-                : '';
-            console.log(`  ${resource.resource.kind} ${chalk.cyan(resource.resource.id)}`
-                + `${chalk.dim(region)} — ${resource.status}, `
-                + `${resource.referenceCount} reference(s), `
-                + `${resource.deleteAttempts} delete attempt(s)`);
-            console.log(chalk.dim(`    exact id ${resource.resourceIdentity}`));
-            if (resource.deletion) {
-                console.log(chalk.dim(`    deletion ${resource.deletion.status}; `
-                    + `deadline ${resource.deletion.deadlineAt}`
-                    + (resource.deletion.deletedAt
-                        ? `; confirmed ${resource.deletion.deletedAt}`
-                        : '')));
-            }
-        }
-    }
-    if (cleanup.status === 'missed')
-        process.exitCode = 2;
-}
-export async function requestUniverseReopen(server, forkId) {
-    const response = await fetch(`${server}/api/cloud-verifier/universes/${encodeURIComponent(forkId)}/reopen`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', ...verifyAuthHeaders() },
-        body: '{}',
-    });
-    if (!response.ok) {
-        let detail = '';
-        try {
-            const body = await response.json();
-            if (typeof body.error === 'string')
-                detail = `: ${body.error}`;
-        }
-        catch { /* status is sufficient */ }
-        throw new Error(`Could not reopen retained universe (HTTP ${response.status})${detail}`);
-    }
-    return await response.json();
-}
-export async function requestUniverseRefork(server, forkId, sandboxId, childKey) {
-    const response = await fetch(`${server}/api/cloud-verifier/universes/${encodeURIComponent(forkId)}`
-        + `/attachments/${encodeURIComponent(sandboxId)}/refork`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', ...verifyAuthHeaders() },
-        body: JSON.stringify({ childKey }),
-    });
-    if (!response.ok) {
-        let detail = '';
-        try {
-            const body = await response.json();
-            if (typeof body.error === 'string')
-                detail = `: ${body.error}`;
-        }
-        catch { /* status is sufficient */ }
-        throw new Error(`Could not refork retained universe (HTTP ${response.status})${detail}`);
-    }
-    return await response.json();
-}
-function validateOperatorSide(side) {
-    if (side && side !== 'base' && side !== 'head') {
-        throw new Error('--side must be base or head');
-    }
-    return side === 'base' ? 'base' : 'head';
-}
-function isStructuredArchilForkId(value) {
-    return /^archil:[A-Za-z0-9_-]+:branch:[A-Za-z0-9._-]+$/.test(value);
-}
-export async function resolveRetainedUniverseTarget(options) {
-    if (isStructuredArchilForkId(options.source)) {
-        if (options.cellSelector) {
-            throw new Error('An exact Archil fork ID does not take a test selector.');
-        }
-        if (options.side) {
-            throw new Error('--side only applies when selecting state from a run.');
-        }
-        return {
-            forkId: options.source,
-            runId: null,
-            ordinal: null,
-            side: null,
-        };
-    }
-    if (options.source.startsWith('archil:')) {
-        throw new Error('Invalid structured Archil fork ID; expected '
-            + 'archil:<disk-id>:branch:<branch-id>.');
-    }
-    if (!options.cellSelector) {
-        throw new Error('A test selector is required when the source is a run. '
-            + 'Use an ordinal, riskCellId, or exact planner cellKey.');
-    }
-    const side = validateOperatorSide(options.side);
-    const loaded = await loadRunAuto({
-        server: options.server,
-        repoRoot: options.repoRoot,
-        selector: options.source,
-    });
-    const match = findCellByStableSelector(loaded.run, options.cellSelector);
-    const universe = side === 'base' ? match.cell.base : match.cell.head;
-    if (universe.stateProvider !== 'archil' || !universe.forkId) {
-        throw new Error(`Test ${match.cell.ordinal}'s ${side} universe has no retained Archil state.`);
-    }
-    if (universe.stateExpiresAt
-        && Date.parse(universe.stateExpiresAt) <= Date.now()) {
-        throw new Error(`Test ${match.cell.ordinal}'s retained state expired at `
-            + `${universe.stateExpiresAt}.`);
-    }
-    return {
-        forkId: universe.forkId,
-        runId: loaded.run.runId,
-        ordinal: match.cell.ordinal,
-        side,
-    };
-}
-export async function reforkRetainedUniverse(server, target, childKey) {
-    const reopened = await requestUniverseReopen(server, target.forkId);
-    try {
-        const reforked = await requestUniverseRefork(server, target.forkId, reopened.sandboxId, childKey);
-        if (reforked.parentForkId !== target.forkId) {
-            throw new Error(`Control plane reforked unexpected parent ${reforked.parentForkId}; `
-                + `expected ${target.forkId}.`);
-        }
-        return { reopened, reforked };
-    }
-    catch (error) {
-        // A newly created attachment exists only to service this command. Reclaim
-        // it on a pre-checkpoint failure; never tear down a reused attachment that
-        // an operator may still be inspecting or mutating.
-        if (!reopened.reused) {
-            await fetch(`${server}/api/cloud-verifier/universes/`
-                + `${encodeURIComponent(target.forkId)}/attachments/`
-                + `${encodeURIComponent(reopened.sandboxId)}/release`, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    ...verifyAuthHeaders(),
-                },
-                body: '{}',
-            }).catch(() => undefined);
-        }
-        throw error;
-    }
-}
-export async function verifyReopenCommand(source, cellSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const target = await resolveRetainedUniverseTarget({
-        server,
-        repoRoot,
-        source,
-        cellSelector,
-        side: options.side,
-    });
-    const reopened = await requestUniverseReopen(server, target.forkId);
-    const output = {
-        schema_version: '1.0.0',
-        run_id: target.runId,
-        ordinal: target.ordinal,
-        side: target.side,
-        ...reopened,
-    };
-    if (options.json) {
-        emitJson(output);
-        return;
-    }
-    console.log(`${chalk.green('✓')} ${reopened.reused ? 'using' : 'reopened'} retained universe `
-        + `${chalk.cyan(reopened.forkId)} on sandbox ${chalk.cyan(reopened.sandboxId)}`);
-    console.log(chalk.dim(`  compute expires ${reopened.expiresAt}; state expires ${reopened.stateExpiresAt}`));
-    console.log(`  e2b sandbox connect ${reopened.sandboxId}`);
-    if (reopened.browserUrl) {
-        console.log(`  ${reopened.browserUrl}`);
-        if (options.openBrowser)
-            launch(reopened.browserUrl);
-    }
-}
-export async function verifyReforkCommand(source, cellOrChildKey, requestedChildKey, options) {
-    setVerifyToken(options.token);
-    const directFork = source.startsWith('archil:');
-    const cellSelector = directFork ? undefined : cellOrChildKey;
-    const childKey = directFork ? cellOrChildKey : requestedChildKey;
-    if (!childKey) {
-        throw new Error('A structured child key is required (for example attempt:checkout-fix-2).');
-    }
-    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(childKey)) {
-        throw new Error('Child key must start with a letter or number and contain at most 128 '
-            + 'letters, numbers, dots, underscores, colons, or hyphens.');
-    }
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const target = await resolveRetainedUniverseTarget({
-        server,
-        repoRoot,
-        source,
-        cellSelector,
-        side: options.side,
-    });
-    const { reopened, reforked } = await reforkRetainedUniverse(server, target, childKey);
-    const output = {
-        schema_version: '1.0.0',
-        run_id: target.runId,
-        ordinal: target.ordinal,
-        side: target.side,
-        child_key: childKey,
-        attachment_sandbox_id: reopened.sandboxId,
-        reused_attachment: reopened.reused,
-        ...reforked,
-    };
-    if (options.json) {
-        emitJson(output);
-        return;
-    }
-    console.log(`${chalk.green('✓')} reforked retained universe for `
-        + `${target.ordinal === null ? chalk.cyan(target.forkId) : `test ${target.ordinal}'s ${target.side} side`}`);
-    console.log(chalk.dim(`  parent ${reforked.parentForkId}`));
-    console.log(`  child  ${chalk.cyan(reforked.forkId)}`);
-    console.log(chalk.dim(`  checkpoint ${reforked.checkpointName}; state expires `
-        + `${reforked.stateExpiresAt}`));
-    console.log(`  haystack verify reopen ${reforked.forkId}`);
-}
-/**
- * Drop a terminal into a test's live universe via the E2B CLI. Only failing
- * tests keep a universe alive. An expired Archil-backed compute attachment is
- * transparently replaced while its durable state is still retained.
- */
-export async function verifyShellCommand(runSelector, cellSelector, options) {
-    setVerifyToken(options.token);
-    const server = resolveServer(options.server);
-    const repoRoot = discoverVerifyRoot(options.repoRoot);
-    const loaded = await loadRunAuto({ server, repoRoot, selector: runSelector });
-    const match = findCellByStableSelector(loaded.run, cellSelector);
-    const side = validateOperatorSide(options.side);
-    const universe = side === 'base' ? match.cell.base : match.cell.head;
-    if (!universe.sandboxId && (!universe.forkId || universe.stateProvider !== 'archil')) {
-        throw new Error(`Test ${match.cell.ordinal} has no ${options.side ?? 'head'} sandbox recorded.`);
-    }
-    const goneError = new Error(`Test ${match.cell.ordinal}'s universe is no longer running (failing tests keep one for 90 minutes). Re-run the chapter, then shell in.`);
-    // Ask E2B whether the sandbox is actually alive — run.json can say `running`
-    // for a universe that has since expired or been reclaimed. If the API is not
-    // reachable, fall back to what the run recorded.
-    let sandboxId = universe.sandboxId ?? '';
-    let confirmedRunning = null;
-    try {
-        const { listE2BSandboxes, resolveE2BApiKey } = await import('./verify-sandboxes.js');
-        confirmedRunning = sandboxId
-            ? (await listE2BSandboxes(resolveE2BApiKey()))
-                .some(sandbox => sandbox.sandboxId === sandboxId)
-            : false;
-    }
-    catch {
-        confirmedRunning = null;
-    }
-    let reopened = null;
-    const recordedLive = universe.status === 'running'
-        && (!universe.expiresAt || Date.parse(universe.expiresAt) > Date.now());
-    const shouldReopen = confirmedRunning === false
-        || (confirmedRunning === null && !recordedLive);
-    if (shouldReopen) {
-        if (universe.stateProvider !== 'archil'
-            || !universe.forkId
-            || (universe.stateExpiresAt
-                && Date.parse(universe.stateExpiresAt) <= Date.now())) {
-            throw goneError;
-        }
-        reopened = await requestUniverseReopen(server, universe.forkId);
-        sandboxId = reopened.sandboxId;
-        confirmedRunning = true;
-    }
-    if (confirmedRunning === null) {
-        if (!recordedLive)
-            throw goneError;
-    }
-    const appUrl = reopened?.browserUrl
-        ?? universe.browserUrl
-        ?? match.cell.head.browserUrl
-        ?? null;
-    console.error(chalk.dim(`Connecting to sandbox ${sandboxId} (universe of test ${match.cell.ordinal}, ${side} side${reopened ? '; reopened from retained Archil state' : ''}${appUrl ? `; app at ${appUrl}` : ''}). The app lives under /home/user/universe.`));
-    if (!process.stdin.isTTY) {
-        // Not interactive — hand the operator the command instead of hanging.
-        console.log(`e2b sandbox connect ${sandboxId}`);
-        return;
-    }
-    try {
-        await new Promise((resolve, reject) => {
-            const child = spawn('e2b', ['sandbox', 'connect', sandboxId], { stdio: 'inherit' });
-            child.on('error', error => reject(new Error(`Could not run the e2b CLI (${error.message}). Install it (npm i -g @e2b/cli) or connect manually: e2b sandbox connect ${sandboxId}`)));
-            child.on('close', () => resolve());
-        });
-    }
-    finally {
-        if (reopened && universe.forkId) {
-            await fetch(`${server}/api/cloud-verifier/universes/${encodeURIComponent(universe.forkId)}/attachments/${encodeURIComponent(sandboxId)}/release`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json', ...verifyAuthHeaders() },
-                body: '{}',
-            }).catch(() => undefined);
-        }
-    }
-}