@inflexa-ai/harness 0.1.1

package/dist/execution/post-step.js

@@ -0,0 +1,65 @@
+/**
+ * Post-step helper — disk-walk of a step's writable artifact directory.
+ *
+ * The step's runtime input/script lineage rides on the step-scoped
+ * `ProvenanceCollector` the sandbox-step body threads through
+ * `PostStepContext` (fed per-exec during the agent loop). This module only
+ * owns the manifest source: walking the writable step dir and hashing each
+ * file from disk.
+ */
+import { readdir, stat as fsStat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { inferArtifactType } from "../schemas/artifact-manifest.js";
+import { computeSha256File } from "../lib/fs-helpers.js";
+import { IGNORED_DIRS } from "../sandbox/ignored-dirs.js";
+/**
+ * Walk a step's writable artifact directory and produce a fully-hashed
+ * `ArtifactManifestEntry[]`. Skips IGNORED_DIRS. Paths are relative to
+ * `writePrefix`.
+ */
+export async function walkStepArtifacts(args) {
+    const { writePrefix, stepId, runId } = args;
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const relPath = relative(writePrefix, full);
+            let info;
+            try {
+                info = await fsStat(full);
+            }
+            catch {
+                continue;
+            }
+            const hash = await computeSha256File(full);
+            out.push({
+                stepId,
+                runId,
+                path: relPath,
+                size: info.size,
+                type: inferArtifactType(relPath),
+                hash,
+            });
+        }
+    }
+    await walk(writePrefix);
+    return out;
+}

package/dist/execution/reconcile-manifest.d.ts

@@ -0,0 +1,25 @@
+import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
+import type { ProvenanceCollector } from "../provenance/collector.js";
+export interface ReconcileManifestInput {
+    /** Absolute host root of the analysis's workspace tree. */
+    workspaceRoot: string;
+    /** Analysis (resource) ID. */
+    resourceId: string;
+    /** Run ID owning this step. */
+    runId: string;
+    /** Step ID — the writable mount segment for this step's artifacts. */
+    stepId: string;
+    /** Agent ID — used for metric tagging only. */
+    agentId: string;
+    /** Draft manifest from `buildManifestFromCollector`. */
+    manifest: ArtifactManifestEntry[];
+    /** Collector backing the manifest; mutated to reflect drops/rehashes. */
+    collector: ProvenanceCollector;
+}
+export interface ReconcileManifestResult {
+    /** Reconciled manifest — phantoms removed, every entry rehashed from disk. */
+    manifest: ArtifactManifestEntry[];
+    /** Number of entries dropped because their file was missing. */
+    droppedCount: number;
+}
+export declare function reconcileManifestWithDisk(input: ReconcileManifestInput): Promise<ReconcileManifestResult>;

package/dist/execution/reconcile-manifest.js

@@ -0,0 +1,132 @@
+/**
+ * Reconcile a step's artifact manifest against the on-disk workspace tree.
+ *
+ * Runs after the sandbox is destroyed and before any artifact is synced to
+ * permanent storage. Two responsibilities:
+ *
+ *   1. Drop phantom entries — `ProvenanceCollector` records writes but not
+ *      deletions, so an agent that writes-then-deletes (or a sandbox-side
+ *      `rm`/`mv`) leaves entries pointing at files that no longer exist.
+ *      Phantoms are dropped from the manifest and removed from the
+ *      collector so the structured registration payload agrees.
+ *
+ *   2. Hash + size every surviving entry from disk. The exec frame that
+ *      `feedExecFrame` folds in reports write paths without a content hash,
+ *      and any hash taken at frame time would be racy with respect to what
+ *      the file becomes by the time it's registered (long-running scripts
+ *      flush after the frame fires; atomic-rename patterns swap content
+ *      under a stable byte count). Hashing here makes
+ *      `study.artifacts.hash` equal `sha256sum` of the bytes the sync target
+ *      will receive at upload time — the equivalence `SyncConfirm` checks.
+ */
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
+import { artifactReconcileDropped } from "../lib/metrics.js";
+export async function reconcileManifestWithDisk(input) {
+    const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
+    const stepRoot = path.join(workspaceRoot, "runs", runId, stepId);
+    const reconciled = [];
+    let droppedCount = 0;
+    for (const entry of manifest) {
+        const absPath = path.join(stepRoot, entry.path);
+        // Bounds check: an entry.path containing `..` segments resolves
+        // outside stepRoot (e.g. `../../etc/passwd` → `/etc/passwd`). Without
+        // this guard a stat outside the step's writable mount could either
+        // ENOENT and silently drop a real artifact, or — worse — succeed
+        // against a host file the step never produced.
+        if (!absPath.startsWith(stepRoot + path.sep) && absPath !== stepRoot) {
+            console.warn(`[reconcile-manifest] skipping out-of-bounds path=${entry.path} stepId=${stepId} runId=${runId}`);
+            continue;
+        }
+        let info;
+        try {
+            info = await stat(absPath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                console.debug(`[reconcile-manifest] dropping phantom path=${entry.path} stepId=${stepId} runId=${runId}`);
+                collector.removeRecord(entry.path);
+                droppedCount++;
+                artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+                continue;
+            }
+            throw err;
+        }
+        // Drop directories — they can slip in via tracer frames that don't
+        // distinguish file vs directory writes (e.g. `mkdir`). `computeSha256File`
+        // uses `createReadStream`, which throws `EISDIR` on directories and would
+        // fail the whole step's reconciliation.
+        if (!info.isFile()) {
+            console.debug(`[reconcile-manifest] dropping non-file path=${entry.path} stepId=${stepId} runId=${runId}`);
+            collector.removeRecord(entry.path);
+            droppedCount++;
+            artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+            continue;
+        }
+        // The registration payload reads output hashes from `entries` (this
+        // returned manifest), not from the collector — the managed registration
+        // adapter builds the structured payload from it. So we
+        // don't need to mirror the rehash back into the collector; the
+        // collector's outputHash for an output path goes unread after this.
+        const hash = await computeSha256File(absPath);
+        reconciled.push({ ...entry, hash, size: info.size });
+    }
+    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId);
+    return { manifest: reconciled, droppedCount };
+}
+/**
+ * Content-attest the step's inputs (see the artifact-manifest spec). The path-only provenance frame
+ * gives every input ref an empty hash; inputs are immutable for the step (the
+ * analysis tree is mounted read-only, the step writes only under its own
+ * `runs/{runId}/{stepId}`), so a hash from disk now equals the bytes the script
+ * read. Mutates the live refs in place — they are shared with the records the
+ * registration payload reads.
+ *
+ * `artifacts`-source reads are the step's OWN files (mutating, dropped by the
+ * registration translator), so they are not attested and not hashed here.
+ * Lineage attestation is fail-fast: an input we cannot hash (gone, or resolving
+ * outside the analysis tree) throws rather than registering a hashless edge.
+ */
+async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId) {
+    const resourceRoot = path.resolve(workspaceRoot);
+    for (const ref of collector.getTrackedInputs()) {
+        if (ref.source === "artifacts")
+            continue;
+        if (hasValidContentHash(ref.hash))
+            continue;
+        // `ref.path` is the absolute container path `/{resourceId}/...`; strip the
+        // mount segment and map the tail onto the host workspace root. `path.join`
+        // normalizes any `..`, and the bound confines the read to the analysis tree.
+        const containerPrefix = `/${resourceId}`;
+        if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
+            throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
+        }
+        const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
+        if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
+            throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
+        }
+        let info;
+        try {
+            info = await stat(hostPath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error(`[reconcile-manifest] cannot attest input ${ref.path}: not present at reconcile (stepId=${stepId} runId=${runId})`, {
+                    cause: err,
+                });
+            }
+            throw err;
+        }
+        if (!info.isFile()) {
+            // A directory read (e.g. `ls` / `list.files` of a mount) is tracked by
+            // the inotify frame but is not a content-attestable file artifact. Drop
+            // it from lineage rather than failing the step — mirrors the output-side
+            // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
+            // as drift; a directory is not drift.
+            collector.dropInput(ref);
+            continue;
+        }
+        ref.hash = await computeSha256File(hostPath);
+    }
+}

package/dist/execution/report-render.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Report renderer — Node-side Nunjucks render of v{N}/report.html.j2 to v{N}/index.html.
+ *
+ * Stateless pure module: no harness imports, no env reads at import time,
+ * safe to run standalone in tests.
+ */
+export interface RenderReportOptions {
+    versionDir: string;
+    templatesDir: string;
+}
+export interface RenderReportResult {
+    ok: boolean;
+    indexBytes: number;
+    error?: {
+        kind: "missing-template" | "syntax" | "runtime";
+        message: string;
+        line?: number;
+        snippet?: string;
+    };
+}
+/**
+ * Render `${versionDir}/report.html.j2` to `${versionDir}/index.html`.
+ *
+ * Loader resolution order: [versionDir, templatesDir]. `report.html.j2`
+ * lives in versionDir; `extends "base.html.j2"` and `include "components/..."`
+ * resolve from templatesDir. Autoescape is OFF — templates own escaping.
+ *
+ * `${templatesDir}/echarts-theme.json` is read, parsed, re-stringified, and
+ * passed as `echarts_theme` (a JSON string) for safe inlining inside a
+ * `<script>` block.
+ *
+ * Returns `{ ok: true, indexBytes }` on success. On failure, returns
+ * `{ ok: false, indexBytes: 0, error }` with `error.kind`:
+ *   - "missing-template" — `report.html.j2` (or any `extends`/`include` target)
+ *      not found by either loader. Message identifies the missing path.
+ *   - "syntax" — Nunjucks parse error in any loaded template.
+ *   - "runtime" — anything else thrown during render or write.
+ */
+export declare function renderReport(opts: RenderReportOptions): Promise<RenderReportResult>;

package/dist/execution/report-render.js

@@ -0,0 +1,98 @@
+/**
+ * Report renderer — Node-side Nunjucks render of v{N}/report.html.j2 to v{N}/index.html.
+ *
+ * Stateless pure module: no harness imports, no env reads at import time,
+ * safe to run standalone in tests.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import nunjucks from "nunjucks";
+/**
+ * Render `${versionDir}/report.html.j2` to `${versionDir}/index.html`.
+ *
+ * Loader resolution order: [versionDir, templatesDir]. `report.html.j2`
+ * lives in versionDir; `extends "base.html.j2"` and `include "components/..."`
+ * resolve from templatesDir. Autoescape is OFF — templates own escaping.
+ *
+ * `${templatesDir}/echarts-theme.json` is read, parsed, re-stringified, and
+ * passed as `echarts_theme` (a JSON string) for safe inlining inside a
+ * `<script>` block.
+ *
+ * Returns `{ ok: true, indexBytes }` on success. On failure, returns
+ * `{ ok: false, indexBytes: 0, error }` with `error.kind`:
+ *   - "missing-template" — `report.html.j2` (or any `extends`/`include` target)
+ *      not found by either loader. Message identifies the missing path.
+ *   - "syntax" — Nunjucks parse error in any loaded template.
+ *   - "runtime" — anything else thrown during render or write.
+ */
+export async function renderReport(opts) {
+    const { versionDir, templatesDir } = opts;
+    let echartsThemeJson;
+    try {
+        const raw = await readFile(join(templatesDir, "echarts-theme.json"), "utf8");
+        echartsThemeJson = JSON.stringify(JSON.parse(raw));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const kind = isNotFound(err) ? "missing-template" : "runtime";
+        return {
+            ok: false,
+            indexBytes: 0,
+            error: { kind, message: `failed to load echarts-theme.json: ${msg}` },
+        };
+    }
+    const env = new nunjucks.Environment(new nunjucks.FileSystemLoader([versionDir, templatesDir], {
+        noCache: true,
+    }), { autoescape: false, throwOnUndefined: false });
+    let html;
+    try {
+        html = env.render("report.html.j2", { echarts_theme: echartsThemeJson });
+    }
+    catch (err) {
+        return { ok: false, indexBytes: 0, error: classifyNunjucksError(err) };
+    }
+    try {
+        const indexPath = join(versionDir, "index.html");
+        await writeFile(indexPath, html, "utf8");
+        return { ok: true, indexBytes: Buffer.byteLength(html, "utf8") };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            indexBytes: 0,
+            error: { kind: "runtime", message: `failed to write index.html: ${msg}` },
+        };
+    }
+}
+function isNotFound(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.code;
+    return code === "ENOENT";
+}
+function classifyNunjucksError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/template not found/i.test(message)) {
+        return { kind: "missing-template", message };
+    }
+    // Nunjucks tags parse errors with "Template render error" + "expected" /
+    // "unexpected" / "parseError" markers; the Template error carries lineno.
+    const lineno = err?.lineno;
+    const colno = err?.colno;
+    const line = typeof lineno === "number" ? lineno : undefined;
+    const isSyntax = /parseError|expected|unexpected token|unexpected end of/i.test(message) || /Template render error.*line \d+/i.test(message);
+    if (isSyntax) {
+        const snippet = extractSnippet(message, line, typeof colno === "number" ? colno : undefined);
+        return snippet ? { kind: "syntax", message, line, snippet } : line !== undefined ? { kind: "syntax", message, line } : { kind: "syntax", message };
+    }
+    return line !== undefined ? { kind: "runtime", message, line } : { kind: "runtime", message };
+}
+function extractSnippet(message, line, col) {
+    if (!line)
+        return undefined;
+    const m = message.split("\n").find((l) => l.trim().length > 0 && !/^\s*at\s/.test(l));
+    if (!m)
+        return undefined;
+    return col !== undefined ? `${m} (col ${col})` : m;
+}

package/dist/execution/report-runner.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Report runner — orchestrates an iterative report build entirely in the
+ * Cortex Node process. No sandbox, no Python.
+ *
+ * Lifecycle:
+ *  1. Resolve version (latest + 1, or baseVersion + 1)
+ *  2. Prepare version dir (mkdir, copy v{base}/report.html.j2, symlink ../assets)
+ *  3. Construct the 4 custom report tools + the in-process versionFs surface;
+ *     all of them close over the iteration's preview-dir state and a single
+ *     `outcome: ReportOutcome | undefined` variable (the closure-state
+ *     closure-state capture — see design.md Decision #9, mirrors
+ *     `harness/tools/research/generate-plan.ts`'s
+ *     `PlannerOutcome` capture).
+ *  4. Build the `report-builder` AgentDefinition with that tool roster and
+ *     drive it via `runAgent` + `passthroughStep`.
+ *  5. Verify the closure-captured `outcome` is `{ ok: true, ... }` (else
+ *     classify the failure, roll back the version dir, return a structured
+ *     failure).
+ *  6. Return success or a structured failure.
+ *
+ * Concurrency: per-previewId serialization via `withPreviewLock` so two
+ * iterations on the same preview don't race on shared assets/.
+ *
+ * Billing: the report-builder's LLM calls flow through the `ChatProvider`
+ * seam with `forSubAgent(session, REPORT_BUILDER_AGENT_ID)` — the provider's
+ * lazy `resolveBilling` fires at the call site. No ALS, no fetch-patch
+ * (Decision #6).
+ *
+ * Preview surface: the `preview_snapshot` and `mint_preview_url` tools mint
+ * a content-server URL through the injected `PreviewPublisher` seam. The
+ * managed publisher owns the short-lived host credential; the local default
+ * returns "unavailable" so the report still builds without a hosted preview.
+ */
+import type { Pool } from "pg";
+import { type RequestSession } from "../auth/types.js";
+import type { EmitFn } from "../loop/types.js";
+import type { ChatProvider } from "../providers/types.js";
+import type { PreviewPublisher } from "../tools/report/preview-publisher.js";
+import type { ChromeConfig } from "../lib/chrome.js";
+export interface ReportRunnerDeps {
+    readonly provider: ChatProvider;
+    readonly pool: Pool;
+    /** Model id — provenance / metric label; provider owns the wire model. */
+    readonly model: string;
+    /** Root templates dir; `report-html` is joined onto it. */
+    readonly templatesDir: string;
+    /** Skills root; the report-builder gets read-only `report-html` skill tools. */
+    readonly skillsDir: string;
+    readonly chrome: ChromeConfig;
+}
+export interface ReportRunnerOptions {
+    readonly resourceId: string;
+    /** Absolute host root of the analysis's workspace tree (previews live inside it). */
+    readonly workspaceRoot: string;
+    readonly previews: PreviewPublisher;
+    /** Preview group ID. Auto-generated by the tool layer if not provided. */
+    readonly previewId: string;
+    /** Base version to iterate from. Defaults to latest. */
+    readonly baseVersion?: number;
+    /** Report format. */
+    readonly format: "html" | "pdf";
+    /** Prompt for the report-builder agent. */
+    readonly prompt: string;
+    /** Live chat session — derives the child agent's session via forSubAgent. */
+    readonly session: RequestSession;
+    /** Cancellation signal — propagates to the agent stream. */
+    readonly signal: AbortSignal;
+    /** Event sink — forwarded to the agent loop. */
+    readonly emit: EmitFn;
+}
+export type ReportRunnerResult = {
+    ok: true;
+    previewId: string;
+    version: number;
+    previewPath: string;
+    durationMs: number;
+    /** Caveats surfaced by the agent via submit_report. */
+    notes: readonly string[];
+} | {
+    ok: false;
+    previewId: string;
+    version: number;
+    reason: string;
+    errorKind: "render" | "submit" | "build" | "timeout" | "internal";
+    durationMs: number;
+};
+export declare function runReportIteration(deps: ReportRunnerDeps, opts: ReportRunnerOptions): Promise<ReportRunnerResult>;

package/dist/execution/report-runner.js

@@ -0,0 +1,227 @@
+/**
+ * Report runner — orchestrates an iterative report build entirely in the
+ * Cortex Node process. No sandbox, no Python.
+ *
+ * Lifecycle:
+ *  1. Resolve version (latest + 1, or baseVersion + 1)
+ *  2. Prepare version dir (mkdir, copy v{base}/report.html.j2, symlink ../assets)
+ *  3. Construct the 4 custom report tools + the in-process versionFs surface;
+ *     all of them close over the iteration's preview-dir state and a single
+ *     `outcome: ReportOutcome | undefined` variable (the closure-state
+ *     closure-state capture — see design.md Decision #9, mirrors
+ *     `harness/tools/research/generate-plan.ts`'s
+ *     `PlannerOutcome` capture).
+ *  4. Build the `report-builder` AgentDefinition with that tool roster and
+ *     drive it via `runAgent` + `passthroughStep`.
+ *  5. Verify the closure-captured `outcome` is `{ ok: true, ... }` (else
+ *     classify the failure, roll back the version dir, return a structured
+ *     failure).
+ *  6. Return success or a structured failure.
+ *
+ * Concurrency: per-previewId serialization via `withPreviewLock` so two
+ * iterations on the same preview don't race on shared assets/.
+ *
+ * Billing: the report-builder's LLM calls flow through the `ChatProvider`
+ * seam with `forSubAgent(session, REPORT_BUILDER_AGENT_ID)` — the provider's
+ * lazy `resolveBilling` fires at the call site. No ALS, no fetch-patch
+ * (Decision #6).
+ *
+ * Preview surface: the `preview_snapshot` and `mint_preview_url` tools mint
+ * a content-server URL through the injected `PreviewPublisher` seam. The
+ * managed publisher owns the short-lived host credential; the local default
+ * returns "unavailable" so the report still builds without a hosted preview.
+ */
+import { copyFile, mkdir, readdir, rm, stat, symlink } from "node:fs/promises";
+import { join } from "node:path";
+import { forSubAgent } from "../auth/types.js";
+import { runToTerminal } from "../loop/run-to-terminal.js";
+import { passthroughStep } from "../loop/run-step.js";
+import { previewVersionDir, previewDir, latestPreviewVersion } from "../workspace/paths.js";
+import { withPreviewLock } from "../tools/lib/preview-lock.js";
+import { createBuildReportTool, createSubmitReportTool, createMintPreviewUrlTool, createPreviewSnapshotTool, createVersionFsTools, } from "../tools/report/index.js";
+import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID } from "../agents/report-builder.js";
+import { createSkillTools } from "../tools/sandbox/skills.js";
+/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
+const REPORT_BUILDER_SKILLS = ["report-html"];
+const REPORT_AGENT_MAX_STEPS = 75;
+export async function runReportIteration(deps, opts) {
+    const startTime = performance.now();
+    return withPreviewLock(opts.previewId, async () => {
+        // ── Resolve version directories ───────────────────────────────
+        const previewRootAbs = join(opts.workspaceRoot, previewDir(opts.previewId));
+        let existingVersions = [];
+        try {
+            existingVersions = (await readdir(previewRootAbs, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+        }
+        catch {
+            /* dir doesn't exist yet */
+        }
+        const latestVer = latestPreviewVersion(existingVersions);
+        const baseVer = opts.baseVersion ?? latestVer;
+        const newVersion = Math.max(latestVer, baseVer) + 1;
+        const versionDirRel = previewVersionDir(opts.previewId, newVersion);
+        const versionDirAbs = join(opts.workspaceRoot, versionDirRel);
+        const assetsDirAbs = join(previewRootAbs, "assets");
+        // ── Prepare directories ───────────────────────────────────────
+        try {
+            await mkdir(versionDirAbs, { recursive: true });
+            await mkdir(assetsDirAbs, { recursive: true });
+            if (baseVer > 0) {
+                const baseTemplate = join(opts.workspaceRoot, previewVersionDir(opts.previewId, baseVer), "report.html.j2");
+                try {
+                    await copyFile(baseTemplate, join(versionDirAbs, "report.html.j2"));
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== "ENOENT")
+                        throw err;
+                    // Base version has no template — agent will author from scratch.
+                }
+            }
+            // Symlink assets/ → ../assets so templates can reference assets/foo.csv
+            // and the content-server resolves them through the version-dir prefix.
+            const assetsSymlink = join(versionDirAbs, "assets");
+            try {
+                await symlink("../assets", assetsSymlink, "dir");
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "EEXIST")
+                    throw err;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return failure(opts.previewId, newVersion, `prepareVersionDir failed: ${msg}`, "internal", startTime);
+        }
+        // ── Closure-captured terminal-tool state (Decision #9) ─────────
+        let outcome;
+        const urlCell = { url: undefined, expiresAt: undefined };
+        const templatesDir = join(deps.templatesDir, "report-html");
+        const buildReportTool = createBuildReportTool({
+            versionDir: versionDirAbs,
+            templatesDir,
+        });
+        const submitReportTool = createSubmitReportTool({
+            versionDir: versionDirAbs,
+            assetsDir: assetsDirAbs,
+            setOutcome: (v) => {
+                outcome = v;
+            },
+        });
+        const tools = [
+            buildReportTool,
+            submitReportTool,
+            createMintPreviewUrlTool({
+                resourceId: opts.resourceId,
+                previewId: opts.previewId,
+                currentVersion: newVersion,
+                previews: opts.previews,
+                urlCell,
+            }),
+            createPreviewSnapshotTool({
+                resourceId: opts.resourceId,
+                previewId: opts.previewId,
+                currentVersion: newVersion,
+                previews: opts.previews,
+                urlCell,
+                chrome: deps.chrome,
+            }),
+            ...createVersionFsTools({ versionDir: versionDirAbs }),
+            ...Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: [...REPORT_BUILDER_SKILLS] })),
+        ];
+        const agent = createReportBuilderAgent({ model: deps.model, tools });
+        // The agent's runaway-guard takes precedence over the per-iteration cap.
+        const cappedAgent = {
+            ...agent,
+            maxIterations: Math.min(agent.maxIterations, REPORT_AGENT_MAX_STEPS),
+        };
+        const childSession = forSubAgent(opts.session, REPORT_BUILDER_AGENT_ID);
+        let agentError;
+        try {
+            await runToTerminal(cappedAgent, [{ role: "user", content: opts.prompt }], childSession, {
+                provider: deps.provider,
+                signal: opts.signal,
+                emit: opts.emit,
+                runStep: passthroughStep,
+            }, {
+                resolved: () => outcome !== undefined,
+                tools: [buildReportTool, submitReportTool],
+                nudge: "You stopped without calling submit_report, so this report version " +
+                    "was not recorded. Build the report if needed, then call " +
+                    "submit_report now to finalize it.",
+            });
+        }
+        catch (err) {
+            agentError = err instanceof Error ? err.message : String(err);
+        }
+        // ── Phantom-success guard ──────────────────────────────────────
+        // submit-report claims ok but index.html doesn't exist or is empty.
+        let phantomSuccess = false;
+        if (outcome?.ok === true && !agentError) {
+            try {
+                const indexStat = await stat(join(versionDirAbs, "index.html"));
+                if (!indexStat.isFile() || indexStat.size === 0)
+                    phantomSuccess = true;
+            }
+            catch {
+                phantomSuccess = true;
+            }
+        }
+        if (!outcome || agentError || phantomSuccess) {
+            console.warn(`[report-runner] event=report.agent.finish preview=${opts.previewId} v${newVersion} ` +
+                `submitted=${outcome?.ok === true} phantom=${phantomSuccess} ` +
+                `agentError=${agentError ?? "null"}`);
+            const { reason, errorKind } = classifyFailure({
+                phantomSuccess,
+                agentError,
+                outcome,
+            });
+            // Roll back the version dir (assets are shared — leave them alone).
+            try {
+                await rm(versionDirAbs, { recursive: true, force: true });
+            }
+            catch (err) {
+                console.error(`[report-runner] rollback failed for ${versionDirAbs}:`, err instanceof Error ? err.message : err);
+            }
+            return failure(opts.previewId, newVersion, reason, errorKind, startTime);
+        }
+        const durationMs = Math.round(performance.now() - startTime);
+        return {
+            ok: true,
+            previewId: opts.previewId,
+            version: newVersion,
+            previewPath: `v${newVersion}/index.html`,
+            durationMs,
+            notes: outcome.notes,
+        };
+    });
+}
+function failure(previewId, version, reason, errorKind, startTime) {
+    return {
+        ok: false,
+        previewId,
+        version,
+        reason,
+        errorKind,
+        durationMs: Math.round(performance.now() - startTime),
+    };
+}
+function classifyFailure(s) {
+    if (s.phantomSuccess) {
+        return {
+            reason: "submit_report claimed ok but index.html is missing or empty",
+            errorKind: "build",
+        };
+    }
+    if (s.agentError) {
+        return {
+            reason: s.agentError,
+            errorKind: /timeout/i.test(s.agentError) ? "timeout" : "submit",
+        };
+    }
+    return {
+        reason: "agent did not call submit_report — terminal outcome was never recorded",
+        errorKind: "submit",
+    };
+}