@inflexa-ai/harness 0.1.1

package/dist/tools/memory/update-working-memory.js

@@ -0,0 +1,112 @@
+/**
+ * update-working-memory — the agent's single interface for maintaining
+ * working memory.
+ *
+ * Dependency-bearing: the `WorkingMemoryStore` is captured by the factory
+ * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`.
+ *
+ * The input is a flat object with a `section` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (Anthropic needs a
+ * top-level `"type":"object"`). The variant fields are validated by
+ * `.refine` so a malformed call (e.g. a `finding` with no `runId`) fails
+ * at the loop boundary and surfaces as an `is_error` tool result.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { scopeResource } from "../../auth/types.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { defineTool } from "../define-tool.js";
+const inputSchema = z
+    .object({
+    section: z.enum(["goal", "constraint", "hypothesis", "finding"]).describe("Which working-memory section to update."),
+    operation: z
+        .enum(["add", "revise", "retire"])
+        .optional()
+        .describe("For constraint/hypothesis: add a new entry (default), revise an " + "existing entry's text, or retire a stale one. Ignored for goal/finding."),
+    text: z
+        .string()
+        .optional()
+        .describe("Entry text. Required for goal, finding, and constraint/hypothesis " + "add/revise. Omit when retiring."),
+    id: z
+        .string()
+        .optional()
+        .describe("The entry id to revise or retire. Required when operation is " + "'revise' or 'retire' — copy it from the rendered working memory."),
+    origin: z
+        .enum(["user", "agent"])
+        .optional()
+        .describe("For a new constraint: whether the user stated the rule or you " + "derived it. Defaults to 'agent'."),
+    runId: z.string().optional().describe("The run that produced the finding. Required when section is 'finding'."),
+})
+    .refine((d) => d.section !== "goal" || d.text !== undefined, {
+    message: "text is required when section is 'goal'",
+    path: ["text"],
+})
+    .refine((d) => d.section !== "finding" || (d.runId !== undefined && d.runId.length > 0), {
+    message: "runId is required when section is 'finding'",
+    path: ["runId"],
+})
+    .refine((d) => d.section !== "finding" || (d.text !== undefined && d.text.length > 0), {
+    message: "text is required when section is 'finding'",
+    path: ["text"],
+})
+    .refine((d) => !(d.operation === "revise" || d.operation === "retire") || (d.id !== undefined && d.id.length > 0), {
+    message: "id is required when operation is 'revise' or 'retire'",
+    path: ["id"],
+})
+    .refine((d) => {
+    const isList = d.section === "constraint" || d.section === "hypothesis";
+    const op = d.operation ?? "add";
+    return !(isList && op !== "retire") || (d.text !== undefined && d.text.length > 0);
+}, {
+    message: "text is required to add or revise a constraint/hypothesis",
+    path: ["text"],
+});
+/** Map a validated flat input to a constraint/hypothesis list amendment. */
+function toListOp(input) {
+    switch (input.operation ?? "add") {
+        case "add":
+            return { op: "add", text: input.text };
+        case "revise":
+            return { op: "revise", id: input.id, text: input.text };
+        case "retire":
+            return { op: "retire", id: input.id };
+    }
+}
+function toConstraintOp(input) {
+    const base = toListOp(input);
+    return base.op === "add" ? { ...base, origin: input.origin ?? "agent" } : base;
+}
+export function createUpdateWorkingMemoryTool(workingMemory) {
+    return defineTool({
+        id: "update_working_memory",
+        description: "Maintain the analysis's working memory — its durable interpretive " +
+            "layer that survives token-window eviction. Section-addressable: set " +
+            "the 'goal', add/revise/retire a 'constraint' (a binding rule) or a " +
+            "'hypothesis', or record a 'finding' under a runId. Updates one " +
+            "section at a time; the others are untouched.",
+        inputSchema,
+        execute: async (input, ctx) => {
+            const analysisId = scopeResource(ctx.session.scope).resourceId;
+            switch (input.section) {
+                case "goal":
+                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "goal", {
+                        text: input.text,
+                    }));
+                    break;
+                case "constraint":
+                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "constraint", toConstraintOp(input)));
+                    break;
+                case "hypothesis":
+                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "hypothesis", toListOp(input)));
+                    break;
+                case "finding":
+                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "finding", {
+                        runId: input.runId,
+                        text: input.text,
+                    }));
+                    break;
+            }
+            return ok({ ok: true, section: input.section });
+        },
+    });
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tool registry — a name→`Tool` map.
+ *
+ * `definitions()` emits AI SDK-compatible tool definitions; `get(name)`
+ * resolves a tool by name for the loop's dispatch boundary (change 3).
+ */
+import { type ToolSet } from "ai";
+import type { Tool } from "./define-tool.js";
+export interface Registry {
+    /** The AI SDK tool definitions to send with a chat request. */
+    definitions(): ToolSet;
+    /** Resolve a tool by name for dispatch; `undefined` if unknown. */
+    get(name: string): Tool | undefined;
+}
+export declare function createRegistry(tools: readonly Tool[]): Registry;

package/dist/tools/registry.js

@@ -0,0 +1,26 @@
+/**
+ * Tool registry — a name→`Tool` map.
+ *
+ * `definitions()` emits AI SDK-compatible tool definitions; `get(name)`
+ * resolves a tool by name for the loop's dispatch boundary (change 3).
+ */
+import { jsonSchema, tool as aiTool } from "ai";
+export function createRegistry(tools) {
+    const byName = new Map();
+    for (const tool of tools) {
+        if (byName.has(tool.id)) {
+            throw new Error(`createRegistry: duplicate tool id "${tool.id}"`);
+        }
+        byName.set(tool.id, tool);
+    }
+    return {
+        definitions: () => Object.fromEntries(tools.map((t) => [
+            t.id,
+            aiTool({
+                description: t.description,
+                inputSchema: jsonSchema(t.jsonSchema),
+            }),
+        ])),
+        get: (name) => byName.get(name),
+    };
+}

package/dist/tools/report/build-report.d.ts

@@ -0,0 +1,13 @@
+/**
+ * build_report tool — renders `report.html.j2` → `index.html` via the
+ * in-process Nunjucks renderer. Closes over the runner's preview-dir state.
+ *
+ * Returns structured success or a typed error so the agent can fix and retry.
+ * Version dir and templates dir are closure-state.
+ */
+import { type Tool } from "../define-tool.js";
+export interface BuildReportToolState {
+    readonly versionDir: string;
+    readonly templatesDir: string;
+}
+export declare function createBuildReportTool(state: BuildReportToolState): Tool;

package/dist/tools/report/build-report.js

@@ -0,0 +1,26 @@
+/**
+ * build_report tool — renders `report.html.j2` → `index.html` via the
+ * in-process Nunjucks renderer. Closes over the runner's preview-dir state.
+ *
+ * Returns structured success or a typed error so the agent can fix and retry.
+ * Version dir and templates dir are closure-state.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { renderReport } from "../../execution/report-render.js";
+export function createBuildReportTool(state) {
+    return defineTool({
+        id: "build_report",
+        description: "Render the report by compiling report.html.j2 into index.html. " +
+            "Always use this — never invoke a build script directly. Returns " +
+            "structured errors with line numbers when the template is broken.",
+        inputSchema: z.object({}),
+        execute: async () => {
+            return ok(await renderReport({
+                versionDir: state.versionDir,
+                templatesDir: state.templatesDir,
+            }));
+        },
+    });
+}

package/dist/tools/report/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Report-tool barrel. These tools are NOT registered on the conversation
+ * agent — they are constructed inside `harness/execution/report-runner.ts`
+ * so each tool factory shares the runner's closure-captured outcome state
+ * and preview-dir paths. The conversation agent reaches the report-builder
+ * through the `iterate_report` tool, which orchestrates the whole
+ * iteration.
+ */
+export { createBuildReportTool, type BuildReportToolState } from "./build-report.js";
+export { createSubmitReportTool, type ReportOutcome, type SubmitReportToolState } from "./submit-report.js";
+export { createMintPreviewUrlTool, type MintPreviewUrlToolState, type PreviewUrlCell } from "./mint-preview-url.js";
+export { createPreviewSnapshotTool, type PreviewSnapshotToolState } from "./preview-snapshot.js";
+export { createVersionFsTools, type VersionFsToolsState } from "./version-fs.js";
+export { type PreviewPublisher, type PreviewMintResult, UnavailablePreviewPublisher } from "./preview-publisher.js";

package/dist/tools/report/index.js

@@ -0,0 +1,14 @@
+/**
+ * Report-tool barrel. These tools are NOT registered on the conversation
+ * agent — they are constructed inside `harness/execution/report-runner.ts`
+ * so each tool factory shares the runner's closure-captured outcome state
+ * and preview-dir paths. The conversation agent reaches the report-builder
+ * through the `iterate_report` tool, which orchestrates the whole
+ * iteration.
+ */
+export { createBuildReportTool } from "./build-report.js";
+export { createSubmitReportTool } from "./submit-report.js";
+export { createMintPreviewUrlTool } from "./mint-preview-url.js";
+export { createPreviewSnapshotTool } from "./preview-snapshot.js";
+export { createVersionFsTools } from "./version-fs.js";
+export { UnavailablePreviewPublisher } from "./preview-publisher.js";

package/dist/tools/report/mint-preview-url.d.ts

@@ -0,0 +1,26 @@
+/**
+ * mint_preview_url tool — get a content-server URL for the report preview.
+ *
+ * Calls the preview-access seam and returns the full navigatable URL
+ * for the requested version.
+ *
+ * Most callers don't need this — `preview_snapshot` mints lazily on first
+ * use. Reach for this tool when:
+ *   - the previously-minted URL has expired
+ *   - inspecting an older version (pass `version`)
+ */
+import { type Tool } from "../define-tool.js";
+import type { PreviewPublisher } from "./preview-publisher.js";
+/** Shared, mutable URL cell so mint and preview-snapshot share a cached URL. */
+export interface PreviewUrlCell {
+    url: string | undefined;
+    expiresAt: string | undefined;
+}
+export interface MintPreviewUrlToolState {
+    readonly resourceId: string;
+    readonly previewId: string;
+    readonly currentVersion: number;
+    readonly previews: PreviewPublisher;
+    readonly urlCell: PreviewUrlCell;
+}
+export declare function createMintPreviewUrlTool(state: MintPreviewUrlToolState): Tool;

package/dist/tools/report/mint-preview-url.js

@@ -0,0 +1,44 @@
+/**
+ * mint_preview_url tool — get a content-server URL for the report preview.
+ *
+ * Calls the preview-access seam and returns the full navigatable URL
+ * for the requested version.
+ *
+ * Most callers don't need this — `preview_snapshot` mints lazily on first
+ * use. Reach for this tool when:
+ *   - the previously-minted URL has expired
+ *   - inspecting an older version (pass `version`)
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+export function createMintPreviewUrlTool(state) {
+    return defineTool({
+        id: "mint_preview_url",
+        description: "Mint a fresh preview URL for the report. Returns a content-server " +
+            "URL with embedded auth token (15-min TTL). Use this only when you " +
+            "need a URL for direct browser navigation — preview_snapshot handles " +
+            "the common case automatically.",
+        inputSchema: z.object({
+            version: z.number().optional().describe("Version to mint for. Defaults to the iteration's current version."),
+        }),
+        execute: async (input) => {
+            const version = input.version ?? state.currentVersion;
+            const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);
+            if (!result.ok) {
+                return ok({
+                    ok: false,
+                    error: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                });
+            }
+            const url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${version}/index.html?t=${result.data.token}`;
+            state.urlCell.url = url;
+            state.urlCell.expiresAt = result.data.expiresAt;
+            return ok({
+                ok: true,
+                url,
+                expiresAt: result.data.expiresAt,
+            });
+        },
+    });
+}

package/dist/tools/report/preview-publisher.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PreviewPublisher — the seam between the harness report path and the hosted
+ * preview surface. The report build itself (FS + Nunjucks + LLM via
+ * `ChatProvider`) is pure in-process; the only thing that reaches outside
+ * the process is minting a content-server URL for the headless-Chrome
+ * preview. That mint is hidden behind this one method.
+ *
+ * The managed implementation (HostedPreviewPublisher) owns the access
+ * grant mint + managed client. The local default (UnavailablePreviewPublisher)
+ * returns not-ok, so `preview_snapshot` short-circuits before touching
+ * Chrome and the report still builds (submit_report is the only gate).
+ */
+export type PreviewMintResult = {
+    ok: true;
+    data: {
+        baseUrl: string;
+        token: string;
+        expiresAt: string;
+    };
+} | {
+    ok: false;
+    status?: number;
+    error: {
+        message?: string;
+    };
+};
+export interface PreviewPublisher {
+    mintPreviewAccess(resourceId: string, previewId: string): Promise<PreviewMintResult>;
+}
+/**
+ * Local default — no hosted preview surface. Returns not-ok so the preview
+ * tools surface a clear "unavailable" message and short-circuit before any
+ * browser navigation.
+ */
+export declare class UnavailablePreviewPublisher implements PreviewPublisher {
+    mintPreviewAccess(_resourceId: string, _previewId: string): Promise<PreviewMintResult>;
+}

package/dist/tools/report/preview-publisher.js

@@ -0,0 +1,25 @@
+/**
+ * PreviewPublisher — the seam between the harness report path and the hosted
+ * preview surface. The report build itself (FS + Nunjucks + LLM via
+ * `ChatProvider`) is pure in-process; the only thing that reaches outside
+ * the process is minting a content-server URL for the headless-Chrome
+ * preview. That mint is hidden behind this one method.
+ *
+ * The managed implementation (HostedPreviewPublisher) owns the access
+ * grant mint + managed client. The local default (UnavailablePreviewPublisher)
+ * returns not-ok, so `preview_snapshot` short-circuits before touching
+ * Chrome and the report still builds (submit_report is the only gate).
+ */
+/**
+ * Local default — no hosted preview surface. Returns not-ok so the preview
+ * tools surface a clear "unavailable" message and short-circuit before any
+ * browser navigation.
+ */
+export class UnavailablePreviewPublisher {
+    async mintPreviewAccess(_resourceId, _previewId) {
+        return {
+            ok: false,
+            error: { message: "report preview is unavailable in this environment" },
+        };
+    }
+}

package/dist/tools/report/preview-snapshot.d.ts

@@ -0,0 +1,26 @@
+/**
+ * preview_snapshot tool — navigate headless Chrome to the rendered report,
+ * wait for the `inflexa-theme-ready` event, capture a screenshot + console
+ * messages + failed network requests in a single deterministic call.
+ *
+ * Lazily mints a preview URL via the `PreviewPublisher` seam on first use,
+ * sharing the cached URL with the `mint_preview_url` tool via a
+ * closure-captured `PreviewUrlCell`.
+ *
+ * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
+ * console errors / failed requests to decide whether to fix the template
+ * or move on to submit_report.
+ */
+import { type Tool } from "../define-tool.js";
+import { type ChromeConfig } from "../../lib/chrome.js";
+import type { PreviewPublisher } from "./preview-publisher.js";
+import type { PreviewUrlCell } from "./mint-preview-url.js";
+export interface PreviewSnapshotToolState {
+    readonly resourceId: string;
+    readonly previewId: string;
+    readonly currentVersion: number;
+    readonly previews: PreviewPublisher;
+    readonly urlCell: PreviewUrlCell;
+    readonly chrome: ChromeConfig;
+}
+export declare function createPreviewSnapshotTool(state: PreviewSnapshotToolState): Tool;

package/dist/tools/report/preview-snapshot.js

@@ -0,0 +1,121 @@
+/**
+ * preview_snapshot tool — navigate headless Chrome to the rendered report,
+ * wait for the `inflexa-theme-ready` event, capture a screenshot + console
+ * messages + failed network requests in a single deterministic call.
+ *
+ * Lazily mints a preview URL via the `PreviewPublisher` seam on first use,
+ * sharing the cached URL with the `mint_preview_url` tool via a
+ * closure-captured `PreviewUrlCell`.
+ *
+ * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
+ * console errors / failed requests to decide whether to fix the template
+ * or move on to submit_report.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { withPage } from "../../lib/chrome.js";
+const NAV_TIMEOUT_MS = 20_000;
+const READY_TIMEOUT_MS = 8_000;
+const WAIT_MS_CAP = 30_000;
+export function createPreviewSnapshotTool(state) {
+    return defineTool({
+        id: "preview_snapshot",
+        description: "Render the report in a real headless browser and report what you " +
+            "see. Returns a screenshot, console errors, and failed network " +
+            "requests. Use this after build_report to verify the layout, charts, " +
+            "and data loads correctly.",
+        inputSchema: z.object({
+            waitForSelector: z
+                .string()
+                .optional()
+                .describe("Optional CSS selector to wait for after the page is loaded — useful " + "when a specific chart needs to be visible before the screenshot."),
+            waitMs: z
+                .number()
+                .finite()
+                .int()
+                .min(0)
+                .max(WAIT_MS_CAP)
+                .optional()
+                .describe("Optional extra wait in ms after the theme-ready event (e.g., for chart paint). Capped at 30s."),
+        }),
+        execute: async (input) => {
+            let url = state.urlCell.url;
+            const expiresAt = state.urlCell.expiresAt;
+            if (url && expiresAt && new Date(expiresAt).getTime() < Date.now() + 60_000) {
+                url = undefined; // refresh if within 60s of expiry
+            }
+            if (!url) {
+                const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);
+                if (!result.ok) {
+                    return ok({
+                        ok: false,
+                        consoleErrors: [],
+                        failedRequests: [],
+                        error: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                    });
+                }
+                url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${state.currentVersion}/index.html?t=${result.data.token}`;
+                state.urlCell.url = url;
+                state.urlCell.expiresAt = result.data.expiresAt;
+            }
+            try {
+                return ok(await withPage(state.chrome, async (page) => {
+                    const consoleErrors = [];
+                    const failedRequests = [];
+                    page.on("console", (msg) => {
+                        if (msg.type() === "error")
+                            consoleErrors.push(msg.text());
+                    });
+                    page.on("pageerror", (err) => consoleErrors.push(`pageerror: ${err.message}`));
+                    page.on("requestfailed", (req) => {
+                        failedRequests.push({
+                            url: req.url(),
+                            reason: req.failure()?.errorText ?? "unknown",
+                        });
+                    });
+                    await page.goto(url, {
+                        waitUntil: "networkidle2",
+                        timeout: NAV_TIMEOUT_MS,
+                    });
+                    // Wait for the inflexa-theme-ready event (fired after echarts theme
+                    // registers). Check the `__inflexaThemeReady` sentinel first because
+                    // the page already deferred its dispatch — by the time we get here
+                    // via networkidle2, the event has likely already fired and a plain
+                    // addEventListener would block forever. The callback runs in the
+                    // browser context.
+                    await page
+                        .evaluate(new Function("timeout", "return new Promise(function(resolve){if(window.__inflexaThemeReady){resolve();return;}var t=setTimeout(resolve,timeout);document.addEventListener('inflexa-theme-ready',function(){clearTimeout(t);resolve();},{once:true});});"), READY_TIMEOUT_MS)
+                        .catch(() => {
+                        /* fall through — capture state as-is */
+                    });
+                    if (input.waitForSelector) {
+                        await page.waitForSelector(input.waitForSelector, { timeout: 5_000 }).catch(() => {
+                            /* not fatal */
+                        });
+                    }
+                    if (input.waitMs)
+                        await new Promise((r) => setTimeout(r, input.waitMs));
+                    const screenshot = await page.screenshot({
+                        encoding: "base64",
+                        fullPage: false,
+                    });
+                    return {
+                        ok: true,
+                        screenshotBase64: typeof screenshot === "string" ? screenshot : Buffer.from(screenshot).toString("base64"),
+                        consoleErrors,
+                        failedRequests,
+                    };
+                }));
+            }
+            catch (err) {
+                return ok({
+                    ok: false,
+                    consoleErrors: [],
+                    failedRequests: [],
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+    });
+}

package/dist/tools/report/submit-report.d.ts

@@ -0,0 +1,25 @@
+/**
+ * submit_report tool — postcondition gate. The runner refuses to emit
+ * `data-report-preview` until this tool writes the success outcome.
+ *
+ * Checks:
+ *   - index.html exists at versionDir/ with size > 0
+ *   - no unrendered `{{ … }}` or `{% … %}` left in the output
+ *   - all referenced asset paths resolve to files on disk
+ *
+ * On success, writes `{ ok: true, notes }` into the runner's closure-captured
+ * outcome variable.
+ */
+import { type Tool } from "../define-tool.js";
+/** Terminal outcome the submit-report tool writes into the runner closure. */
+export type ReportOutcome = {
+    ok: true;
+    notes: readonly string[];
+};
+export interface SubmitReportToolState {
+    readonly versionDir: string;
+    readonly assetsDir: string;
+    /** Write-through for the runner's closure-captured outcome variable. */
+    setOutcome(outcome: ReportOutcome): void;
+}
+export declare function createSubmitReportTool(state: SubmitReportToolState): Tool;

package/dist/tools/report/submit-report.js

@@ -0,0 +1,126 @@
+/**
+ * submit_report tool — postcondition gate. The runner refuses to emit
+ * `data-report-preview` until this tool writes the success outcome.
+ *
+ * Checks:
+ *   - index.html exists at versionDir/ with size > 0
+ *   - no unrendered `{{ … }}` or `{% … %}` left in the output
+ *   - all referenced asset paths resolve to files on disk
+ *
+ * On success, writes `{ ok: true, notes }` into the runner's closure-captured
+ * outcome variable.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+// `[^{}]*` accepts any expression Nunjucks allows between delimiters
+// (filters `{{ x | tojson }}`, inline conditionals `{{ a if b else c }}`,
+// bracket access `{{ d['k'] }}`) but stops at nested braces — which aren't
+// valid Nunjucks anyway. The `{%-?` arm covers whitespace-trimming tags.
+const UNRENDERED_JINJA = /\{\{[^{}]*\}\}|\{%-?\s*\w/;
+export function createSubmitReportTool(state) {
+    return defineTool({
+        id: "submit_report",
+        description: "Declare the report ready. Validates index.html exists, has no " +
+            "unrendered Jinja, and that all referenced asset paths resolve. " +
+            "You MUST call this to finish — the runner ignores any other claim " +
+            "of success. Returns problems[] when checks fail; fix and re-submit. " +
+            "Use `notes` to surface caveats to the caller (e.g. files skipped due " +
+            "to the 50MB asset size limit, sections rendered with partial data, " +
+            "missing inputs that forced a fallback) — these reach the conversation " +
+            "agent and the user in the iteration result.",
+        inputSchema: z.object({
+            notes: z
+                .array(z.string())
+                .optional()
+                .describe("Caveats / issues to surface to the caller. One short sentence " +
+                "per item. Examples: 'skipped raw_counts.h5ad (1.2GB > 50MB cap)', " +
+                "'pathway-enrichment section omitted — no GSEA output found'. " +
+                "Leave empty when the report shipped cleanly."),
+        }),
+        execute: async (input) => {
+            const problems = [];
+            // 1. index.html exists and is non-empty
+            const indexPath = join(state.versionDir, "index.html");
+            let html;
+            try {
+                const s = await stat(indexPath);
+                if (!s.isFile() || s.size === 0) {
+                    problems.push("index.html is empty or not a regular file");
+                    return ok({ ok: false, problems });
+                }
+                html = await readFile(indexPath, "utf8");
+            }
+            catch {
+                problems.push("index.html does not exist — call build_report first");
+                return ok({ ok: false, problems });
+            }
+            // 2. No unrendered Jinja markers
+            if (UNRENDERED_JINJA.test(html)) {
+                const match = html.match(UNRENDERED_JINJA);
+                problems.push(`unrendered Jinja in output (e.g. ${JSON.stringify(match?.[0] ?? "")}); ` +
+                    "build_report likely failed silently or report.html.j2 was edited after build");
+            }
+            // 3. Asset reference resolution
+            const refs = extractLocalRefs(html);
+            for (const ref of refs) {
+                const resolved = resolveLocalRef(ref, state.versionDir, state.assetsDir);
+                if (!resolved) {
+                    problems.push(`asset reference does not resolve: ${ref}`);
+                    continue;
+                }
+                try {
+                    const s = await stat(resolved);
+                    if (!s.isFile())
+                        problems.push(`asset reference is not a regular file: ${ref}`);
+                }
+                catch {
+                    problems.push(`asset reference missing on disk: ${ref}`);
+                }
+            }
+            if (problems.length === 0) {
+                const notes = (input.notes ?? []).map((n) => n.trim()).filter(Boolean);
+                state.setOutcome({ ok: true, notes });
+                return ok({ ok: true, problems: [] });
+            }
+            return ok({ ok: false, problems });
+        },
+    });
+}
+const SRC_HREF_RE = /\b(?:src|href)\s*=\s*["']([^"']+)["']/gi;
+const FETCH_RE = /\bfetch\s*\(\s*["'`]([^"'`]+)["'`]/gi;
+function extractLocalRefs(html) {
+    const refs = new Set();
+    for (const m of html.matchAll(SRC_HREF_RE))
+        refs.add(m[1]);
+    for (const m of html.matchAll(FETCH_RE))
+        refs.add(m[1]);
+    // Filter to local refs only — drop absolute URLs and data: / blob: schemes.
+    const out = [];
+    for (const ref of refs) {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(ref))
+            continue; // http:, https:, data:, blob:
+        if (ref.startsWith("//"))
+            continue; // protocol-relative
+        if (ref.startsWith("#"))
+            continue; // anchor
+        out.push(ref);
+    }
+    return out;
+}
+function resolveLocalRef(ref, versionDir, assetsDir) {
+    // Strip leading slash, query string, and fragment.
+    const cleaned = ref.split("?")[0].split("#")[0].replace(/^\/+/, "");
+    if (!cleaned)
+        return undefined;
+    const candidate = resolve(versionDir, cleaned);
+    // The candidate must stay under either versionDir or assetsDir (the
+    // shared assets dir is the symlink target — both are valid roots).
+    const inVersion = candidate.startsWith(versionDir + sep) || candidate === versionDir;
+    const inAssets = candidate.startsWith(assetsDir + sep) || candidate === assetsDir;
+    if (!inVersion && !inAssets)
+        return undefined;
+    return candidate;
+}