ptywright 0.4.0 → 0.6.0

package/dist/{runner-CembqDgJ.mjs → runner-GIEf0C6d.mjs}

@@ -1,223 +1,23 @@
-import { z } from "zod";
+import { a as sameArgv, n as validateManifestFiles, r as formatZodIssues, t as collectManifestFiles } from "./manifest_files-DW80c1H7.mjs";
+import { t as envTruthy } from "./env-DPYHo-zH.mjs";
+import { t as base64ToBytes } from "./data-sdbf3IDh.mjs";
+import { a as styleKey, i as isDefaultStyle, n as extractStyle, r as findMeaningfulEndCol, t as DEFAULT_STYLE } from "./style-BtIUv5H0.mjs";
+import { createRequire } from "node:module";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { chromium } from "playwright";
+import { z } from "zod";
 import { createServer } from "node:http";
+import { chromium } from "playwright";
+import { Terminal } from "@xterm/headless";
 import { spawn } from "node:child_process";
-//#region src/agent/manifest.ts
-const AGENT_MANIFEST_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-manifest.schema.json";
-const AGENT_MANIFEST_FILE_NAME = "ptywright-agent.manifest.json";
-const agentManifestKindSchema = z.enum([
-	"run",
-	"replay-suite",
-	"check",
-	"promote"
-]);
-const agentManifestFileKindSchema = z.enum([
-	"flow",
-	"cassette",
-	"run-record",
-	"replay-summary",
-	"check-summary",
-	"promote-summary",
-	"report",
-	"terminal",
-	"dom",
-	"screenshot",
-	"diff"
-]);
-const agentManifestCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
-const agentManifestValidationStageSchema = z.object({
-	name: z.string().min(1),
-	ok: z.boolean(),
-	totalCount: z.number().int().nonnegative(),
-	failureCount: z.number().int().nonnegative()
-}).strict();
-const agentManifestValidationSchema = z.object({
-	ok: z.boolean(),
-	stages: z.array(agentManifestValidationStageSchema)
-}).strict().superRefine((validation, ctx) => {
-	const ok = validation.stages.every((stage) => stage.ok && stage.failureCount === 0);
-	if (validation.ok !== ok) ctx.addIssue({
-		code: z.ZodIssueCode.custom,
-		path: ["ok"],
-		message: "validation ok must match validation stages"
-	});
-});
-const agentManifestFileSchema = z.object({
-	path: z.string().min(1),
-	kind: agentManifestFileKindSchema,
-	role: z.string().min(1).optional(),
-	ok: z.boolean().optional(),
-	bytes: z.number().int().nonnegative(),
-	sha256: z.string().regex(/^[a-f0-9]{64}$/)
-}).strict();
-const agentManifestSchema = z.object({
-	$schema: z.string().optional(),
-	version: z.literal(1),
-	kind: agentManifestKindSchema,
-	ok: z.boolean(),
-	generatedAt: z.string().min(1),
-	rootDir: z.string().min(1),
-	primaryPath: z.string().min(1),
-	commands: z.record(agentManifestCommandSchema),
-	validation: agentManifestValidationSchema.optional(),
-	files: z.array(agentManifestFileSchema)
-}).strict().superRefine((manifest, ctx) => {
-	const seen = /* @__PURE__ */ new Set();
-	for (const file of manifest.files) {
-		if (seen.has(file.path)) ctx.addIssue({
-			code: z.ZodIssueCode.custom,
-			path: ["files"],
-			message: `duplicate manifest file path: ${file.path}`
-		});
-		seen.add(file.path);
-	}
-});
-function agentManifestPath(rootDir) {
-	return join(rootDir, AGENT_MANIFEST_FILE_NAME);
-}
-function createAgentManifest(options) {
-	return normalizeAgentManifest({
-		$schema: AGENT_MANIFEST_SCHEMA_URL,
-		version: 1,
-		kind: options.kind,
-		ok: options.ok,
-		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		rootDir: options.rootDir,
-		primaryPath: options.primaryPath,
-		commands: options.commands,
-		validation: options.validation,
-		files: collectManifestFiles(options.files, options.rootDir)
-	});
-}
-function readAgentManifestPath(path) {
-	return normalizeAgentManifest(JSON.parse(readFileSync(path, "utf8")));
-}
-function writeAgentManifestPath(path, options) {
-	const manifest = createAgentManifest(options);
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
-	return manifest;
-}
-function normalizeAgentManifest(input) {
-	try {
-		const parsed = agentManifestSchema.parse(input);
-		return {
-			...parsed,
-			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-manifest.schema.json"
-		};
-	} catch (error) {
-		if (error instanceof z.ZodError) throw new Error(`invalid agent manifest: ${formatZodIssues$1(error)}`);
-		throw error;
-	}
-}
-function validateAgentManifestFiles(manifest, manifestPath) {
-	const failures = [];
-	const baseDir = manifestPath ? dirname(resolve(process.cwd(), manifestPath)) : resolve(process.cwd(), manifest.rootDir);
-	for (const file of manifest.files) {
-		let current = null;
-		try {
-			current = readManifestFile(file, baseDir);
-		} catch (error) {
-			failures.push(`${file.path}: ${error instanceof Error ? error.message : String(error)}`);
-			continue;
-		}
-		if (current.bytes !== file.bytes) failures.push(`${file.path}: bytes ${current.bytes} !== ${file.bytes}`);
-		if (current.sha256 !== file.sha256) failures.push(`${file.path}: sha256 ${current.sha256} !== ${file.sha256}`);
-	}
-	if (failures.length > 0) throw new Error(`invalid agent manifest files: ${failures.join("; ")}`);
-}
-function isAgentManifestLike(input) {
-	return typeof input === "object" && input !== null && input.version === 1 && typeof input.kind === "string" && Array.isArray(input.files) && typeof input.commands === "object";
-}
-function collectManifestFiles(files, rootDir) {
-	const out = [];
-	const seen = /* @__PURE__ */ new Set();
-	const rootAbs = resolve(process.cwd(), rootDir);
-	for (const file of files) {
-		if (!file.path || seen.has(file.path)) continue;
-		seen.add(file.path);
-		try {
-			out.push(readManifestFile(file, rootAbs, { portableRoot: true }));
-		} catch {}
-	}
-	return out.sort((a, b) => a.path.localeCompare(b.path));
-}
-function readManifestFile(file, baseDir, options = {}) {
-	if (!file.path) throw new Error("missing file path");
-	const absPath = isAbsolute(file.path) ? file.path : resolve(options.portableRoot ? process.cwd() : baseDir, file.path);
-	if (!statSync(absPath).isFile()) throw new Error("not a file");
-	const bytes = readFileSync(absPath);
-	return {
-		path: options.portableRoot ? portableManifestPath(absPath, baseDir) : file.path,
-		kind: file.kind,
-		role: file.role,
-		ok: file.ok,
-		bytes: bytes.byteLength,
-		sha256: createHash("sha256").update(bytes).digest("hex")
-	};
-}
-function portableManifestPath(absPath, rootAbs) {
-	const rel = relative(rootAbs, absPath);
-	if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
-	return absPath;
-}
-function formatZodIssues$1(error) {
-	return error.issues.map((issue) => {
-		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
-	}).join("; ");
-}
-//#endregion
-//#region src/agent/browser.ts
-async function launchAgentBrowser(args) {
-	let lastError;
-	for (let attempt = 0; attempt < 5; attempt += 1) try {
-		const browser = await chromium.launch({ headless: args.headless });
-		await verifyBrowserLaunch(browser);
-		return browser;
-	} catch (error) {
-		lastError = error;
-		if (!isTransientBrowserLaunchError(error) || attempt === 4) throw error;
-		await new Promise((resolveRetry) => setTimeout(resolveRetry, 250 * (attempt + 1)));
-	}
-	throw lastError;
-}
-async function verifyBrowserLaunch(browser) {
-	const context = await browser.newContext();
-	try {
-		const page = await context.newPage();
-		await page.goto("data:text/html,<title>ptywright</title>", { waitUntil: "load" });
-		await page.close();
-	} catch (error) {
-		await browser.close();
-		throw error;
-	} finally {
-		await context.close().catch(() => void 0);
-	}
-}
-function isTransientBrowserLaunchError(error) {
-	const fields = errorFields(error);
-	return fields.message.includes("Failed to connect") || fields.message.includes("Target page, context or browser has been closed") || fields.message.includes("browserType.launch") || fields.code === "ENOENT" || fields.code === "ECONNREFUSED" || fields.syscall === "connect";
-}
-function errorFields(error) {
-	const record = typeof error === "object" && error !== null ? error : {};
-	return {
-		message: error instanceof Error ? error.message : String(error),
-		code: typeof record.code === "string" ? record.code : "",
-		syscall: typeof record.syscall === "string" ? record.syscall : ""
-	};
-}
-//#endregion
 //#region src/agent/normalize.ts
-function applyAgentMasks(input, rules = []) {
+function applyAgentMasks(input, rules = [], options = {}) {
 	let out = input;
 	for (const rule of rules) {
 		const flags = rule.flags ?? "g";
 		const regex = new RegExp(rule.regex, flags.includes("g") ? flags : `${flags}g`);
-		const replacement = rule.replacement ?? "<masked>";
+		const replacement = options.replacement?.(rule.replacement ?? "<masked>") ?? rule.replacement ?? "<masked>";
 		out = out.replace(regex, (match) => {
 			if (!rule.preserveLength) return replacement;
 			if (replacement.length === match.length) return replacement;
@@ -234,7 +34,7 @@ function normalizeTerminalText(input, rules = []) {
 	return lines.join("\n");
 }
 function normalizeDomSnapshot(input, rules = []) {
-	return applyAgentMasks(input.replace(/\sdata-v-[a-z0-9-]+="[^"]*"/g, "").replace(/\sstyle="[^"]*--term-(?:cell-width|row-height):[^"]*"/g, "").replace(/\s+/g, " ").replace(/>\s+</g, "><").replace(/<div class="[^"]*\bterm-row\b[^"]*\bterm-scrollback-row\b[^"]*"[^>]*><span[^>]*><\/span><\/div>/g, "").trim(), rules);
+	return applyAgentMasks(input.replace(/\sdata-v-[a-z0-9-]+="[^"]*"/g, "").replace(/\sstyle="[^"]*--term-(?:cell-width|row-height):[^"]*"/g, "").replace(/\s+/g, " ").replace(/>\s+</g, "><").replace(/<div class="[^"]*\bterm-row\b[^"]*\bterm-scrollback-row\b[^"]*"[^>]*><span[^>]*><\/span><\/div>/g, "").trim(), rules, { replacement: escapeHtmlText });
 }
 function sanitizeArtifactName(input) {
 	return input.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "artifact";
@@ -247,6 +47,9 @@ function shortHash(input) {
 	}
 	return hash.toString(16).padStart(8, "0");
 }
+function escapeHtmlText(input) {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
 //#endregion
 //#region src/agent/schema.ts
 const agentTextMaskRuleSchema = z.object({
@@ -394,73 +197,15 @@ function resolveAgentLaunchMode(launch) {
 	return inferAgentLaunchMode(launch);
 }
 //#endregion
-//#region src/agent/cassette.ts
-const AGENT_CASSETTE_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json";
-const agentCassetteFrameSchema = z.object({
-	viewport: agentViewportSchema,
-	phase: z.number().int().nonnegative(),
-	stepIndex: z.number().int().nonnegative().nullable(),
-	stepType: z.string().min(1),
-	terminalText: z.string(),
-	terminalHash: z.string().min(1),
-	dom: z.string(),
-	domHash: z.string().min(1),
-	capturedAt: z.string().min(1)
-});
-const agentCassetteSchema = z.object({
-	$schema: z.string().optional(),
-	version: z.literal(1),
-	name: z.string().min(1),
-	createdAt: z.string().min(1),
-	spec: agentFlowSpecSchema.optional(),
-	frames: z.array(agentCassetteFrameSchema).min(1)
-});
-function createAgentCassette(name, spec) {
-	return {
-		$schema: AGENT_CASSETTE_SCHEMA_URL,
-		version: 1,
-		name,
-		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-		spec: normalizeAgentFlowSpec(spec),
-		frames: []
-	};
-}
-function normalizeAgentCassette(input, fallbackSpec) {
-	const parsed = agentCassetteSchema.parse(input);
-	const specInput = parsed.spec ?? fallbackSpec;
-	if (!specInput) throw new Error("invalid agent cassette: missing spec");
-	validateCassetteFrameHashes(parsed.frames);
-	return {
-		...parsed,
-		$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json",
-		spec: normalizeAgentFlowSpec(specInput)
-	};
-}
-function validateCassetteFrameHashes(frames) {
-	for (const frame of frames) {
-		if (shortHash(frame.terminalText) !== frame.terminalHash) throw new Error(`invalid agent cassette: terminal hash mismatch viewport=${frame.viewport.name} phase=${frame.phase}`);
-		if (shortHash(frame.dom) !== frame.domHash) throw new Error(`invalid agent cassette: dom hash mismatch viewport=${frame.viewport.name} phase=${frame.phase}`);
-	}
-}
-function readAgentCassettePath(path, fallbackSpec) {
-	return normalizeAgentCassette(JSON.parse(readFileSync(path, "utf8")), fallbackSpec);
-}
-function isAgentCassetteLike(input) {
-	return typeof input === "object" && input !== null && input.version === 1 && Array.isArray(input.frames);
+//#region src/agent/html_escape.ts
+function escapeHtml(input) {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function upsertAgentCassetteFrame(cassette, frame) {
-	const next = {
-		...frame,
-		terminalHash: shortHash(frame.terminalText),
-		domHash: shortHash(frame.dom)
-	};
-	const index = cassette.frames.findIndex((candidate) => candidate.viewport.name === next.viewport.name && candidate.phase === next.phase);
-	if (index >= 0) {
-		cassette.frames[index] = next;
-		return;
-	}
-	cassette.frames.push(next);
+function escapeAttribute(input) {
+	return escapeHtml(input).replace(/'/g, "&#39;");
 }
+//#endregion
+//#region src/agent/cassette_server.ts
 async function startAgentCassetteServer(cassette) {
 	const sockets = /* @__PURE__ */ new Set();
 	const server = createServer((request, response) => {
@@ -496,7 +241,7 @@ async function startAgentCassetteServer(cassette) {
 	});
 	const address = server.address();
 	if (!address || typeof address === "string") {
-		await closeServer(server);
+		await closeServer(server, sockets);
 		throw new Error("failed to bind cassette replay server");
 	}
 	return {
@@ -511,7 +256,7 @@ function renderCassetteHtml(cassette) {
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${escapeHtml$1(cassette.name)} cassette replay</title>
+    <title>${escapeHtml(cassette.name)} cassette replay</title>
     <style>
       :root {
         color-scheme: dark;
@@ -542,10 +287,25 @@ function renderCassetteHtml(cassette) {
       const root = document.querySelector("[data-terminal-root]");
       let phase = 0;
 
+      function queryViewport() {
+        const params = new URLSearchParams(window.location.search);
+        const width = Number.parseInt(params.get("viewportWidth") || "", 10);
+        const height = Number.parseInt(params.get("viewportHeight") || "", 10);
+        const name = params.get("viewportName") || "";
+        return {
+          height: Number.isFinite(height) && height > 0 ? height : window.innerHeight,
+          name,
+          width: Number.isFinite(width) && width > 0 ? width : window.innerWidth,
+        };
+      }
+
       function viewportScore(frame) {
         const viewport = frame.viewport || {};
-        return Math.abs((viewport.width || window.innerWidth) - window.innerWidth) +
-          Math.abs((viewport.height || window.innerHeight) - window.innerHeight);
+        const target = queryViewport();
+        const namePenalty = target.name && viewport.name !== target.name ? 100000 : 0;
+        return namePenalty +
+          Math.abs((viewport.width || target.width) - target.width) +
+          Math.abs((viewport.height || target.height) - target.height);
       }
 
       function chooseFrame() {
@@ -620,288 +380,193 @@ async function closeServer(server, sockets) {
 		});
 	});
 }
-function escapeHtml$1(input) {
-	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
 //#endregion
-//#region src/agent/config_defaults.ts
-function normalizeAgentFlowSpecWithConfig(input, config) {
-	return normalizeAgentFlowSpec(applyAgentConfigDefaults(agentFlowSpecSchema.parse(input), config));
-}
-function applyAgentConfigDefaults(input, config) {
-	const agent = config?.agent;
-	if (!agent) return input;
-	const name = sanitizeArtifactName(input.name ?? "agent-flow");
-	const configDefaults = agent.defaults ?? {};
-	const specDefaults = input.defaults ?? {};
-	const viewports = input.viewports ? void 0 : cloneViewports(configDefaults.viewports);
-	return {
-		...input,
-		artifactsDir: input.artifactsDir ?? resolveNamedDir(agent.artifactsRoot, name, config.rootDir),
-		snapshotDir: input.snapshotDir ?? resolveNamedDir(agent.snapshotDir, name, config.rootDir),
-		viewports: viewports ?? input.viewports,
-		defaults: {
-			...specDefaults,
-			timeoutMs: specDefaults.timeoutMs ?? configDefaults.timeoutMs,
-			screenshot: specDefaults.screenshot ?? configDefaults.screenshot,
-			mask: mergeMaskRules(configDefaults.mask, specDefaults.mask)
-		}
-	};
-}
-function resolveNamedDir(root, name, configRoot) {
-	if (!root) return void 0;
-	const namedDir = join(root, name);
-	return isAbsolute(namedDir) ? namedDir : resolve(configRoot, namedDir);
-}
-function cloneViewports(viewports) {
-	return Array.isArray(viewports) && viewports.length > 0 ? viewports.map((viewport) => ({ ...viewport })) : void 0;
-}
-function mergeMaskRules(configMask, specMask) {
-	const merged = [...configMask ?? [], ...specMask ?? []];
-	return merged.length > 0 ? merged : void 0;
-}
-//#endregion
-//#region src/agent/command_launch.ts
-const DEFAULT_URL_REGEX = /https?:\/\/[^\s"'<>]+/;
-function buildCommandLaunchCommand(launch, options = {}) {
-	if (!launch.command) throw new Error("launch.command is required when launch.mode is 'command'");
-	const rootDir = options.rootDir ?? process.cwd();
-	const cwd = launch.cwd ? resolve(rootDir, launch.cwd) : rootDir;
+//#region src/agent/cassette.ts
+const AGENT_CASSETTE_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json";
+const agentCassetteFrameSchema = z.object({
+	viewport: agentViewportSchema,
+	phase: z.number().int().nonnegative(),
+	stepIndex: z.number().int().nonnegative().nullable(),
+	stepType: z.string().min(1),
+	terminalText: z.string(),
+	terminalHash: z.string().min(1),
+	dom: z.string(),
+	domHash: z.string().min(1),
+	capturedAt: z.string().min(1)
+});
+const agentCassetteSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	name: z.string().min(1),
+	createdAt: z.string().min(1),
+	spec: agentFlowSpecSchema.optional(),
+	frames: z.array(agentCassetteFrameSchema).min(1)
+});
+function createAgentCassette(name, spec) {
 	return {
-		file: launch.command,
-		args: launch.args ?? [],
-		cwd,
-		env: {
-			...options.env ?? process.env,
-			...launch.env
-		},
-		label: launch.command,
-		urlRegex: launch.urlRegex,
-		waitForUrlMs: launch.waitForUrlMs
+		$schema: AGENT_CASSETTE_SCHEMA_URL,
+		version: 1,
+		name,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		spec: normalizeAgentFlowSpec(spec),
+		frames: []
 	};
 }
-async function launchBrowserSessionFromCommand(command) {
-	const timeoutMs = command.waitForUrlMs ?? 15e3;
-	const child = spawn(command.file, command.args, {
-		cwd: command.cwd,
-		env: command.env,
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		]
-	});
-	const stdoutChunks = [];
-	const stderrChunks = [];
+function normalizeAgentCassette(input, fallbackSpec) {
+	const parsed = agentCassetteSchema.parse(input);
+	const specInput = parsed.spec ?? fallbackSpec;
+	if (!specInput) throw new Error("invalid agent cassette: missing spec");
+	validateCassetteFrameHashes(parsed.frames);
 	return {
-		url: await new Promise((resolveUrl, reject) => {
-			let settled = false;
-			const timer = setTimeout(() => {
-				finish(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for ${command.label ?? command.file} session URL\nstdout=${stdoutChunks.join("").trim()}\nstderr=${stderrChunks.join("").trim()}`));
-			}, timeoutMs);
-			const finish = (result) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timer);
-				child.stdout.off("data", onStdout);
-				child.stderr.off("data", onStderr);
-				child.off("error", onError);
-				child.off("exit", onExit);
-				if (result instanceof Error) reject(result);
-				else resolveUrl(result);
-			};
-			const readUrl = () => {
-				const found = extractUrlFromOutput(`${stdoutChunks.join("")}\n${stderrChunks.join("")}`, command.urlRegex);
-				if (found) finish(found);
-			};
-			const onStdout = (chunk) => {
-				stdoutChunks.push(chunk.toString("utf8"));
-				readUrl();
-			};
-			const onStderr = (chunk) => {
-				stderrChunks.push(chunk.toString("utf8"));
-				readUrl();
-			};
-			const onError = (error) => finish(error);
-			const onExit = (code, signal) => {
-				finish(/* @__PURE__ */ new Error(`${command.label ?? command.file} exited before printing a session URL (code=${code ?? "null"} signal=${signal ?? "null"})\nstdout=${stdoutChunks.join("").trim()}\nstderr=${stderrChunks.join("").trim()}`));
-			};
-			child.stdout.on("data", onStdout);
-			child.stderr.on("data", onStderr);
-			child.once("error", onError);
-			child.once("exit", onExit);
-		}),
-		process: child,
-		close: () => closeChild(child)
+		...parsed,
+		$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-cassette.schema.json",
+		spec: normalizeAgentFlowSpec(specInput)
 	};
 }
-function extractUrlFromOutput(output, regexSource) {
-	if (!regexSource) return output.match(DEFAULT_URL_REGEX)?.[0] ?? null;
-	const match = output.match(new RegExp(regexSource, "m"));
-	return match?.[1] ?? match?.[0] ?? null;
-}
-function formatBrowserLaunchCommand(command) {
-	return [command.file, ...command.args].join(" ");
+function validateCassetteFrameHashes(frames) {
+	for (const frame of frames) {
+		if (shortHash(frame.terminalText) !== frame.terminalHash) throw new Error(`invalid agent cassette: terminal hash mismatch viewport=${frame.viewport.name} phase=${frame.phase}`);
+		if (shortHash(frame.dom) !== frame.domHash) throw new Error(`invalid agent cassette: dom hash mismatch viewport=${frame.viewport.name} phase=${frame.phase}`);
+	}
 }
-async function closeChild(child) {
-	if (child.exitCode !== null || child.signalCode !== null) return;
-	await new Promise((resolveClose) => {
-		const timer = setTimeout(() => {
-			if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
-			resolveClose();
-		}, 2e3);
-		child.once("exit", () => {
-			clearTimeout(timer);
-			resolveClose();
-		});
-		child.kill("SIGTERM");
-	});
+function readAgentCassettePath(path, fallbackSpec) {
+	return normalizeAgentCassette(JSON.parse(readFileSync(path, "utf8")), fallbackSpec);
 }
-//#endregion
-//#region src/agent/launch.ts
-function buildAgentLaunchCommand(launch, options = {}) {
-	if (resolveAgentLaunchMode(launch) === "url") return null;
-	return buildCommandLaunchCommand(launch, options);
+function isAgentCassetteLike(input) {
+	return typeof input === "object" && input !== null && input.version === 1 && Array.isArray(input.frames);
 }
-async function resolveAgentLaunchTarget(launch, options = {}) {
-	const mode = resolveAgentLaunchMode(launch);
-	if (mode === "url") return {
-		mode,
-		url: launch.url,
-		session: null
-	};
-	const session = await launchBrowserSessionFromCommand(buildCommandLaunchCommand(launch, options));
-	return {
-		mode,
-		url: session.url,
-		session
+function upsertAgentCassetteFrame(cassette, frame) {
+	const next = {
+		...frame,
+		terminalHash: shortHash(frame.terminalText),
+		domHash: shortHash(frame.dom)
 	};
-}
-function formatAgentLaunchCommand(launch) {
-	const command = buildAgentLaunchCommand(launch);
-	return command ? formatBrowserLaunchCommand(command) : "launch.mode=url";
+	const index = cassette.frames.findIndex((candidate) => candidate.viewport.name === next.viewport.name && candidate.phase === next.phase);
+	if (index >= 0) {
+		cassette.frames[index] = next;
+		return;
+	}
+	cassette.frames.push(next);
 }
 //#endregion
-//#region src/agent/presets.ts
-const COMMON_AGENT_MASKS = [
-	{
-		regex: "\\b\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:?\\d{2})?\\b",
-		replacement: "<timestamp>"
-	},
-	{
-		regex: "\\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\b",
-		flags: "gi",
-		replacement: "<uuid>"
-	},
-	{
-		regex: "\\b(?:req|run|msg|chatcmpl|call|toolu|session)_[A-Za-z0-9_-]{8,}\\b",
-		replacement: "<id>"
-	},
-	{
-		regex: "\\b(?:[0-9a-f]{7,40})\\b",
-		flags: "gi",
-		replacement: "<hex>"
-	},
-	{
-		regex: "\\$\\d+(?:\\.\\d{2,6})?\\b",
-		replacement: "$<amount>"
-	},
-	{
-		regex: "\\b(?:\\d+\\.\\d+|\\d+)\\s*(?:s|ms|tokens?|tok)\\b",
-		flags: "gi",
-		replacement: "<metric>"
-	}
-];
-const FLAVOR_MASKS = {
-	codex: [{
-		regex: "\\b(?:gpt|o)[A-Za-z0-9._:-]+\\b",
-		flags: "gi",
-		replacement: "<model>"
-	}, {
-		regex: "\\b(?:context|tokens?)\\s*[:=]\\s*[0-9,]+\\b",
-		flags: "gi",
-		replacement: "<token-count>"
-	}],
-	claude: [{
-		regex: "\\bclaude-[A-Za-z0-9._-]+\\b",
-		flags: "gi",
-		replacement: "<model>"
-	}, {
-		regex: "\\b(?:Opus|Sonnet|Haiku)\\s+[0-9.]+\\b",
-		flags: "gi",
-		replacement: "<model>"
-	}],
-	droid: [{
-		regex: "\\bdroidx?-[A-Za-z0-9._-]+\\b",
-		flags: "gi",
-		replacement: "<droid-id>"
-	}],
-	generic: []
-};
-const DEFAULT_VIEWPORTS = [{
-	name: "desktop",
-	width: 1280,
-	height: 820
-}, {
-	name: "mobile",
-	width: 390,
-	height: 844,
-	isMobile: true,
-	hasTouch: true
-}];
-function resolveAgentFlavor(spec) {
-	const explicit = spec.launch.agentFlavor;
-	if (explicit) return explicit;
-	const command = spec.launch.command?.split(/[\\/]/).at(-1)?.toLowerCase() ?? "";
-	if (command === "codex" || command.startsWith("codex-")) return "codex";
-	if (command === "claude" || command === "claude-code" || command.startsWith("claude-")) return "claude";
-	if (command === "droid" || command === "droidx" || command.startsWith("droid")) return "droid";
-	return "generic";
+//#region src/agent/manifest.ts
+const AGENT_MANIFEST_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-manifest.schema.json";
+const AGENT_MANIFEST_FILE_NAME = "ptywright-agent.manifest.json";
+const agentManifestKindSchema = z.enum([
+	"run",
+	"replay-suite",
+	"check",
+	"promote"
+]);
+const agentManifestFileKindSchema = z.enum([
+	"flow",
+	"cassette",
+	"run-record",
+	"replay-summary",
+	"check-summary",
+	"promote-summary",
+	"report",
+	"terminal",
+	"dom",
+	"screenshot",
+	"diff"
+]);
+const agentManifestCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentManifestValidationStageSchema = z.object({
+	name: z.string().min(1),
+	ok: z.boolean(),
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative()
+}).strict();
+const agentManifestValidationSchema = z.object({
+	ok: z.boolean(),
+	stages: z.array(agentManifestValidationStageSchema)
+}).strict().superRefine((validation, ctx) => {
+	const ok = validation.stages.every((stage) => stage.ok && stage.failureCount === 0);
+	if (validation.ok !== ok) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["ok"],
+		message: "validation ok must match validation stages"
+	});
+});
+const agentManifestFileSchema = z.object({
+	path: z.string().min(1),
+	kind: agentManifestFileKindSchema,
+	role: z.string().min(1).optional(),
+	ok: z.boolean().optional(),
+	bytes: z.number().int().nonnegative(),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+const agentManifestSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	kind: agentManifestKindSchema,
+	ok: z.boolean(),
+	generatedAt: z.string().min(1),
+	rootDir: z.string().min(1),
+	primaryPath: z.string().min(1),
+	commands: z.record(agentManifestCommandSchema),
+	validation: agentManifestValidationSchema.optional(),
+	files: z.array(agentManifestFileSchema)
+}).strict().superRefine((manifest, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const file of manifest.files) {
+		if (seen.has(file.path)) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["files"],
+			message: `duplicate manifest file path: ${file.path}`
+		});
+		seen.add(file.path);
+	}
+});
+function agentManifestPath(rootDir) {
+	return join(rootDir, AGENT_MANIFEST_FILE_NAME);
 }
-function getAgentMaskPreset(flavor) {
-	return [...COMMON_AGENT_MASKS, ...FLAVOR_MASKS[flavor]];
+function createAgentManifest(options) {
+	return normalizeAgentManifest({
+		$schema: AGENT_MANIFEST_SCHEMA_URL,
+		version: 1,
+		kind: options.kind,
+		ok: options.ok,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		rootDir: options.rootDir,
+		primaryPath: options.primaryPath,
+		commands: options.commands,
+		validation: options.validation,
+		files: collectManifestFiles(options.files, options.rootDir)
+	});
 }
-function resolveAgentMasks(spec) {
-	return [...getAgentMaskPreset(resolveAgentFlavor(spec)), ...spec.defaults?.mask ?? []];
+function readAgentManifestPath(path) {
+	return normalizeAgentManifest(JSON.parse(readFileSync(path, "utf8")));
 }
-function createAgentTemplateSpec(flavor) {
-	const command = flavor === "droid" ? "droidx" : flavor === "generic" ? "agent" : flavor;
-	const name = flavor === "generic" ? "agent_browser_smoke" : `${flavor}_browser_smoke`;
-	return {
-		name,
-		artifactsDir: `.tmp/agent/${name}`,
-		snapshotDir: `tests/agent-snapshots/${name}`,
-		launch: {
-			mode: "command",
-			agentFlavor: flavor,
-			command: "your-browser-terminal-launcher",
-			args: [
-				"--agent",
-				command,
-				"--print-url"
-			],
-			waitForUrlMs: 15e3
-		},
-		viewports: DEFAULT_VIEWPORTS.map((viewport) => ({ ...viewport })),
-		defaults: {
-			timeoutMs: 45e3,
-			screenshot: true
-		},
-		steps: [{
-			type: "waitForStableDom",
-			timeoutMs: 45e3,
-			quietMs: 600,
-			intervalMs: 150
-		}, {
-			type: "snapshot",
-			name: "launch",
-			targets: [
-				"terminal",
-				"dom",
-				"screenshot"
-			]
-		}]
-	};
+function writeAgentManifestPath(path, options) {
+	const manifest = createAgentManifest(options);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+	return manifest;
+}
+function normalizeAgentManifest(input) {
+	try {
+		const parsed = agentManifestSchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-manifest.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent manifest: ${formatZodIssues(error)}`);
+		throw error;
+	}
+}
+function validateAgentManifestFiles(manifest, manifestPath) {
+	validateManifestFiles({
+		files: manifest.files,
+		manifestPath,
+		rootDir: manifest.rootDir,
+		label: "agent"
+	});
+}
+function isAgentManifestLike(input) {
+	return typeof input === "object" && input !== null && input.version === 1 && typeof input.kind === "string" && Array.isArray(input.files) && typeof input.commands === "object";
 }
 //#endregion
 //#region src/common/argv.ts
@@ -1011,9 +676,6 @@ function normalizeAgentRunRecord(input) {
 function formatAgentArgv(argv) {
 	return formatArgv(argv);
 }
-function sameArgv(left, right) {
-	return left.length === right.length && left.every((value, index) => value === right[index]);
-}
 function isReplayArgv(argv) {
 	return argv.length >= 4 && argv[0] === "ptywright" && argv[1] === "agent" && argv[2] === "replay";
 }
@@ -1032,175 +694,1609 @@ function isAgentRunRecordLike(input) {
 	const candidate = input;
 	return candidate.version === 1 && ("cassettePath" in candidate || "flowPath" in candidate || "spec" in candidate);
 }
-function formatZodIssues(error) {
-	return error.issues.map((issue) => {
-		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
-	}).join("; ");
-}
 //#endregion
-//#region src/agent/report.ts
-function writeAgentReport(path, result) {
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, renderAgentReportHtml(result), "utf8");
+//#region src/agent/spec_loader.ts
+async function loadAgentSpec(specPath) {
+	const resolved = resolve(process.cwd(), specPath);
+	if (resolved.endsWith(".json")) {
+		const raw = JSON.parse(readFileSync(resolved, "utf8"));
+		return {
+			spec: normalizeAgentFlowSpec(raw),
+			raw,
+			path: resolved
+		};
+	}
+	const mod = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
+	const raw = mod.default ?? mod.spec;
+	return {
+		spec: normalizeAgentFlowSpec(raw),
+		raw,
+		path: resolved
+	};
 }
-function renderAgentReportHtml(result) {
-	const artifacts = result.artifacts.map((artifact) => renderArtifactRow(artifact, result.artifactsDir, result.reportPath)).join("\n");
-	const viewportTabs = result.viewports.map((viewport) => `<span class="pill">${escapeHtml(viewport.name)} ${viewport.width}x${viewport.height}</span>`).join("");
-	const status = result.ok ? "passed" : "failed";
-	return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${escapeHtml(`${result.name} terminal-agent report`)}</title>
-    <style>
-      :root {
-        color-scheme: light;
-        --bg: oklch(97.5% 0.008 210);
-        --ink: oklch(19% 0.018 230);
-        --muted: oklch(48% 0.02 230);
-        --line: oklch(86% 0.018 230);
-        --panel: oklch(99% 0.006 210);
-        --good: oklch(55% 0.15 155);
-        --bad: oklch(58% 0.19 25);
-        --focus: oklch(55% 0.14 235);
-        font-family:
-          ui-sans-serif,
-          system-ui,
-          -apple-system,
-          BlinkMacSystemFont,
-          "Segoe UI",
-          sans-serif;
-      }
-      * { box-sizing: border-box; }
-      body {
-        margin: 0;
-        background: var(--bg);
-        color: var(--ink);
-      }
-      main {
-        display: grid;
-        gap: 24px;
-        width: min(1180px, calc(100vw - 32px));
-        margin: 0 auto;
-        padding: 32px 0 48px;
-      }
-      header {
-        display: grid;
-        grid-template-columns: minmax(0, 1fr) auto;
-        gap: 20px;
-        align-items: start;
-        border-bottom: 1px solid var(--line);
-        padding-bottom: 24px;
-      }
-      h1 {
-        margin: 0;
-        font-size: 28px;
-        line-height: 1.15;
-        letter-spacing: 0;
-      }
-      h2 {
-        margin: 0;
-        font-size: 18px;
-        line-height: 1.25;
-      }
-      .meta {
-        display: flex;
-        flex-wrap: wrap;
-        gap: 8px;
-        margin-top: 12px;
-      }
-      .pill,
-      .status {
-        display: inline-flex;
-        min-height: 32px;
+//#endregion
+//#region src/agent/presets.ts
+const COMMON_AGENT_MASKS = [
+	{
+		regex: "\\b\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:?\\d{2})?\\b",
+		replacement: "<timestamp>"
+	},
+	{
+		regex: "\\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\b",
+		flags: "gi",
+		replacement: "<uuid>"
+	},
+	{
+		regex: "\\b(?:req|run|msg|chatcmpl|call|toolu|session)_[A-Za-z0-9_-]{8,}\\b",
+		replacement: "<id>"
+	},
+	{
+		regex: "\\b(?:[0-9a-f]{7,40})\\b",
+		flags: "gi",
+		replacement: "<hex>"
+	},
+	{
+		regex: "\\$\\d+(?:\\.\\d{2,6})?\\b",
+		replacement: "$<amount>"
+	},
+	{
+		regex: "\\b(?:\\d+\\.\\d+|\\d+)\\s*(?:s|ms|tokens?|tok)\\b",
+		flags: "gi",
+		replacement: "<metric>"
+	}
+];
+const FLAVOR_MASKS = {
+	codex: [{
+		regex: "\\b(?:gpt-[A-Za-z0-9._:-]+|o[0-9][A-Za-z0-9._:-]*)\\b",
+		flags: "gi",
+		replacement: "<model>"
+	}, {
+		regex: "\\b(?:context|tokens?)\\s*[:=]\\s*[0-9,]+\\b",
+		flags: "gi",
+		replacement: "<token-count>"
+	}],
+	claude: [{
+		regex: "\\bclaude-[A-Za-z0-9._-]+\\b",
+		flags: "gi",
+		replacement: "<model>"
+	}, {
+		regex: "\\b(?:Opus|Sonnet|Haiku)\\s+[0-9.]+\\b",
+		flags: "gi",
+		replacement: "<model>"
+	}],
+	droid: [{
+		regex: "\\bdroidx?-[A-Za-z0-9._-]+\\b",
+		flags: "gi",
+		replacement: "<droid-id>"
+	}],
+	generic: []
+};
+const DEFAULT_VIEWPORTS = [{
+	name: "desktop",
+	width: 1280,
+	height: 820
+}, {
+	name: "mobile",
+	width: 390,
+	height: 844,
+	isMobile: true,
+	hasTouch: true
+}];
+function resolveAgentFlavor(spec) {
+	const explicit = spec.launch.agentFlavor;
+	if (explicit) return explicit;
+	const command = spec.launch.command?.split(/[\\/]/).at(-1)?.toLowerCase() ?? "";
+	if (command === "codex" || command.startsWith("codex-")) return "codex";
+	if (command === "claude" || command === "claude-code" || command.startsWith("claude-")) return "claude";
+	if (command === "droid" || command === "droidx" || command.startsWith("droid")) return "droid";
+	return "generic";
+}
+function getAgentMaskPreset(flavor) {
+	return [...COMMON_AGENT_MASKS, ...FLAVOR_MASKS[flavor]];
+}
+function resolveAgentMasks(spec) {
+	return [...getAgentMaskPreset(resolveAgentFlavor(spec)), ...spec.defaults?.mask ?? []];
+}
+function createAgentTemplateSpec(flavor) {
+	const command = flavor === "droid" ? "droidx" : flavor === "generic" ? "agent" : flavor;
+	const name = flavor === "generic" ? "agent_browser_smoke" : `${flavor}_browser_smoke`;
+	return {
+		name,
+		artifactsDir: `.tmp/agent/${name}`,
+		snapshotDir: `tests/agent-snapshots/${name}`,
+		launch: {
+			mode: "command",
+			agentFlavor: flavor,
+			command: "your-browser-terminal-launcher",
+			args: [
+				"--agent",
+				command,
+				"--print-url"
+			],
+			waitForUrlMs: 15e3
+		},
+		viewports: DEFAULT_VIEWPORTS.map((viewport) => ({ ...viewport })),
+		defaults: {
+			timeoutMs: 45e3,
+			screenshot: true
+		},
+		steps: [{
+			type: "waitForStableDom",
+			timeoutMs: 45e3,
+			quietMs: 600,
+			intervalMs: 150
+		}, {
+			type: "snapshot",
+			name: "launch",
+			targets: [
+				"terminal",
+				"dom",
+				"screenshot"
+			]
+		}]
+	};
+}
+//#endregion
+//#region src/agent/browser.ts
+async function launchAgentBrowser(args) {
+	let lastError;
+	for (let attempt = 0; attempt < 5; attempt += 1) try {
+		const browser = await chromium.launch({ headless: args.headless });
+		await verifyBrowserLaunch(browser);
+		return browser;
+	} catch (error) {
+		lastError = error;
+		if (!isTransientBrowserLaunchError(error) || attempt === 4) throw error;
+		await new Promise((resolveRetry) => setTimeout(resolveRetry, 250 * (attempt + 1)));
+	}
+	throw lastError;
+}
+async function verifyBrowserLaunch(browser) {
+	const context = await browser.newContext();
+	try {
+		const page = await context.newPage();
+		await page.goto("data:text/html,<title>ptywright</title>", { waitUntil: "load" });
+		await page.close();
+	} catch (error) {
+		await browser.close();
+		throw error;
+	} finally {
+		await context.close().catch(() => void 0);
+	}
+}
+function isTransientBrowserLaunchError(error) {
+	const fields = errorFields(error);
+	return fields.message.includes("Failed to connect") || fields.message.includes("Target page, context or browser has been closed") || fields.message.includes("browserType.launch") || fields.code === "ENOENT" || fields.code === "ECONNREFUSED" || fields.syscall === "connect";
+}
+function errorFields(error) {
+	const record = typeof error === "object" && error !== null ? error : {};
+	return {
+		message: error instanceof Error ? error.message : String(error),
+		code: typeof record.code === "string" ? record.code : "",
+		syscall: typeof record.syscall === "string" ? record.syscall : ""
+	};
+}
+//#endregion
+//#region src/agent/aitty_report_assets.ts
+function prepareAittyReportAssets(context) {
+	const sources = resolveAittyReportAssetSources(context);
+	if (!existsSync(sources.scriptSource) || !existsSync(sources.styleSource)) throw new Error("@aitty/snapshot report assets are missing. Run the package build before generating reports.");
+	const assetDir = join(context.artifactsDir, "assets");
+	const scriptPath = join(assetDir, "aitty-web-component.js");
+	const stylePath = join(assetDir, "aitty-terminal.css");
+	mkdirSync(assetDir, { recursive: true });
+	copyFileSync(sources.scriptSource, scriptPath);
+	copyFileSync(sources.styleSource, stylePath);
+	return {
+		scriptPath,
+		scriptType: sources.scriptType,
+		stylePath
+	};
+}
+function resolveAittyReportAssetSources(context) {
+	for (const resolverBase of resolveAittyReportResolverBases(context)) {
+		const sources = tryResolveAittyReportAssetSources(createRequire(resolverBase));
+		if (sources) return sources;
+	}
+	const fallback = tryResolveAittyReportAssetSources(createRequire(import.meta.url));
+	if (fallback) return fallback;
+	throw new Error("@aitty/snapshot report assets are missing. Install @aitty/snapshot or run the package build before generating reports.");
+}
+function resolveAittyReportResolverBases(context) {
+	const candidates = [
+		findNearestPackageJson(dirname(resolve(context.flowPath))),
+		findNearestPackageJson(dirname(resolve(context.reportPath))),
+		findNearestPackageJson(dirname(resolve(context.artifactsDir))),
+		findNearestPackageJson(process.cwd())
+	].filter((path) => Boolean(path));
+	return Array.from(new Set(candidates));
+}
+function findNearestPackageJson(startDir) {
+	let currentDir = resolve(startDir);
+	while (true) {
+		const packagePath = join(currentDir, "package.json");
+		if (existsSync(packagePath)) return packagePath;
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+function tryResolveAittyReportAssetSources(resolver) {
+	return tryResolveAittyPackageAssetSources(resolver, "@aitty/snapshot") ?? tryResolveAittyPackageAssetSources(resolver, "@aitty/browser");
+}
+function tryResolveAittyPackageAssetSources(resolver, packageName) {
+	let scriptSource;
+	let scriptType = "classic";
+	let styleSource;
+	try {
+		scriptSource = resolver.resolve(`${packageName}/web-component.global.js`);
+	} catch {
+		try {
+			scriptSource = resolver.resolve(`${packageName}/web-component.js`);
+			scriptType = "module";
+		} catch {
+			return null;
+		}
+	}
+	try {
+		styleSource = resolver.resolve(`${packageName}/style.css`);
+	} catch {
+		return null;
+	}
+	return {
+		scriptSource,
+		scriptType,
+		styleSource
+	};
+}
+//#endregion
+//#region src/agent/report_paths.ts
+function relativeHref(fromPath, targetPath, artifactsDir) {
+	if (targetPath.startsWith(artifactsDir)) return relative(dirname(fromPath), targetPath).replaceAll("\\", "/") || ".";
+	return targetPath;
+}
+//#endregion
+//#region src/agent/report_aitty_preview.ts
+function resolveAittyPreviewAssets(previewPath, assets, artifactsDir) {
+	return {
+		scriptHref: relativeHref(previewPath, assets.scriptPath, artifactsDir),
+		scriptType: assets.scriptType,
+		styleHref: relativeHref(previewPath, assets.stylePath, artifactsDir)
+	};
+}
+function renderAittyPreviewAssetTags(assets) {
+	return `    <link rel="stylesheet" href="${escapeAttribute(assets.styleHref)}" />
+    <script${assets.scriptType === "module" ? " type=\"module\"" : ""} src="${escapeAttribute(assets.scriptHref)}"><\/script>
+`;
+}
+function renderAittyPreviewBody(args) {
+	const { snapshot, snapshotLayout, viewOptions } = args;
+	return `    <aitty-snapshot
+      cols="${snapshotLayout.cols}"
+      rows="${snapshotLayout.rows}"
+      screen-mode="${escapeAttribute(viewOptions.screenMode)}"
+      theme="${escapeAttribute(viewOptions.theme)}"
+      font-size="${snapshotLayout.fontSize}"
+      line-height="${snapshotLayout.lineHeight}"
+    >${snapshot}</aitty-snapshot>`;
+}
+function renderAittyPreviewCss(viewOptions) {
+	return `      :root {
+        color-scheme: ${viewOptions.theme};
+      }
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+        margin: 0;
+        background: var(--theme-term-bg, Canvas);
+      }
+      aitty-snapshot {
+        display: block;
+        width: 100%;
+        height: 100%;
+      }`;
+}
+//#endregion
+//#region src/agent/report_artifact_paths.ts
+function artifactViewerPath(artifact) {
+	if (artifact.kind === "terminal") return artifact.path.endsWith(".terminal.txt") ? artifact.path.replace(/\.terminal\.txt$/, ".terminal.viewer.html") : `${artifact.path}.viewer.html`;
+	if (artifact.kind === "dom") return artifact.path.endsWith(".dom.html") ? artifact.path.replace(/\.dom\.html$/, ".dom.viewer.html") : `${artifact.path}.viewer.html`;
+	return null;
+}
+function artifactDomPreviewPath(artifact) {
+	return artifact.path.endsWith(".dom.html") ? artifact.path.replace(/\.dom\.html$/, ".dom.preview.html") : `${artifact.path}.preview.html`;
+}
+function artifactSnapshotKey(artifact) {
+	return `${artifact.viewport}\u0000${artifact.name}`;
+}
+//#endregion
+//#region src/agent/report_dom_artifact_viewer.ts
+function resolveReportDomPreview(path) {
+	return path ? { path } : null;
+}
+function renderDomArtifactViewer(args) {
+	const { artifactsDir, mobile, preview, viewerPath, viewOptions } = args;
+	const src = relativeHref(viewerPath, preview.path, artifactsDir);
+	return `<div class="viewer-viewport dom-viewport" data-mobile="${mobile ? "true" : "false"}" data-screen-mode="${escapeAttribute(viewOptions.screenMode)}"><iframe class="dom-viewer-frame" sandbox="allow-same-origin allow-scripts" src="${escapeAttribute(src)}" title="terminal DOM artifact"></iframe></div>`;
+}
+function renderDomArtifactViewerFragment(args) {
+	return {
+		css: "",
+		html: renderDomArtifactViewer(args),
+		script: ""
+	};
+}
+//#endregion
+//#region src/agent/report_raw_ansi_text.ts
+function renderRawAnsiTextHtml(input) {
+	const out = [];
+	let style = {};
+	let segmentStart = 0;
+	let index = 0;
+	while (index < input.length) {
+		if (!isCsiStart(input, index)) {
+			index += 1;
+			continue;
+		}
+		const end = findCsiEnd(input, index + 2);
+		if (end === -1) {
+			index += 1;
+			continue;
+		}
+		out.push(renderAnsiTextSegment(input.slice(segmentStart, index), style));
+		if (input[end] === "m") style = applySgrCodes(style, parseSgrCodes(input.slice(index + 2, end)));
+		index = end + 1;
+		segmentStart = index;
+	}
+	out.push(renderAnsiTextSegment(input.slice(segmentStart), style));
+	return out.join("");
+}
+function isCsiStart(input, index) {
+	return input.charCodeAt(index) === 27 && input[index + 1] === "[";
+}
+function findCsiEnd(input, start) {
+	for (let index = start; index < input.length; index += 1) {
+		const code = input.charCodeAt(index);
+		if (code >= 64 && code <= 126) return index;
+	}
+	return -1;
+}
+function parseSgrCodes(input) {
+	if (!input) return [0];
+	return input.split(";").map((value) => {
+		const parsed = Number.parseInt(value, 10);
+		return Number.isFinite(parsed) ? parsed : 0;
+	});
+}
+function applySgrCodes(current, codes) {
+	const next = { ...current };
+	for (let index = 0; index < codes.length; index += 1) {
+		const code = codes[index] ?? 0;
+		if (code === 0) {
+			resetStyle(next);
+			continue;
+		}
+		if (code === 1) next.bold = true;
+		else if (code === 2) next.dim = true;
+		else if (code === 3) next.italic = true;
+		else if (code === 4) next.underline = true;
+		else if (code === 7) next.inverse = true;
+		else if (code === 9) next.strikethrough = true;
+		else if (code === 22) {
+			next.bold = false;
+			next.dim = false;
+		} else if (code === 23) next.italic = false;
+		else if (code === 24) next.underline = false;
+		else if (code === 27) next.inverse = false;
+		else if (code === 29) next.strikethrough = false;
+		else if (code === 39) next.fg = void 0;
+		else if (code === 49) next.bg = void 0;
+		else if (code >= 30 && code <= 37) next.fg = ansiPaletteColor(code - 30);
+		else if (code >= 90 && code <= 97) next.fg = ansiPaletteColor(code - 90 + 8);
+		else if (code >= 40 && code <= 47) next.bg = ansiPaletteColor(code - 40);
+		else if (code >= 100 && code <= 107) next.bg = ansiPaletteColor(code - 100 + 8);
+		else if ((code === 38 || code === 48) && codes[index + 1] === 5) {
+			const color = ansiPaletteColor(codes[index + 2] ?? 0);
+			if (code === 38) next.fg = color;
+			else next.bg = color;
+			index += 2;
+		} else if ((code === 38 || code === 48) && codes[index + 1] === 2) {
+			const color = `rgb(${clampColor(codes[index + 2] ?? 0)} ${clampColor(codes[index + 3] ?? 0)} ${clampColor(codes[index + 4] ?? 0)})`;
+			if (code === 38) next.fg = color;
+			else next.bg = color;
+			index += 4;
+		}
+	}
+	return next;
+}
+function resetStyle(style) {
+	style.fg = void 0;
+	style.bg = void 0;
+	style.bold = false;
+	style.dim = false;
+	style.italic = false;
+	style.underline = false;
+	style.inverse = false;
+	style.strikethrough = false;
+}
+function renderAnsiTextSegment(text, style) {
+	if (!text) return "";
+	const safeText = escapeHtml(text);
+	const css = ansiStyleToCss(style);
+	return css ? `<span style="${escapeAttribute(css)}">${safeText}</span>` : safeText;
+}
+function ansiStyleToCss(style) {
+	const decls = [];
+	const fg = style.inverse ? style.bg : style.fg;
+	const bg = style.inverse ? style.fg : style.bg;
+	if (fg) decls.push(`color: ${fg}`);
+	if (bg) decls.push(`background-color: ${bg}`);
+	if (style.bold) decls.push("font-weight: 700");
+	if (style.italic) decls.push("font-style: italic");
+	if (style.dim) decls.push("opacity: 0.72");
+	const decorations = [];
+	if (style.underline) decorations.push("underline");
+	if (style.strikethrough) decorations.push("line-through");
+	if (decorations.length > 0) decls.push(`text-decoration: ${decorations.join(" ")}`);
+	return decls.join("; ");
+}
+function ansiPaletteColor(index) {
+	const table16 = [
+		"#151b23",
+		"#ff7b72",
+		"#7ee787",
+		"#f2cc60",
+		"#79c0ff",
+		"#d2a8ff",
+		"#70e1e8",
+		"#e6edf7",
+		"#6e7681",
+		"#ffa198",
+		"#aff5b4",
+		"#ffdf80",
+		"#a5d6ff",
+		"#e2c5ff",
+		"#96f0f5",
+		"#ffffff"
+	];
+	const normalized = clampColor(index);
+	if (normalized < table16.length) return table16[normalized] ?? "#e6edf7";
+	if (normalized <= 231) {
+		const values = [
+			0,
+			95,
+			135,
+			175,
+			215,
+			255
+		];
+		const offset = normalized - 16;
+		return `rgb(${values[Math.trunc(offset / 36) % 6] ?? 0} ${values[Math.trunc(offset / 6) % 6] ?? 0} ${values[offset % 6] ?? 0})`;
+	}
+	const gray = clampColor(8 + (normalized - 232) * 10);
+	return `rgb(${gray} ${gray} ${gray})`;
+}
+function clampColor(value) {
+	if (!Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(255, Math.trunc(value)));
+}
+//#endregion
+//#region src/agent/report_viewer_pan.ts
+function renderReportViewportPanCss() {
+	return `      [data-ptywright-report-pan="true"] {
+        cursor: grab;
+      }
+      [data-ptywright-report-panning="true"] {
+        cursor: grabbing;
+      }`;
+}
+function renderReportViewportPanScript(body) {
+	return `      (() => {
+        const isHtmlElement = (value) => {
+          return Boolean(
+            value &&
+            value.nodeType === 1 &&
+            value.dataset &&
+            value.style &&
+            typeof value.addEventListener === "function"
+          );
+        };
+
+        const scrollToBottom = (element) => {
+          element.scrollTop = Math.max(0, element.scrollHeight - element.clientHeight);
+        };
+
+        const enableViewportPan = (element) => {
+          if (!isHtmlElement(element) || element.dataset.ptywrightReportPan === "true") {
+            return;
+          }
+
+          element.dataset.ptywrightReportPan = "true";
+          let activePointerId = null;
+          let startX = 0;
+          let startY = 0;
+          let startScrollLeft = 0;
+          let startScrollTop = 0;
+          let moved = false;
+
+          element.addEventListener("pointerdown", (event) => {
+            if (event.button !== 0) return;
+            activePointerId = event.pointerId;
+            startX = event.clientX;
+            startY = event.clientY;
+            startScrollLeft = element.scrollLeft;
+            startScrollTop = element.scrollTop;
+            moved = false;
+            element.dataset.ptywrightReportPanning = "true";
+            element.setPointerCapture?.(event.pointerId);
+          });
+
+          element.addEventListener("pointermove", (event) => {
+            if (activePointerId !== event.pointerId) return;
+            const deltaX = event.clientX - startX;
+            const deltaY = event.clientY - startY;
+            if (Math.abs(deltaX) > 2 || Math.abs(deltaY) > 2) {
+              moved = true;
+            }
+            element.scrollLeft = startScrollLeft - deltaX;
+            element.scrollTop = startScrollTop - deltaY;
+            if (moved) event.preventDefault();
+          });
+
+          const finish = (event) => {
+            if (activePointerId !== event.pointerId) return;
+            activePointerId = null;
+            element.dataset.ptywrightReportPanning = "false";
+            element.releasePointerCapture?.(event.pointerId);
+          };
+
+          element.addEventListener("pointerup", finish);
+          element.addEventListener("pointercancel", finish);
+        };
+${body}
+      })();`;
+}
+//#endregion
+//#region src/agent/report_raw_artifact_viewer.ts
+function renderRawArtifactViewer(content, mobile, viewOptions) {
+	return `<div class="viewer-viewport raw-artifact-viewport" data-mobile="${mobile ? "true" : "false"}" data-screen-mode="${escapeAttribute(viewOptions.screenMode)}"><pre class="raw-artifact-text">${renderRawAnsiTextHtml(content)}</pre></div>`;
+}
+function renderRawArtifactViewerCss() {
+	return `      .raw-artifact-text {
+        min-width: 100%;
+        width: max-content;
+        min-height: 100%;
+        margin: 0;
+        background:
+          linear-gradient(180deg, color-mix(in srgb, #162033 92%, black), #0c111d);
+        color: #e6edf7;
+        font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, "Liberation Mono", monospace;
+        font-size: 13px;
+        line-height: 1.45;
+        overflow: visible;
+        padding: 12px;
+        white-space: pre;
+      }
+      .viewer-page[data-theme="light"] .raw-artifact-text {
+        background: #ffffff;
+        color: #4c4f69;
+      }
+${renderReportViewportPanCss()}`;
+}
+function renderRawArtifactViewerScript() {
+	return renderReportViewportPanScript(`
+        document.querySelectorAll(".raw-artifact-viewport").forEach((viewport) => {
+          enableViewportPan(viewport);
+          if (viewport.getAttribute("data-screen-mode") === "termvision") {
+            requestAnimationFrame(() => scrollToBottom(viewport));
+          }
+        });
+`);
+}
+function renderRawArtifactViewerFragment(args) {
+	const { content, mobile, viewOptions } = args;
+	return {
+		css: renderRawArtifactViewerCss(),
+		html: renderRawArtifactViewer(content, mobile, viewOptions),
+		script: renderRawArtifactViewerScript()
+	};
+}
+//#endregion
+//#region src/agent/report_artifact_viewer_fragment.ts
+function renderArtifactViewerFragment(args) {
+	const { artifactsDir, content, domViewerPreview, mobile, viewerPath, viewOptions } = args;
+	if (domViewerPreview) return renderDomArtifactViewerFragment({
+		artifactsDir,
+		mobile,
+		preview: domViewerPreview,
+		viewerPath,
+		viewOptions
+	});
+	return renderRawArtifactViewerFragment({
+		content,
+		mobile,
+		viewOptions
+	});
+}
+//#endregion
+//#region src/agent/report_artifact_viewer_shell_css.ts
+function renderArtifactViewerShellCss() {
+	return `      :root {
+        color-scheme: dark;
+        --bg: #080d16;
+        --panel: #0c111d;
+        --line: rgba(148, 163, 184, 0.26);
+        --ink: #e6edf7;
+        --muted: #91a0b8;
+        --focus: #79c0ff;
+        font-family:
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Segoe UI",
+          sans-serif;
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+        margin: 0;
+        overflow: hidden;
+        background: var(--bg);
+        color: var(--ink);
+      }
+      .viewer-page {
+        display: grid;
+        grid-template-rows: auto minmax(0, 1fr);
+        width: 100%;
+        height: 100dvh;
+        min-width: 0;
+        min-height: 0;
+      }
+      .viewer-toolbar {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        align-items: center;
+        min-width: 0;
+        border-bottom: 1px solid var(--line);
+        background: color-mix(in srgb, var(--panel) 88%, black);
+        padding: 10px 12px;
+      }
+      .viewer-title {
+        min-width: min(100%, 220px);
+        margin-right: auto;
+        overflow-wrap: anywhere;
+        font-size: 14px;
+        font-weight: 700;
+      }
+      .viewer-link,
+      .viewer-pill {
+        display: inline-flex;
+        min-height: 30px;
         align-items: center;
         border: 1px solid var(--line);
         border-radius: 999px;
-        padding: 0 12px;
+        padding: 0 10px;
         color: var(--muted);
-        font-size: 13px;
+        font-size: 12px;
+        text-decoration: none;
       }
-      .status {
-        border-color: ${result.ok ? "color-mix(in oklch, var(--good) 42%, var(--line))" : "color-mix(in oklch, var(--bad) 44%, var(--line))"};
-        color: ${result.ok ? "var(--good)" : "var(--bad)"};
+      .viewer-link {
+        color: var(--focus);
         font-weight: 700;
       }
-      .panel {
+      .viewer-stage {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr);
+        grid-template-rows: minmax(0, 1fr);
+        min-width: 0;
+        min-height: 0;
+        justify-items: center;
+        align-content: start;
+        overflow: hidden;
+        background:
+          radial-gradient(circle at top left, rgba(121, 192, 255, 0.1), transparent 32%),
+          #060a13;
+        padding: 14px;
+      }
+      .viewer-viewport {
+        width: min(var(--config-viewport-width), 100%);
+        height: min(var(--config-viewport-height), 100%);
+        max-width: 100%;
+        max-height: 100%;
+        overflow: auto;
+        overscroll-behavior: contain;
+        border: 0;
+        border-radius: 8px;
+        background: #0c111d;
+        outline: 1px solid var(--line);
+        box-shadow: 0 18px 52px rgba(0, 0, 0, 0.34);
+      }
+      .viewer-viewport[data-mobile="true"] {
+        width: min(var(--config-viewport-width), 100%);
+      }
+      .dom-viewport {
+        overflow: hidden;
+      }
+      .dom-viewer-frame {
+        display: block;
+        width: 100%;
+        height: 100%;
+        border: 0;
+        background: #0c111d;
+      }
+      .viewer-page[data-theme="light"] {
+        --bg: #f8fafc;
+        --panel: #ffffff;
+        --line: rgba(15, 23, 42, 0.14);
+        --ink: #0f172a;
+        --muted: #64748b;
+        --focus: #1e66f5;
+      }
+      .viewer-page[data-theme="light"] .viewer-stage {
+        background: #f8fafc;
+      }
+      .viewer-page[data-theme="light"] .viewer-viewport,
+      .viewer-page[data-theme="light"] .dom-viewer-frame {
+        background: #ffffff;
+      }
+      @media (max-width: 720px) {
+        .viewer-toolbar {
+          padding: 8px;
+        }
+        .viewer-title {
+          flex-basis: 100%;
+          order: -1;
+        }
+        .viewer-stage {
+          padding: 0;
+        }
+        .viewer-viewport {
+          width: min(var(--config-viewport-width), 100%);
+          height: min(var(--config-viewport-height), 100%);
+          border-radius: 0;
+        }
+      }`;
+}
+//#endregion
+//#region src/agent/report_artifact_viewer_shell.ts
+function renderArtifactViewerShellHtml(args) {
+	const { artifact, artifactsDir, contentFragment, mobile, reportPath, viewOptions, viewerPath } = args;
+	const title = `${artifact.viewport} ${artifact.name} ${artifact.kind}`;
+	const viewportStyle = renderConfiguredViewportStyle(args.viewport);
+	const viewportLabel = args.viewport ? `${args.viewport.name} ${args.viewport.width}x${args.viewport.height}` : `${artifact.viewport} viewport`;
+	const backHref = relativeHref(viewerPath, reportPath, artifactsDir);
+	const rawHref = relativeHref(viewerPath, artifact.path, artifactsDir);
+	const baselineHref = artifact.baselinePath ? relativeHref(viewerPath, artifact.baselinePath, artifactsDir) : "";
+	const diffHref = artifact.diffPath ? relativeHref(viewerPath, artifact.diffPath, artifactsDir) : "";
+	const scriptTag = contentFragment.script ? `    <script>
+${contentFragment.script}
+    <\/script>
+` : "";
+	return `<!doctype html>
+<html lang="en" data-theme="${escapeAttribute(viewOptions.theme)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>
+    <style>
+${renderArtifactViewerShellCss()}
+${contentFragment.css}
+    </style>
+  </head>
+  <body>
+    <main class="viewer-page" data-report-screen-mode="${escapeAttribute(viewOptions.screenMode)}" data-theme="${escapeAttribute(viewOptions.theme)}" style="${escapeAttribute(viewportStyle)}">
+      <header class="viewer-toolbar">
+        <a class="viewer-link" href="${escapeAttribute(backHref)}">Report</a>
+        <span class="viewer-title">${escapeHtml(title)}</span>
+        <span class="viewer-pill">${escapeHtml(viewportLabel)}</span>
+        <span class="viewer-pill">${escapeHtml(viewOptions.screenMode)}</span>
+        <a class="viewer-link" href="${escapeAttribute(rawHref)}">Raw</a>
+        ${baselineHref ? `<a class="viewer-link" href="${escapeAttribute(baselineHref)}">Baseline</a>` : ""}
+        ${diffHref ? `<a class="viewer-link" href="${escapeAttribute(diffHref)}">Diff</a>` : ""}
+      </header>
+      <section class="viewer-stage" data-mobile="${mobile ? "true" : "false"}">
+        ${contentFragment.html}
+      </section>
+    </main>
+${scriptTag}
+  </body>
+</html>`;
+}
+function renderConfiguredViewportStyle(viewport) {
+	if (!viewport) return "--config-viewport-width: 1280px; --config-viewport-height: 760px;";
+	return `--config-viewport-width: ${viewport.width}px; --config-viewport-height: ${viewport.height}px;`;
+}
+//#endregion
+//#region src/agent/report_launch_args.ts
+function readReportLaunchArgSets(result) {
+	return [readFlowLaunchArgs(result.flowPath), readCassetteLaunchArgs(result.replaySourceCassettePath ?? result.cassettePath)];
+}
+function readFlagValueFromArgSets(argSets, flag) {
+	for (const args of argSets) {
+		const value = readFlagValue(args, flag);
+		if (value !== void 0) return value;
+	}
+}
+function readFlagValue(args, flag) {
+	const index = args.indexOf(flag);
+	return index >= 0 ? args[index + 1] : void 0;
+}
+function readCassetteLaunchArgs(cassettePath) {
+	try {
+		return normalizeStringArray(JSON.parse(readFileSync(cassettePath, "utf8")).spec?.launch?.args);
+	} catch {
+		return [];
+	}
+}
+function readFlowLaunchArgs(flowPath) {
+	try {
+		return normalizeStringArray(JSON.parse(readFileSync(flowPath, "utf8")).launch?.args);
+	} catch {
+		return [];
+	}
+}
+function normalizeStringArray(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+//#endregion
+//#region src/agent/report_view_options.ts
+function isMobileViewport(viewport) {
+	return Boolean(viewport?.isMobile || viewport?.hasTouch || (viewport?.width ?? 9999) <= 720);
+}
+function resolveReportViewOptions(result, config) {
+	const launchArgSets = readReportLaunchArgSets(result);
+	const ptyReplayArg = readFlagValueFromArgSets(launchArgSets, "--pty-replay");
+	const screenModeArg = readFlagValueFromArgSets(launchArgSets, "--experimental-screen-mode");
+	const themeArg = readFlagValueFromArgSets(launchArgSets, "--theme");
+	const fontSizeArg = readFlagValueFromArgSets(launchArgSets, "--font-size");
+	const lineHeightArg = readFlagValueFromArgSets(launchArgSets, "--line-height");
+	const stableFrameConfig = resolveStableFrameConfig$1(config, result.name);
+	const themeOverride = ptyReplayArg && stableFrameConfig.enabled !== false && !stableFrameConfig.skip ? stableFrameConfig.theme : void 0;
+	return {
+		fontSize: parsePositiveNumber(fontSizeArg) ?? 15,
+		lineHeight: parsePositiveNumber(lineHeightArg) ?? 1.6,
+		screenMode: screenModeArg && screenModeArg !== "termvision" ? "plain" : "termvision",
+		theme: themeOverride ?? (themeArg === "light" ? "light" : "dark")
+	};
+}
+function parsePositiveNumber(value) {
+	if (value === void 0) return void 0;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+function resolveStableFrameConfig$1(config, flowName) {
+	const stableFrames = config?.agent?.report?.stableFrames;
+	const flowConfig = stableFrames?.flows?.[flowName];
+	return {
+		enabled: flowConfig?.enabled ?? stableFrames?.enabled,
+		skip: flowConfig?.skip ?? stableFrames?.skip,
+		theme: flowConfig?.theme ?? stableFrames?.theme ?? "dark"
+	};
+}
+//#endregion
+//#region src/agent/report_artifact_viewer.ts
+function renderArtifactViewerHtml(args) {
+	const { artifact, artifactsDir, content, domPreview, reportPath, terminalDomPreview, viewOptions, viewerPath, viewport } = args;
+	const mobile = isMobileViewport(viewport);
+	return renderArtifactViewerShellHtml({
+		artifact,
+		artifactsDir,
+		contentFragment: renderArtifactViewerFragment({
+			artifactsDir,
+			content,
+			domViewerPreview: artifact.kind === "dom" ? domPreview : artifact.kind === "terminal" ? terminalDomPreview : null,
+			mobile,
+			viewerPath,
+			viewOptions
+		}),
+		mobile,
+		reportPath,
+		viewOptions,
+		viewerPath,
+		viewport
+	});
+}
+//#endregion
+//#region src/agent/report_pty_stable_frame.ts
+async function extractPtyReplayStableFrameForReport(args) {
+	const replayPathArg = readFlagValueFromArgSets(readReportLaunchArgSets(args.result), "--pty-replay");
+	if (!replayPathArg) return null;
+	const config = resolveStableFrameConfig(args.config, args.result.name);
+	if (config.enabled === false || config.skip) return null;
+	const replayPath = resolvePtyReplayPath(replayPathArg, args.config);
+	if (!existsSync(replayPath)) return null;
+	const recording = JSON.parse(readFileSync(replayPath, "utf8"));
+	const events = Array.isArray(recording.events) ? recording.events : [];
+	const firstResize = events.find((event) => event.type === "resize");
+	const terminal = new Terminal({
+		allowProposedApi: true,
+		cols: config.cols ?? recording.terminal?.cols ?? recording.command?.cols ?? recording.cols ?? firstResize?.cols ?? 80,
+		convertEol: true,
+		rows: config.rows ?? recording.terminal?.rows ?? recording.command?.rows ?? recording.rows ?? firstResize?.rows ?? 24,
+		scrollback: 2e4
+	});
+	try {
+		return await extractStableFrame({
+			config,
+			events,
+			terminal
+		});
+	} finally {
+		terminal.dispose();
+	}
+}
+function renderPtyReplayStableFramePreviewDocument(args) {
+	const targetCols = resolveTargetCols({
+		config: resolveStableFrameConfig(args.config, args.flowName),
+		fontSize: args.viewOptions.fontSize,
+		frameCols: args.frame.cols,
+		viewport: args.viewport
+	});
+	const body = renderAittyPreviewBody({
+		snapshot: renderStableFrameDom(args.frame, targetCols),
+		snapshotLayout: {
+			cols: targetCols,
+			fontSize: args.viewOptions.fontSize,
+			lineHeight: args.viewOptions.lineHeight,
+			paddingInline: isMobileViewport(args.viewport) ? 16 : 32,
+			rows: args.frame.rows
+		},
+		viewOptions: args.viewOptions
+	});
+	const style = renderAittyPreviewCss(args.viewOptions);
+	const assetTags = renderAittyPreviewAssetTags(args.aittyAssets);
+	return `<!doctype html>
+<html lang="en" data-theme="${escapeAttribute(args.viewOptions.theme)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>stable-frame preview (atMs=${args.frame.atMs})</title>
+${assetTags}    <style>
+${style}
+    </style>
+  </head>
+  <body>
+${body}
+  </body>
+</html>`;
+}
+function resolveStableFrameConfig(config, flowName) {
+	const stableFrames = config?.agent?.report?.stableFrames;
+	const flowConfig = stableFrames?.flows?.[flowName];
+	return {
+		...stableFrames,
+		...flowConfig,
+		stableMs: flowConfig?.stableMs ?? stableFrames?.stableMs ?? 200,
+		theme: flowConfig?.theme ?? stableFrames?.theme ?? "dark",
+		viewportOnly: flowConfig?.viewportOnly ?? stableFrames?.viewportOnly ?? false,
+		viewportTargets: {
+			...stableFrames?.viewportTargets,
+			...flowConfig?.viewportTargets
+		}
+	};
+}
+function resolvePtyReplayPath(replayPathArg, config) {
+	if (isAbsolute(replayPathArg)) return replayPathArg;
+	return resolve(config?.rootDir ?? process.cwd(), replayPathArg);
+}
+async function extractStableFrame(args) {
+	const { config, events, terminal } = args;
+	const targetFrameIndex = config.frameIndex;
+	const matcher = createStableFrameMatcher(config);
+	let matchedFrame = null;
+	const retainedFrames = [];
+	const retainCount = targetFrameIndex === void 0 ? 24 : targetFrameIndex < 0 ? -targetFrameIndex : 1;
+	let totalFrames = 0;
+	let pendingDirtySinceMs = null;
+	let lastEventAtMs = 0;
+	const captureFrame = (atMs, reason) => {
+		const shouldRetain = targetFrameIndex === void 0 || targetFrameIndex >= 0 && totalFrames === targetFrameIndex || targetFrameIndex < 0;
+		if (shouldRetain || matcher) {
+			const frame = {
+				...snapshotTerminalFrame(terminal, {
+					atMs,
+					index: totalFrames,
+					reason,
+					viewportOnly: config.viewportOnly
+				}),
+				score: scoreTerminalFrame(terminal)
+			};
+			if (matcher?.matches(stableFrameText(frame))) {
+				if (matcher.mode === "last" || !matchedFrame) matchedFrame = frame;
+			}
+			if (shouldRetain) retainedFrames.push(frame);
+			if (retainedFrames.length > retainCount) retainedFrames.splice(0, retainedFrames.length - retainCount);
+		}
+		totalFrames += 1;
+		pendingDirtySinceMs = null;
+	};
+	const flushIfStable = (nowMs) => {
+		if (pendingDirtySinceMs === null) return;
+		if (nowMs - pendingDirtySinceMs >= config.stableMs) captureFrame(pendingDirtySinceMs, "stable");
+	};
+	for (const event of events) {
+		const atMs = event.atMs ?? lastEventAtMs;
+		flushIfStable(atMs);
+		lastEventAtMs = atMs;
+		if (event.type === "output" && event.dataBase64) {
+			await writeTerminal(terminal, base64ToBytes(event.dataBase64));
+			pendingDirtySinceMs = pendingDirtySinceMs ?? atMs;
+			continue;
+		}
+		if (event.type === "resize" && event.cols && event.rows) {
+			terminal.resize(event.cols, event.rows);
+			pendingDirtySinceMs = pendingDirtySinceMs ?? atMs;
+			continue;
+		}
+		if (event.type === "exit") flushIfStable(atMs);
+	}
+	flushIfStable(lastEventAtMs + config.stableMs);
+	if (totalFrames === 0) captureFrame(lastEventAtMs, "final");
+	if (targetFrameIndex !== void 0 && targetFrameIndex >= 0) {
+		const exact = retainedFrames.find((frame) => frame.index === targetFrameIndex);
+		if (exact) return exact;
+		return null;
+	}
+	if (targetFrameIndex !== void 0 && targetFrameIndex < 0) {
+		const resolved = totalFrames + targetFrameIndex;
+		const exact = retainedFrames.find((frame) => frame.index === resolved);
+		if (exact) return exact;
+	}
+	if (matchedFrame) return matchedFrame;
+	return chooseBestStableFrame(retainedFrames);
+}
+function writeTerminal(terminal, data) {
+	return new Promise((resolveWrite) => {
+		terminal.write(data, resolveWrite);
+	});
+}
+function snapshotTerminalFrame(terminal, options) {
+	const buffer = terminal.buffer.active;
+	const startY = options.viewportOnly ? buffer.viewportY : 0;
+	const count = options.viewportOnly ? terminal.rows : buffer.length;
+	const logicalLines = [];
+	for (let offset = 0; offset < count; offset += 1) {
+		const y = startY + offset;
+		const line = buffer.getLine(y);
+		const cells = readStableLineCells(terminal, y);
+		const live = options.viewportOnly || y >= buffer.viewportY;
+		const previous = logicalLines.at(-1);
+		if (line?.isWrapped && previous) {
+			previous.cells.push(...cells);
+			previous.live = previous.live || live;
+			previous.physicalRows += 1;
+			continue;
+		}
+		logicalLines.push({
+			cells,
+			live,
+			physicalRows: 1
+		});
+	}
+	return {
+		atMs: options.atMs,
+		cols: terminal.cols,
+		index: options.index,
+		lines: logicalLines,
+		reason: options.reason,
+		rows: terminal.rows
+	};
+}
+function readStableLineCells(terminal, y) {
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	const line = buffer.getLine(y);
+	const endCol = findMeaningfulEndCol(line, terminal.cols, nullCell);
+	const cells = [];
+	for (let x = 0; x < endCol; x += 1) {
+		const cell = line?.getCell(x, nullCell);
+		if (!cell) {
+			cells.push({
+				style: DEFAULT_STYLE,
+				text: " ",
+				width: 1
+			});
+			continue;
+		}
+		const width = cell.getWidth();
+		if (width === 0) continue;
+		cells.push({
+			style: extractStyle(cell),
+			text: cell.getChars() || " ",
+			width
+		});
+	}
+	return cells;
+}
+function scoreTerminalFrame(terminal) {
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	let score = 0;
+	for (let y = 0; y < buffer.length; y += 1) {
+		const endCol = findMeaningfulEndCol(buffer.getLine(y), terminal.cols, nullCell);
+		score += endCol;
+	}
+	return score;
+}
+function chooseBestStableFrame(frames) {
+	return frames.filter((frame) => frame.score > 0).at(-1) ?? frames.at(-1) ?? null;
+}
+function createStableFrameMatcher(config) {
+	const matchText = toStringArray(config.matchText);
+	const matchRegex = toStringArray(config.matchRegex).map((pattern) => {
+		try {
+			return new RegExp(pattern);
+		} catch (error) {
+			throw new Error(`invalid agent.report.stableFrames.matchRegex pattern ${JSON.stringify(pattern)}: ${String(error)}`);
+		}
+	});
+	if (matchText.length === 0 && matchRegex.length === 0) return null;
+	return {
+		mode: config.matchMode ?? "last",
+		matches: (text) => matchText.some((needle) => text.includes(needle)) || matchRegex.some((regex) => regex.test(text))
+	};
+}
+function stableFrameText(frame) {
+	return frame.lines.map((line) => line.cells.map((cell) => cell.text).join("").trimEnd()).join("\n");
+}
+function toStringArray(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+function resolveTargetCols(args) {
+	const explicit = args.viewport ? args.config.viewportTargets?.[args.viewport.name] : void 0;
+	if (typeof explicit === "number" && Number.isFinite(explicit) && explicit > 0) return Math.trunc(explicit);
+	if (explicit === null) return args.frameCols;
+	if (isMobileViewport(args.viewport)) {
+		const width = args.viewport?.width ?? 390;
+		const cellWidth = Math.max(1, args.fontSize * .6);
+		return Math.max(20, Math.floor(width / cellWidth));
+	}
+	return args.frameCols;
+}
+function renderStableFrameDom(frame, targetCols) {
+	let html = "";
+	let totalRows = 0;
+	let wideBlockId = 0;
+	for (const line of frame.lines) {
+		const lineCols = Math.max(targetCols, cellsDisplayWidth(line.cells));
+		if (lineCols > targetCols || line.physicalRows > 1) {
+			wideBlockId += 1;
+			html += `<div class="term-wide-row-block" data-aitty-wide-block="true" data-aitty-wide-block-id="${wideBlockId}" data-aitty-wide-block-kind="viewport-pan" style="--aitty-wide-block-cols: ${lineCols}">`;
+			html += renderStableFrameRow(line, lineCols, totalRows);
+			html += "</div>";
+		} else html += renderStableFrameRow(line, targetCols, totalRows);
+		totalRows += 1;
+	}
+	return `<div class="term-grid" data-cols="${targetCols}" data-rows="${totalRows}" style="--term-cols: ${targetCols}; --term-rows: ${totalRows};">${html}</div>`;
+}
+function renderStableFrameRow(line, lineCols, lineIndex) {
+	return `<div class="${line.live ? "term-row" : "term-row term-scrollback-row"}"${line.live ? ` data-aitty-live-grid-row="${lineIndex + 1}"` : ""} data-aitty-line-cols="${lineCols}">${renderStableFrameCells(line.cells, lineCols)}</div>`;
+}
+function renderStableFrameCells(cells, lineCols) {
+	const out = [];
+	let usedCols = 0;
+	let runText = "";
+	let runWidth = 0;
+	let runStyle = null;
+	let runKey = null;
+	const flush = () => {
+		if (runText === "" && runWidth === 0) return;
+		out.push(renderSpan(runText, runWidth, runStyle ?? DEFAULT_STYLE));
+		runText = "";
+		runWidth = 0;
+		runStyle = null;
+		runKey = null;
+	};
+	for (const cell of cells) {
+		const key = styleKey(cell.style);
+		const wide = cell.width !== 1;
+		if (!wide && runKey === key) {
+			runText += cell.text;
+			runWidth += cell.width;
+			usedCols += cell.width;
+			continue;
+		}
+		flush();
+		if (wide) {
+			out.push(renderSpan(cell.text, cell.width, cell.style, "term-wide"));
+			usedCols += cell.width;
+			continue;
+		}
+		runText = cell.text;
+		runWidth = cell.width;
+		runStyle = cell.style;
+		runKey = key;
+		usedCols += cell.width;
+	}
+	flush();
+	const remaining = lineCols - usedCols;
+	if (remaining > 0) out.push(renderSpan("", remaining, DEFAULT_STYLE));
+	return out.join("");
+}
+function renderSpan(text, width, style, className) {
+	const declarations = styleDeclarations(style);
+	declarations.push(widthDeclaration(width));
+	if (className === "term-wide") declarations.push("overflow: hidden");
+	return `<span${className ? ` class="${escapeAttribute(className)}"` : ""} style="${escapeAttribute(declarations.join("; "))}">${escapeHtml(text)}</span>`;
+}
+function styleDeclarations(style) {
+	if (isDefaultStyle(style)) return [];
+	const declarations = [];
+	const fg = colorToCss(style.fg);
+	const bg = colorToCss(style.bg);
+	if (fg) declarations.push(`color: ${fg}`);
+	if (bg) declarations.push(`background-color: ${bg}`);
+	if (style.bold) declarations.push("font-weight: 700");
+	if (style.dim) declarations.push("opacity: 0.72");
+	if (style.italic) declarations.push("font-style: italic");
+	const decorations = [style.underline ? "underline" : "", style.strikethrough ? "line-through" : ""].filter(Boolean);
+	if (decorations.length > 0) declarations.push(`text-decoration: ${decorations.join(" ")}`);
+	if (style.inverse) declarations.push("filter: invert(1)");
+	return declarations;
+}
+function colorToCss(color) {
+	if (color.mode === "default") return null;
+	if (color.mode === "palette") return `var(--term-color-${color.value})`;
+	const value = color.value;
+	return `rgb(${value >> 16 & 255},${value >> 8 & 255},${value & 255})`;
+}
+function widthDeclaration(width) {
+	if (width <= 1) return "width: var(--term-cell-width, 1ch)";
+	return `width: calc(var(--term-cell-width, 1ch) * ${width})`;
+}
+function cellsDisplayWidth(cells) {
+	return cells.reduce((sum, cell) => sum + cell.width, 0);
+}
+//#endregion
+//#region src/agent/report_terminal_layout.ts
+function resolveTerminalSnapshotLayout(snapshot, viewport, viewOptions) {
+	const cols = inferTerminalCols(snapshot);
+	const rows = inferTerminalRows(snapshot);
+	const mobile = isMobileViewport(viewport);
+	return {
+		cols,
+		fontSize: viewOptions.fontSize,
+		lineHeight: viewOptions.lineHeight,
+		paddingInline: mobile ? 16 : 32,
+		rows
+	};
+}
+function inferTerminalCols(snapshot) {
+	const dataCols = /data-cols="(\d+)"/.exec(snapshot)?.[1];
+	const styleCols = /--term-cols:\s*(\d+)/.exec(snapshot)?.[1];
+	const parsed = Number.parseInt(dataCols ?? styleCols ?? "", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 80;
+}
+function inferTerminalRows(snapshot) {
+	const dataRows = /data-rows="(\d+)"/.exec(snapshot)?.[1];
+	const styleRows = /--term-rows:\s*(\d+)/.exec(snapshot)?.[1];
+	const parsed = Number.parseInt(dataRows ?? styleRows ?? "", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 24;
+}
+//#endregion
+//#region src/agent/report_terminal_preview.ts
+function renderDomPreviewDocument(snapshot, viewport, viewOptions, aittyAssets) {
+	const body = renderAittyPreviewBody({
+		snapshot,
+		snapshotLayout: resolveTerminalSnapshotLayout(snapshot, viewport, viewOptions),
+		viewOptions
+	});
+	const style = renderAittyPreviewCss(viewOptions);
+	const assetTags = renderAittyPreviewAssetTags(aittyAssets);
+	return `<!doctype html>
+<html lang="en" data-theme="${escapeAttribute(viewOptions.theme)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+${assetTags}    <style>
+${style}
+    </style>
+  </head>
+  <body>
+${body}
+  </body>
+</html>`;
+}
+//#endregion
+//#region src/agent/report_artifact_writer.ts
+async function writeArtifactViewerPages(result, options = {}) {
+	const viewportsByName = new Map(result.viewports.map((viewport) => [viewport.name, viewport]));
+	const viewOptions = resolveReportViewOptions(result, options.config);
+	const readableArtifacts = [];
+	for (const artifact of result.artifacts) {
+		const viewerPath = artifactViewerPath(artifact);
+		if (!viewerPath) continue;
+		const content = readArtifactText(artifact.path);
+		if (content === null) continue;
+		readableArtifacts.push({
+			artifact,
+			content,
+			viewerPath
+		});
+	}
+	const domPreviewPathsBySnapshot = new Map(readableArtifacts.filter(({ artifact }) => artifact.kind === "dom").map(({ artifact }) => [artifactSnapshotKey(artifact), artifactDomPreviewPath(artifact)]));
+	const aittyAssets = domPreviewPathsBySnapshot.size > 0 ? prepareAittyReportAssets({
+		artifactsDir: result.artifactsDir,
+		flowPath: result.flowPath,
+		reportPath: result.reportPath
+	}) : null;
+	const writtenDomPreviewPaths = /* @__PURE__ */ new Set();
+	const ptyReplayStableFrame = aittyAssets ? await extractPtyReplayStableFrameForReport({
+		config: options.config,
+		result
+	}) : null;
+	if (aittyAssets) for (const { artifact, content } of readableArtifacts) {
+		if (artifact.kind !== "dom") continue;
+		const viewport = viewportsByName.get(artifact.viewport);
+		const domPreviewPath = artifactDomPreviewPath(artifact);
+		const aittyPreviewAssets = resolveAittyPreviewAssets(domPreviewPath, aittyAssets, result.artifactsDir);
+		const previewDocument = ptyReplayStableFrame ? renderPtyReplayStableFramePreviewDocument({
+			aittyAssets: aittyPreviewAssets,
+			config: options.config,
+			flowName: result.name,
+			frame: ptyReplayStableFrame,
+			viewOptions,
+			viewport
+		}) : renderDomPreviewDocument(content, viewport, viewOptions, aittyPreviewAssets);
+		mkdirSync(dirname(domPreviewPath), { recursive: true });
+		writeFileSync(domPreviewPath, previewDocument, "utf8");
+		writtenDomPreviewPaths.add(domPreviewPath);
+	}
+	for (const { artifact, content, viewerPath } of readableArtifacts) {
+		const viewport = viewportsByName.get(artifact.viewport);
+		const domPreviewPath = artifact.kind === "dom" ? artifactDomPreviewPath(artifact) : null;
+		mkdirSync(dirname(viewerPath), { recursive: true });
+		writeFileSync(viewerPath, renderArtifactViewerHtml({
+			artifact,
+			artifactsDir: result.artifactsDir,
+			content,
+			reportPath: result.reportPath,
+			viewerPath,
+			domPreview: resolveReportDomPreview(domPreviewPath && writtenDomPreviewPaths.has(domPreviewPath) ? domPreviewPath : null),
+			viewOptions,
+			viewport,
+			terminalDomPreview: artifact.kind === "terminal" ? resolveReportDomPreview(resolveWrittenDomPreviewPath(domPreviewPathsBySnapshot, writtenDomPreviewPaths, artifact)) : null
+		}), "utf8");
+	}
+}
+function resolveWrittenDomPreviewPath(domPreviewPathsBySnapshot, writtenDomPreviewPaths, artifact) {
+	const path = domPreviewPathsBySnapshot.get(artifactSnapshotKey(artifact));
+	return path && writtenDomPreviewPaths.has(path) ? path : null;
+}
+function readArtifactText(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/agent/report_index_artifacts.ts
+function renderAgentReportArtifacts(args) {
+	return args.artifacts.map((artifact) => renderArtifactRow({
+		artifact,
+		artifactsDir: args.artifactsDir,
+		reportPath: args.reportPath
+	})).join("\n") || "<p>No artifacts were captured.</p>";
+}
+function renderArtifactRow(args) {
+	const { artifact, artifactsDir, reportPath } = args;
+	const state = artifact.ok ? "pass" : "fail";
+	const href = relativeHref(reportPath, artifact.path, artifactsDir);
+	const baselineHref = artifact.baselinePath ? relativeHref(reportPath, artifact.baselinePath, artifactsDir) : "";
+	const diffHref = artifact.diffPath ? relativeHref(reportPath, artifact.diffPath, artifactsDir) : "";
+	const viewerPath = artifactViewerPath(artifact);
+	const viewerHref = viewerPath ? relativeHref(reportPath, viewerPath, artifactsDir) : "";
+	return `<article class="artifact">
+    <div class="artifact-summary">
+      <span class="badge ${state}">${state}</span>
+      <div class="artifact-meta">
+        <div class="artifact-links">
+          <a href="${escapeAttribute(viewerHref || href)}">${escapeHtml(artifact.kind)}</a>
+          ${viewerHref ? `<a href="${escapeAttribute(href)}">raw</a>` : ""}
+          ${baselineHref ? `<a href="${escapeAttribute(baselineHref)}">baseline</a>` : ""}
+          ${diffHref ? `<a href="${escapeAttribute(diffHref)}">diff</a>` : ""}
+        </div>
+      <div><code>${escapeHtml(artifact.viewport)} / ${escapeHtml(artifact.name)}</code></div>
+      ${artifact.error ? `<div><code>${escapeHtml(artifact.error)}</code></div>` : ""}
+      </div>
+      <code class="artifact-hash">${escapeHtml(artifact.hash ?? "")}</code>
+    </div>
+  </article>`;
+}
+//#endregion
+//#region src/agent/report_index_commands.ts
+function renderAgentReportCommandBlock(label, argv) {
+	return `<div class="command">
+    <span>${escapeHtml(label)}</span>
+    <pre>${escapeHtml(formatAgentArgv(argv))}</pre>
+  </div>`;
+}
+//#endregion
+//#region src/agent/report_index_artifacts_css.ts
+function renderAgentReportArtifactsCss() {
+	return `      .artifacts {
         display: grid;
-        gap: 16px;
-        border: 1px solid var(--line);
-        border-radius: 8px;
-        background: var(--panel);
-        padding: 18px;
+        gap: 14px;
       }
-      .summary {
+      .artifact {
         display: grid;
-        grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
         gap: 12px;
-      }
-      .metric {
         border: 1px solid var(--line);
         border-radius: 8px;
-        padding: 14px;
-        background: color-mix(in oklch, var(--panel) 82%, var(--bg));
-      }
-      .metric strong {
-        display: block;
-        font-size: 24px;
-        line-height: 1.1;
-      }
-      .metric span {
-        display: block;
-        margin-top: 4px;
-        color: var(--muted);
-        font-size: 13px;
+        padding: 12px;
+        background: var(--panel);
       }
-      .artifacts {
+      .artifact-summary {
         display: grid;
-        gap: 10px;
+        grid-template-columns: auto minmax(0, 1fr) minmax(96px, auto);
+        gap: 14px;
+        align-items: start;
       }
-      .artifact {
+      .artifact-meta {
         display: grid;
-        grid-template-columns: 120px minmax(0, 1fr) auto;
-        gap: 14px;
-        align-items: center;
-        border: 1px solid var(--line);
-        border-radius: 8px;
-        padding: 12px;
-        background: var(--panel);
+        gap: 4px;
+        min-width: 0;
+      }
+      .artifact-links {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px 12px;
       }
       .artifact a {
         color: var(--focus);
         font-weight: 700;
         text-decoration: none;
       }
-      .artifact code,
-      pre {
-        font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
-      }
       .artifact code {
         color: var(--muted);
         overflow-wrap: anywhere;
       }
-      .badge {
-        justify-self: start;
+      .artifact-hash {
+        justify-self: end;
+        text-align: right;
+      }
+      .badge {
+        justify-self: start;
+        border-radius: 999px;
+        padding: 5px 9px;
+        background: color-mix(in oklch, var(--line) 52%, transparent);
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+      }
+      .badge.fail {
+        background: color-mix(in oklch, var(--bad) 12%, var(--panel));
+        color: var(--bad);
+      }
+      .badge.pass {
+        background: color-mix(in oklch, var(--good) 12%, var(--panel));
+        color: var(--good);
+      }
+      @media (max-width: 720px) {
+        .artifact-summary {
+          grid-template-columns: 1fr;
+        }
+        .artifact-hash {
+          justify-self: start;
+          text-align: left;
+        }
+      }`;
+}
+//#endregion
+//#region src/agent/report_index_base_css.ts
+function renderAgentReportBaseCss() {
+	return `      :root {
+        color-scheme: light;
+        --bg: oklch(97.5% 0.008 210);
+        --ink: oklch(19% 0.018 230);
+        --muted: oklch(48% 0.02 230);
+        --line: oklch(86% 0.018 230);
+        --panel: oklch(99% 0.006 210);
+        --good: oklch(55% 0.15 155);
+        --bad: oklch(58% 0.19 25);
+        --focus: oklch(55% 0.14 235);
+        font-family:
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Segoe UI",
+          sans-serif;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        background: var(--bg);
+        color: var(--ink);
+      }
+      main {
+        display: grid;
+        gap: 24px;
+        width: min(1180px, calc(100vw - 32px));
+        margin: 0 auto;
+        padding: 32px 0 48px;
+      }
+      header {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        gap: 20px;
+        align-items: start;
+        border-bottom: 1px solid var(--line);
+        padding-bottom: 24px;
+      }
+      h1 {
+        margin: 0;
+        font-size: 28px;
+        line-height: 1.15;
+        letter-spacing: 0;
+      }
+      h2 {
+        margin: 0;
+        font-size: 18px;
+        line-height: 1.25;
+      }
+      .meta {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-top: 12px;
+      }
+      .pill,
+      .status {
+        display: inline-flex;
+        min-height: 32px;
+        align-items: center;
+        border: 1px solid var(--line);
         border-radius: 999px;
-        padding: 5px 9px;
-        background: color-mix(in oklch, var(--line) 52%, transparent);
+        padding: 0 12px;
         color: var(--muted);
-        font-size: 12px;
+        font-size: 13px;
+      }
+      .status {
         font-weight: 700;
       }
-      .badge.fail {
-        background: color-mix(in oklch, var(--bad) 12%, var(--panel));
+      .status.pass {
+        border-color: color-mix(in oklch, var(--good) 42%, var(--line));
+        color: var(--good);
+      }
+      .status.fail {
+        border-color: color-mix(in oklch, var(--bad) 44%, var(--line));
         color: var(--bad);
       }
-      .badge.pass {
-        background: color-mix(in oklch, var(--good) 12%, var(--panel));
-        color: var(--good);
+      .panel {
+        display: grid;
+        gap: 16px;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: var(--panel);
+        padding: 18px;
       }
-      .commands {
+      @media (max-width: 720px) {
+        main {
+          width: min(100vw - 20px, 1180px);
+          padding-top: 18px;
+        }
+        header {
+          grid-template-columns: 1fr;
+        }
+        .status {
+          justify-self: start;
+        }
+      }`;
+}
+//#endregion
+//#region src/agent/report_index_commands_css.ts
+function renderAgentReportCommandsCss() {
+	return `      .commands {
         display: grid;
         gap: 10px;
       }
@@ -1213,6 +2309,10 @@ function renderAgentReportHtml(result) {
         font-size: 13px;
         font-weight: 700;
       }
+      .artifact code,
+      pre {
+        font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      }
       pre {
         overflow: auto;
         margin: 0;
@@ -1221,20 +2321,63 @@ function renderAgentReportHtml(result) {
         color: oklch(92% 0.012 230);
         padding: 14px;
         line-height: 1.5;
+      }`;
+}
+//#endregion
+//#region src/agent/report_index_summary_css.ts
+function renderAgentReportSummaryCss() {
+	return `      .summary {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+        gap: 12px;
       }
-      @media (max-width: 720px) {
-        main {
-          width: min(100vw - 20px, 1180px);
-          padding-top: 18px;
-        }
-        header,
-        .artifact {
-          grid-template-columns: 1fr;
-        }
-        .status {
-          justify-self: start;
-        }
+      .metric {
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 14px;
+        background: color-mix(in oklch, var(--panel) 82%, var(--bg));
+      }
+      .metric strong {
+        display: block;
+        font-size: 24px;
+        line-height: 1.1;
       }
+      .metric span {
+        display: block;
+        margin-top: 4px;
+        color: var(--muted);
+        font-size: 13px;
+      }`;
+}
+//#endregion
+//#region src/agent/report_index_css.ts
+function renderAgentReportCss() {
+	return [
+		renderAgentReportBaseCss(),
+		renderAgentReportSummaryCss(),
+		renderAgentReportArtifactsCss(),
+		renderAgentReportCommandsCss()
+	].join("\n");
+}
+//#endregion
+//#region src/agent/report_index.ts
+function renderAgentReportHtml(result) {
+	const artifacts = renderAgentReportArtifacts({
+		artifacts: result.artifacts,
+		artifactsDir: result.artifactsDir,
+		reportPath: result.reportPath
+	});
+	const viewportTabs = result.viewports.map((viewport) => `<span class="pill">${escapeHtml(viewport.name)} ${viewport.width}x${viewport.height}</span>`).join("");
+	const status = result.ok ? "passed" : "failed";
+	const statusClass = result.ok ? "pass" : "fail";
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(`${result.name} terminal-agent report`)}</title>
+    <style>
+${renderAgentReportCss()}
     </style>
   </head>
   <body>
@@ -1243,7 +2386,7 @@ function renderAgentReportHtml(result) {
         <div>
           <h1>${escapeHtml(result.name)}</h1>
           <div class="meta">
-            <span class="status">${status}</span>
+            <span class="status ${statusClass}">${status}</span>
             <span class="pill">${escapeHtml(result.mode)}</span>
             <span class="pill">${escapeHtml(result.agentFlavor)}</span>
             ${viewportTabs}
@@ -1262,9 +2405,9 @@ function renderAgentReportHtml(result) {
       <section class="panel">
         <h2>Commands</h2>
         <div class="commands">
-          ${renderCommandBlock("replay", result.commands.replay.argv)}
-          ${renderCommandBlock("update snapshots", result.commands.updateSnapshots.argv)}
-          ${renderCommandBlock("inspect commands", [
+          ${renderAgentReportCommandBlock("replay", result.commands.replay.argv)}
+          ${renderAgentReportCommandBlock("update snapshots", result.commands.updateSnapshots.argv)}
+          ${renderAgentReportCommandBlock("inspect commands", [
 		"ptywright",
 		"agent",
 		"commands",
@@ -1278,93 +2421,263 @@ function renderAgentReportHtml(result) {
       <section class="panel">
         <h2>Terminal Agent Artifacts</h2>
         <div class="artifacts">
-          ${artifacts || "<p>No artifacts were captured.</p>"}
+          ${artifacts}
         </div>
       </section>
     </main>
   </body>
 </html>`;
 }
-function renderCommandBlock(label, argv) {
-	return `<div class="command">
-    <span>${escapeHtml(label)}</span>
-    <pre>${escapeHtml(formatAgentArgv(argv))}</pre>
-  </div>`;
+//#endregion
+//#region src/agent/report.ts
+async function writeAgentReport(path, result, options = {}) {
+	mkdirSync(dirname(path), { recursive: true });
+	await writeArtifactViewerPages(result, options);
+	writeFileSync(path, renderAgentReportHtml(result), "utf8");
 }
-function renderArtifactRow(artifact, artifactsDir, reportPath) {
-	const state = artifact.ok ? "pass" : "fail";
-	const href = relativeHref(reportPath, artifact.path, artifactsDir);
-	const baselineHref = artifact.baselinePath ? relativeHref(reportPath, artifact.baselinePath, artifactsDir) : "";
-	const diffHref = artifact.diffPath ? relativeHref(reportPath, artifact.diffPath, artifactsDir) : "";
-	return `<article class="artifact">
-    <span class="badge ${state}">${state}</span>
-    <div>
-      ${artifact.kind === "screenshot" && artifact.path ? `<a href="${escapeAttribute(href)}">open image</a>` : `<a href="${escapeAttribute(href)}">${escapeHtml(artifact.kind)}</a>`}
-      <div><code>${escapeHtml(artifact.viewport)} / ${escapeHtml(artifact.name)}</code></div>
-      ${baselineHref ? `<div><code>baseline ${escapeHtml(baselineHref)}</code></div>` : ""}
-      ${diffHref ? `<div><a href="${escapeAttribute(diffHref)}">diff</a></div>` : ""}
-      ${artifact.error ? `<div><code>${escapeHtml(artifact.error)}</code></div>` : ""}
-    </div>
-    <code>${escapeHtml(artifact.hash ?? "")}</code>
-  </article>`;
+//#endregion
+//#region src/agent/run_artifacts.ts
+function writeRunRecord(result, spec) {
+	const record = {
+		$schema: AGENT_RUN_RECORD_SCHEMA_URL,
+		version: 1,
+		name: result.name,
+		ok: result.ok,
+		startedAt: new Date(result.startedAt).toISOString(),
+		durationMs: result.durationMs,
+		mode: result.mode,
+		spec,
+		flowPath: relative(dirname(result.recordPath), result.flowPath),
+		artifactsDir: result.artifactsDir,
+		snapshotDir: result.snapshotDir,
+		reportPath: result.reportPath,
+		cassettePath: relative(dirname(result.recordPath), result.cassettePath),
+		cassetteFrameCount: result.cassetteFrameCount,
+		replayCommand: result.replayCommand,
+		commands: result.commands,
+		steps: result.steps,
+		artifacts: result.artifacts,
+		errors: result.errors
+	};
+	writeAgentRunRecordPath(result.recordPath, record);
+}
+function writeRunManifest(result) {
+	writeAgentManifestPath(agentManifestPath(result.artifactsDir), {
+		kind: "run",
+		ok: result.ok,
+		rootDir: result.artifactsDir,
+		primaryPath: result.recordPath,
+		commands: result.commands,
+		validation: {
+			ok: result.ok,
+			stages: [{
+				name: "run",
+				ok: result.ok,
+				totalCount: result.artifacts.length,
+				failureCount: result.artifacts.filter((artifact) => !artifact.ok).length
+			}]
+		},
+		files: [
+			{
+				path: result.flowPath,
+				kind: "flow",
+				role: "flow"
+			},
+			{
+				path: result.cassettePath,
+				kind: "cassette",
+				role: "cassette"
+			},
+			{
+				path: result.recordPath,
+				kind: "run-record",
+				role: "record",
+				ok: result.ok
+			},
+			{
+				path: result.reportPath,
+				kind: "report",
+				role: "report",
+				ok: result.ok
+			},
+			...result.artifacts.flatMap((artifact) => [{
+				path: artifact.path,
+				kind: artifact.kind,
+				role: "artifact",
+				ok: artifact.ok
+			}, {
+				path: artifact.diffPath,
+				kind: "diff",
+				role: "diff",
+				ok: artifact.ok
+			}])
+		]
+	});
+}
+function writeFlowArtifact(path, spec) {
+	writeFileSync(path, JSON.stringify(spec, null, 2) + "\n", "utf8");
+}
+//#endregion
+//#region src/agent/config_defaults.ts
+function normalizeAgentFlowSpecWithConfig(input, config) {
+	return normalizeAgentFlowSpec(applyAgentConfigDefaults(agentFlowSpecSchema.parse(input), config));
+}
+function applyAgentConfigDefaults(input, config) {
+	const agent = config?.agent;
+	if (!agent) return input;
+	const name = sanitizeArtifactName(input.name ?? "agent-flow");
+	const configDefaults = agent.defaults ?? {};
+	const specDefaults = input.defaults ?? {};
+	const viewports = input.viewports ? void 0 : cloneViewports(configDefaults.viewports);
+	return {
+		...input,
+		artifactsDir: input.artifactsDir ?? resolveNamedDir(agent.artifactsRoot, name, config.rootDir),
+		snapshotDir: input.snapshotDir ?? resolveNamedDir(agent.snapshotDir, name, config.rootDir),
+		viewports: viewports ?? input.viewports,
+		defaults: {
+			...specDefaults,
+			timeoutMs: specDefaults.timeoutMs ?? configDefaults.timeoutMs,
+			screenshot: specDefaults.screenshot ?? configDefaults.screenshot,
+			mask: mergeMaskRules(configDefaults.mask, specDefaults.mask)
+		}
+	};
+}
+function resolveNamedDir(root, name, configRoot) {
+	if (!root) return void 0;
+	const namedDir = join(root, name);
+	return isAbsolute(namedDir) ? namedDir : resolve(configRoot, namedDir);
+}
+function cloneViewports(viewports) {
+	return Array.isArray(viewports) && viewports.length > 0 ? viewports.map((viewport) => ({ ...viewport })) : void 0;
+}
+function mergeMaskRules(configMask, specMask) {
+	const merged = [...configMask ?? [], ...specMask ?? []];
+	return merged.length > 0 ? merged : void 0;
+}
+//#endregion
+//#region src/agent/command_launch.ts
+const DEFAULT_URL_REGEX = /https?:\/\/[^\s"'<>]+/;
+function buildCommandLaunchCommand(launch, options = {}) {
+	if (!launch.command) throw new Error("launch.command is required when launch.mode is 'command'");
+	const rootDir = options.rootDir ?? process.cwd();
+	const cwd = launch.cwd ? resolve(rootDir, launch.cwd) : rootDir;
+	return {
+		file: launch.command,
+		args: launch.args ?? [],
+		cwd,
+		env: {
+			...options.env ?? process.env,
+			...launch.env
+		},
+		label: launch.command,
+		urlRegex: launch.urlRegex,
+		waitForUrlMs: launch.waitForUrlMs
+	};
+}
+async function launchBrowserSessionFromCommand(command) {
+	const timeoutMs = command.waitForUrlMs ?? 15e3;
+	const child = spawn(command.file, command.args, {
+		cwd: command.cwd,
+		env: command.env,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	const stdoutChunks = [];
+	const stderrChunks = [];
+	return {
+		url: await new Promise((resolveUrl, reject) => {
+			let settled = false;
+			const timer = setTimeout(() => {
+				finish(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms waiting for ${command.label ?? command.file} session URL\nstdout=${stdoutChunks.join("").trim()}\nstderr=${stderrChunks.join("").trim()}`));
+			}, timeoutMs);
+			const finish = (result) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				child.stdout.off("data", onStdout);
+				child.stderr.off("data", onStderr);
+				child.off("error", onError);
+				child.off("exit", onExit);
+				if (result instanceof Error) reject(result);
+				else resolveUrl(result);
+			};
+			const readUrl = () => {
+				const found = extractUrlFromOutput(`${stdoutChunks.join("")}\n${stderrChunks.join("")}`, command.urlRegex);
+				if (found) finish(found);
+			};
+			const onStdout = (chunk) => {
+				stdoutChunks.push(chunk.toString("utf8"));
+				readUrl();
+			};
+			const onStderr = (chunk) => {
+				stderrChunks.push(chunk.toString("utf8"));
+				readUrl();
+			};
+			const onError = (error) => finish(error);
+			const onExit = (code, signal) => {
+				finish(/* @__PURE__ */ new Error(`${command.label ?? command.file} exited before printing a session URL (code=${code ?? "null"} signal=${signal ?? "null"})\nstdout=${stdoutChunks.join("").trim()}\nstderr=${stderrChunks.join("").trim()}`));
+			};
+			child.stdout.on("data", onStdout);
+			child.stderr.on("data", onStderr);
+			child.once("error", onError);
+			child.once("exit", onExit);
+		}),
+		process: child,
+		close: () => closeChild(child)
+	};
 }
-function relativeHref(_reportPath, targetPath, artifactsDir) {
-	if (targetPath.startsWith(artifactsDir)) return targetPath.slice(artifactsDir.length).replace(/^\/+/, "");
-	return targetPath;
+function extractUrlFromOutput(output, regexSource) {
+	if (!regexSource) return output.match(DEFAULT_URL_REGEX)?.[0] ?? null;
+	const match = output.match(new RegExp(regexSource, "m"));
+	return match?.[1] ?? match?.[0] ?? null;
 }
-function escapeHtml(input) {
-	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function formatBrowserLaunchCommand(command) {
+	return [command.file, ...command.args].join(" ");
 }
-function escapeAttribute(input) {
-	return escapeHtml(input).replace(/'/g, "&#39;");
+async function closeChild(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	await new Promise((resolveClose) => {
+		const timer = setTimeout(() => {
+			if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+			resolveClose();
+		}, 2e3);
+		child.once("exit", () => {
+			clearTimeout(timer);
+			resolveClose();
+		});
+		child.kill("SIGTERM");
+	});
 }
 //#endregion
-//#region src/agent/spec_loader.ts
-async function loadAgentSpec(specPath) {
-	const resolved = resolve(process.cwd(), specPath);
-	if (resolved.endsWith(".json")) {
-		const raw = JSON.parse(readFileSync(resolved, "utf8"));
-		return {
-			spec: normalizeAgentFlowSpec(raw),
-			raw,
-			path: resolved
-		};
-	}
-	const mod = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
-	const raw = mod.default ?? mod.spec;
+//#region src/agent/launch.ts
+function buildAgentLaunchCommand(launch, options = {}) {
+	if (resolveAgentLaunchMode(launch) === "url") return null;
+	return buildCommandLaunchCommand(launch, options);
+}
+async function resolveAgentLaunchTarget(launch, options = {}) {
+	const mode = resolveAgentLaunchMode(launch);
+	if (mode === "url") return {
+		mode,
+		url: launch.url,
+		session: null
+	};
+	const session = await launchBrowserSessionFromCommand(buildCommandLaunchCommand(launch, options));
 	return {
-		spec: normalizeAgentFlowSpec(raw),
-		raw,
-		path: resolved
+		mode,
+		url: session.url,
+		session
 	};
 }
-//#endregion
-//#region src/agent/runner.ts
-async function runAgentSpecPath(specPath, options = {}) {
-	return runAgentSpec((await loadAgentSpec(specPath)).raw, options);
-}
-async function replayAgentRecordPath(recordPath, options = {}) {
-	const raw = JSON.parse(readFileSync(recordPath, "utf8"));
-	if (isAgentCassetteLike(raw)) return replayAgentCassette(normalizeAgentCassette(raw), recordPath, options);
-	const record = readAgentRunRecordPath(recordPath);
-	if (record.cassettePath) {
-		const cassettePath = isAbsolute(record.cassettePath) ? record.cassettePath : resolve(dirname(recordPath), record.cassettePath);
-		return replayAgentCassette(readAgentCassettePath(cassettePath, record.spec), cassettePath, {
-			...options,
-			artifactsDir: options.artifactsDir ?? join(dirname(recordPath), "replay")
-		});
-	}
-	if (record.spec) return runAgentSpec(record.spec, {
-		...options,
-		config: void 0
-	});
-	if (!record.flowPath) throw new Error(`invalid agent run record: missing replay source in ${recordPath}`);
-	return runAgentSpecPath(isAbsolute(record.flowPath) ? record.flowPath : resolve(dirname(recordPath), record.flowPath), {
-		...options,
-		config: void 0
-	});
+function formatAgentLaunchCommand(launch) {
+	const command = buildAgentLaunchCommand(launch);
+	return command ? formatBrowserLaunchCommand(command) : "launch.mode=url";
 }
-async function runAgentSpec(input, options = {}) {
+//#endregion
+//#region src/agent/runner_setup.ts
+function prepareAgentRun(input, options) {
 	const startedAt = Date.now();
 	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
 	const spec = normalizeAgentFlowSpecWithConfig(input, options.replayCassette ? void 0 : options.config);
@@ -1385,161 +2698,51 @@ async function runAgentSpec(input, options = {}) {
 		"replay",
 		relative(process.cwd(), recordPath)
 	];
-	const result = {
-		ok: true,
-		name,
-		mode: options.replayCassette ? "replay" : "live",
+	return {
 		startedAt,
-		durationMs: 0,
+		rootDir,
+		spec,
+		name,
 		artifactsDir,
 		snapshotDir,
 		reportPath,
 		recordPath,
 		flowPath,
 		cassettePath,
-		replaySourceCassettePath: options.replaySourceCassettePath,
-		replayCommand: formatAgentArgv(replayArgv),
-		commands: {
-			replay: { argv: replayArgv },
-			updateSnapshots: { argv: [...replayArgv, "--update-snapshots"] }
-		},
-		agentFlavor: resolveAgentFlavor(spec),
-		viewports: spec.viewports ?? [],
-		cassetteFrameCount: cassette.frames.length,
-		steps: [],
-		artifacts: [],
-		errors: []
-	};
-	writeFileSync(flowPath, JSON.stringify(spec, null, 2) + "\n", "utf8");
-	let browser = null;
-	try {
-		browser = await launchAgentBrowser({ headless: options.headless ?? true });
-		for (const viewport of spec.viewports ?? []) await runViewport({
-			browser,
-			spec,
-			viewport,
-			rootDir,
-			artifactsDir,
-			snapshotDir,
-			updateSnapshots,
-			recordCassette: !options.replayCassette,
-			cassette,
-			result
-		});
-	} catch (error) {
-		result.ok = false;
-		result.errors.push(error instanceof Error ? error.message : String(error));
-	} finally {
-		await closeBrowserSafely(browser);
-		result.durationMs = Date.now() - startedAt;
-		if (options.replaySourceCassettePath) writeFileSync(cassettePath, readFileSync(options.replaySourceCassettePath, "utf8"), "utf8");
-		else writeFileSync(cassettePath, JSON.stringify(cassette, null, 2) + "\n", "utf8");
-		result.cassetteFrameCount = cassette.frames.length;
-		writeRunRecord(result, spec);
-		writeAgentReport(reportPath, result);
-		writeRunManifest(result);
-	}
-	return result;
-}
-async function runViewport(args) {
-	const { browser, spec, viewport, rootDir, artifactsDir, snapshotDir, updateSnapshots, recordCassette, cassette, result } = args;
-	const launchTarget = await resolveAgentLaunchTarget(spec.launch, { rootDir });
-	const context = await browser.newContext({
-		viewport: {
-			width: viewport.width,
-			height: viewport.height
-		},
-		deviceScaleFactor: viewport.deviceScaleFactor,
-		isMobile: viewport.isMobile,
-		hasTouch: viewport.hasTouch
-	});
-	const page = await context.newPage();
-	const ctx = {
-		spec,
-		viewport,
-		page,
-		artifactsDir,
-		snapshotDir,
 		updateSnapshots,
-		recordCassette,
-		masks: resolveAgentMasks(spec),
-		artifacts: result.artifacts,
-		replay: Boolean(args.cassette && !args.recordCassette),
-		cassette,
-		nextReplayPhase: 0
-	};
-	try {
-		await page.goto(launchTarget.url, {
-			waitUntil: "domcontentloaded",
-			timeout: spec.defaults?.timeoutMs ?? 3e4
-		});
-		await waitForTerminalRoot(page, spec.defaults?.timeoutMs ?? 3e4);
-		await captureCassetteFrame(ctx, {
-			stepIndex: null,
-			stepType: "initial"
-		});
-		for (let i = 0; i < spec.steps.length; i += 1) {
-			const step = spec.steps[i];
-			const started = Date.now();
-			try {
-				await runStep(ctx, step);
-				result.steps.push({
-					index: i,
-					type: step.type,
-					label: formatStepLabel(step),
-					durationMs: Date.now() - started,
-					ok: true
-				});
-				await captureCassetteFrame(ctx, {
-					stepIndex: i,
-					stepType: step.type
-				});
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				result.ok = false;
-				result.errors.push(`${viewport.name} step ${i + 1} ${step.type}: ${message}`);
-				result.steps.push({
-					index: i,
-					type: step.type,
-					label: formatStepLabel(step),
-					durationMs: Date.now() - started,
-					ok: false,
-					error: message
-				});
-				break;
-			}
-		}
-	} finally {
-		await withTimeout(context.close().catch(() => void 0), 5e3);
-		await launchTarget.session?.close();
-	}
-}
-async function replayAgentCassette(cassette, cassettePath, options) {
-	const server = await startAgentCassetteServer(cassette);
-	try {
-		const replaySpec = structuredClone(cassette.spec);
-		const replayCassette = structuredClone(cassette);
-		return await runAgentSpec({
-			...replaySpec,
-			launch: {
-				mode: "url",
-				url: server.url,
-				agentFlavor: replaySpec.launch.agentFlavor
-			}
-		}, {
-			...options,
-			artifactsDir: options.artifactsDir ?? join(dirname(cassettePath), "replay"),
-			replayCassette,
-			replaySourceCassettePath: cassettePath
-		});
-	} finally {
-		await server.close();
-	}
+		cassette,
+		result: {
+			ok: true,
+			name,
+			mode: options.replayCassette ? "replay" : "live",
+			startedAt,
+			durationMs: 0,
+			artifactsDir,
+			snapshotDir,
+			reportPath,
+			recordPath,
+			flowPath,
+			cassettePath,
+			replaySourceCassettePath: options.replaySourceCassettePath,
+			replayCommand: formatAgentArgv(replayArgv),
+			commands: {
+				replay: { argv: replayArgv },
+				updateSnapshots: { argv: [...replayArgv, "--update-snapshots"] }
+			},
+			agentFlavor: resolveAgentFlavor(spec),
+			viewports: spec.viewports ?? [],
+			cassetteFrameCount: cassette.frames.length,
+			steps: [],
+			artifacts: [],
+			errors: []
+		}
+	};
 }
-async function closeBrowserSafely(browser) {
-	if (!browser) return;
-	await withTimeout(browser.close().catch(() => void 0), 5e3);
+function formatAgentLaunchPlan(input) {
+	return formatAgentLaunchCommand(normalizeAgentFlowSpec(input).launch);
 }
+//#endregion
+//#region src/agent/timeout.ts
 async function withTimeout(promise, timeoutMs) {
 	let timer;
 	try {
@@ -1550,85 +2753,95 @@ async function withTimeout(promise, timeoutMs) {
 		if (timer) clearTimeout(timer);
 	}
 }
-async function runStep(ctx, step) {
-	const timeout = ctx.spec.defaults?.timeoutMs ?? 3e4;
-	if (step.type === "waitForText") {
-		await waitForTerminalText(ctx.page, {
-			text: step.text,
-			regex: step.regex,
-			timeoutMs: step.timeoutMs ?? timeout
-		});
-		return;
-	}
-	if (step.type === "typeText") {
-		await advanceReplayPhase(ctx);
-		if (!ctx.replay) {
-			await ctx.page.locator("[data-terminal-root]").first().click({ timeout });
-			await ctx.page.keyboard.type(step.text, { delay: step.delayMs });
-			if (step.enter) await ctx.page.keyboard.press("Enter");
+//#endregion
+//#region src/agent/step_label.ts
+function formatAgentStepLabel(step) {
+	if (step.type === "snapshot") return `snapshot ${step.name}`;
+	if (step.type === "waitForText") return `wait ${step.text ?? step.regex ?? ""}`;
+	if (step.type === "typeText") return `type ${step.text.slice(0, 24)}`;
+	if (step.type === "pressKey") return `press ${step.key}`;
+	if (step.type === "click") return `click ${step.selector ?? step.text ?? `${step.x},${step.y}`}`;
+	if (step.type === "mark") return `mark ${step.label ?? ""}`;
+	if (step.type === "sleep") return `sleep ${step.ms}ms`;
+	return step.type;
+}
+//#endregion
+//#region src/agent/snapshot_diff.ts
+function renderSnapshotDiff(expected, received) {
+	const expectedLines = expected.split("\n");
+	const receivedLines = received.split("\n");
+	const max = Math.max(expectedLines.length, receivedLines.length);
+	const out = ["--- expected", "+++ received"];
+	for (let i = 0; i < max; i += 1) {
+		const before = expectedLines[i];
+		const after = receivedLines[i];
+		if (before === after) {
+			if (before !== void 0) out.push(`  ${before}`);
+			continue;
 		}
-		return;
+		if (before !== void 0) out.push(`- ${before}`);
+		if (after !== void 0) out.push(`+ ${after}`);
 	}
-	if (step.type === "pressKey") {
-		await advanceReplayPhase(ctx);
-		if (!ctx.replay) await ctx.page.keyboard.press(step.key);
-		return;
+	return out.join("\n") + "\n";
+}
+//#endregion
+//#region src/agent/terminal_dom.ts
+async function waitForTerminalRoot(page, timeoutMs) {
+	await page.locator("[data-terminal-root]").first().waitFor({
+		state: "attached",
+		timeout: timeoutMs
+	});
+}
+async function waitForTerminalText(page, args) {
+	const started = Date.now();
+	const matcher = args.regex ? new RegExp(args.regex) : null;
+	while (Date.now() - started < args.timeoutMs) {
+		const text = await readTerminalText(page);
+		if (args.text && text.includes(args.text)) return;
+		if (matcher?.test(text)) return;
+		await new Promise((resolvePoll) => setTimeout(resolvePoll, 100));
 	}
-	if (step.type === "click") {
-		await advanceReplayPhase(ctx);
-		if (ctx.replay) return;
-		if (step.selector) {
-			await ctx.page.locator(step.selector).first().click({ timeout });
-			return;
-		}
-		if (step.text) {
-			await ctx.page.getByText(step.text, { exact: false }).first().click({ timeout });
-			return;
+	throw new Error(`timed out waiting for terminal text ${args.text ?? args.regex ?? ""}`);
+}
+async function waitForStableDom(page, args) {
+	const started = Date.now();
+	let last = "";
+	let stableSince = Date.now();
+	while (Date.now() - started < args.timeoutMs) {
+		const current = await readTerminalDomIfPresent(page);
+		if (current === null) {
+			await new Promise((resolvePoll) => setTimeout(resolvePoll, args.intervalMs));
+			continue;
 		}
-		await ctx.page.mouse.click(step.x, step.y);
-		return;
-	}
-	if (step.type === "waitForStableDom") {
-		await waitForStableDom(ctx.page, {
-			timeoutMs: step.timeoutMs ?? timeout,
-			quietMs: step.quietMs ?? 350,
-			intervalMs: step.intervalMs ?? 100
-		});
-		return;
-	}
-	if (step.type === "snapshot") {
-		await captureSnapshotStep(ctx, step);
-		return;
-	}
-	if (step.type === "sleep") {
-		if (!ctx.replay) await new Promise((resolveSleep) => setTimeout(resolveSleep, step.ms));
-		return;
+		if (current !== last) {
+			last = current;
+			stableSince = Date.now();
+		} else if (Date.now() - stableSince >= args.quietMs) return;
+		await new Promise((resolvePoll) => setTimeout(resolvePoll, args.intervalMs));
 	}
-	if (step.type === "mark") return;
+	throw new Error(`timed out waiting for stable terminal DOM`);
 }
-async function captureCassetteFrame(ctx, frame) {
-	if (!ctx.cassette || !ctx.recordCassette) return;
-	const phase = ctx.nextReplayPhase;
-	upsertAgentCassetteFrame(ctx.cassette, {
-		viewport: ctx.viewport,
-		phase,
-		stepIndex: frame.stepIndex,
-		stepType: frame.stepType,
-		terminalText: normalizeTerminalText(await readTerminalText(ctx.page), ctx.masks),
-		dom: normalizeDomSnapshot(await readTerminalDom(ctx.page), ctx.masks),
-		capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+async function readTerminalText(page) {
+	const text = await page.evaluate(() => {
+		const node = document.querySelector("[data-terminal-root]");
+		if (!node) return null;
+		const rows = Array.from(node.querySelectorAll(".term-grid .term-row"));
+		if (rows.length > 0) return rows.map((row) => row.textContent ?? "").join("\n");
+		return node.textContent ?? "";
 	});
+	if (text === null) throw new Error("terminal root is not attached");
+	return text;
 }
-async function advanceReplayPhase(ctx) {
-	if (!ctx.replay) {
-		ctx.nextReplayPhase += 1;
-		return;
-	}
-	ctx.nextReplayPhase += 1;
-	await ctx.page.evaluate((phase) => {
-		window.__ptywrightReplaySetPhase?.(phase);
-	}, ctx.nextReplayPhase);
+async function readTerminalDom(page) {
+	const dom = await readTerminalDomIfPresent(page);
+	if (dom === null) throw new Error("terminal root is not attached");
+	return dom;
+}
+async function readTerminalDomIfPresent(page) {
+	return page.evaluate(() => document.querySelector("[data-terminal-root]")?.innerHTML ?? null);
 }
+//#endregion
+//#region src/agent/snapshot_artifacts.ts
 async function captureSnapshotStep(ctx, step) {
 	const targets = step.targets ?? [
 		"terminal",
@@ -1636,7 +2849,8 @@ async function captureSnapshotStep(ctx, step) {
 		...ctx.spec.defaults?.screenshot ? ["screenshot"] : []
 	];
 	const base = `${sanitizeArtifactName(ctx.viewport.name)}.${sanitizeArtifactName(step.name)}`;
-	for (const target of targets) {
+	const errors = [];
+	for (const target of targets) try {
 		if (target === "terminal") {
 			const text = normalizeTerminalText(await readTerminalText(ctx.page), ctx.masks);
 			await writeComparableArtifact(ctx, {
@@ -1675,7 +2889,10 @@ async function captureSnapshotStep(ctx, step) {
 			path: screenshotPath,
 			ok: true
 		});
+	} catch (error) {
+		errors.push(error instanceof Error ? error.message : String(error));
 	}
+	if (errors.length > 0) throw new Error(errors.join("; "));
 }
 async function writeComparableArtifact(ctx, artifact) {
 	const artifactPath = join(ctx.artifactsDir, artifact.relativePath);
@@ -1752,172 +2969,255 @@ async function writeComparableArtifact(ctx, artifact) {
 		ok: true
 	});
 }
-function renderSnapshotDiff(expected, received) {
-	const expectedLines = expected.split("\n");
-	const receivedLines = received.split("\n");
-	const max = Math.max(expectedLines.length, receivedLines.length);
-	const out = ["--- expected", "+++ received"];
-	for (let i = 0; i < max; i += 1) {
-		const before = expectedLines[i];
-		const after = receivedLines[i];
-		if (before === after) {
-			if (before !== void 0) out.push(`  ${before}`);
-			continue;
+//#endregion
+//#region src/agent/step_runner.ts
+async function runAgentStep(ctx, step) {
+	const timeout = ctx.spec.defaults?.timeoutMs ?? 3e4;
+	if (step.type === "waitForText") {
+		await waitForTerminalText(ctx.page, {
+			text: step.text,
+			regex: step.regex,
+			timeoutMs: step.timeoutMs ?? timeout
+		});
+		return;
+	}
+	if (step.type === "typeText") {
+		await advanceReplayPhase(ctx);
+		if (!ctx.replay) {
+			await ctx.page.locator("[data-terminal-root]").first().click({ timeout });
+			await ctx.page.keyboard.type(step.text, { delay: step.delayMs });
+			if (step.enter) await ctx.page.keyboard.press("Enter");
 		}
-		if (before !== void 0) out.push(`- ${before}`);
-		if (after !== void 0) out.push(`+ ${after}`);
+		return;
 	}
-	return out.join("\n") + "\n";
-}
-async function waitForTerminalRoot(page, timeoutMs) {
-	await page.locator("[data-terminal-root]").first().waitFor({
-		state: "attached",
-		timeout: timeoutMs
-	});
-}
-async function waitForTerminalText(page, args) {
-	const started = Date.now();
-	const matcher = args.regex ? new RegExp(args.regex) : null;
-	while (Date.now() - started < args.timeoutMs) {
-		const text = await readTerminalText(page);
-		if (args.text && text.includes(args.text)) return;
-		if (matcher?.test(text)) return;
-		await new Promise((resolvePoll) => setTimeout(resolvePoll, 100));
+	if (step.type === "pressKey") {
+		await advanceReplayPhase(ctx);
+		if (!ctx.replay) await ctx.page.keyboard.press(step.key);
+		return;
 	}
-	throw new Error(`timed out waiting for terminal text ${args.text ?? args.regex ?? ""}`);
-}
-async function waitForStableDom(page, args) {
-	const started = Date.now();
-	let last = "";
-	let stableSince = Date.now();
-	while (Date.now() - started < args.timeoutMs) {
-		const current = await readTerminalDomIfPresent(page);
-		if (current === null) {
-			await new Promise((resolvePoll) => setTimeout(resolvePoll, args.intervalMs));
-			continue;
+	if (step.type === "click") {
+		await advanceReplayPhase(ctx);
+		if (ctx.replay) return;
+		if (step.selector) {
+			await ctx.page.locator(step.selector).first().click({ timeout });
+			return;
 		}
-		if (current !== last) {
-			last = current;
-			stableSince = Date.now();
-		} else if (Date.now() - stableSince >= args.quietMs) return;
-		await new Promise((resolvePoll) => setTimeout(resolvePoll, args.intervalMs));
+		if (step.text) {
+			await ctx.page.getByText(step.text, { exact: false }).first().click({ timeout });
+			return;
+		}
+		await ctx.page.mouse.click(step.x, step.y);
+		return;
 	}
-	throw new Error(`timed out waiting for stable terminal DOM`);
-}
-async function readTerminalText(page) {
-	const text = await page.evaluate(() => {
-		const node = document.querySelector("[data-terminal-root]");
-		if (!node) return null;
-		const rows = Array.from(node.querySelectorAll(".term-grid .term-row"));
-		if (rows.length > 0) return rows.map((row) => row.textContent ?? "").join("\n");
-		return node.textContent ?? "";
-	});
-	if (text === null) throw new Error("terminal root is not attached");
-	return text;
+	if (step.type === "waitForStableDom") {
+		await waitForStableDom(ctx.page, {
+			timeoutMs: step.timeoutMs ?? timeout,
+			quietMs: step.quietMs ?? 350,
+			intervalMs: step.intervalMs ?? 100
+		});
+		return;
+	}
+	if (step.type === "snapshot") {
+		await captureSnapshotStep(ctx, step);
+		return;
+	}
+	if (step.type === "sleep") {
+		if (!ctx.replay) await new Promise((resolveSleep) => setTimeout(resolveSleep, step.ms));
+		return;
+	}
+	if (step.type === "mark") return;
 }
-async function readTerminalDom(page) {
-	const dom = await readTerminalDomIfPresent(page);
-	if (dom === null) throw new Error("terminal root is not attached");
-	return dom;
+async function captureCassetteFrame(ctx, frame) {
+	if (!ctx.cassette || !ctx.recordCassette) return;
+	const phase = ctx.nextReplayPhase;
+	upsertAgentCassetteFrame(ctx.cassette, {
+		viewport: ctx.viewport,
+		phase,
+		stepIndex: frame.stepIndex,
+		stepType: frame.stepType,
+		terminalText: normalizeTerminalText(await readTerminalText(ctx.page), ctx.masks),
+		dom: normalizeDomSnapshot(await readTerminalDom(ctx.page), ctx.masks),
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
 }
-async function readTerminalDomIfPresent(page) {
-	return page.evaluate(() => document.querySelector("[data-terminal-root]")?.innerHTML ?? null);
+async function advanceReplayPhase(ctx) {
+	if (!ctx.replay) {
+		ctx.nextReplayPhase += 1;
+		return;
+	}
+	ctx.nextReplayPhase += 1;
+	await ctx.page.evaluate((phase) => {
+		window.__ptywrightReplaySetPhase?.(phase);
+	}, ctx.nextReplayPhase);
 }
-function writeRunRecord(result, spec) {
-	const record = {
-		$schema: AGENT_RUN_RECORD_SCHEMA_URL,
-		version: 1,
-		name: result.name,
-		ok: result.ok,
-		startedAt: new Date(result.startedAt).toISOString(),
-		durationMs: result.durationMs,
-		mode: result.mode,
+//#endregion
+//#region src/agent/viewport_runner.ts
+async function runAgentViewport(args) {
+	const { browser, spec, viewport, rootDir, artifactsDir, snapshotDir, updateSnapshots, recordCassette, cassette, result } = args;
+	const launchTarget = await resolveAgentLaunchTarget(spec.launch, { rootDir });
+	const context = await browser.newContext({
+		viewport: {
+			width: viewport.width,
+			height: viewport.height
+		},
+		deviceScaleFactor: viewport.deviceScaleFactor,
+		isMobile: viewport.isMobile,
+		hasTouch: viewport.hasTouch
+	});
+	const page = await context.newPage();
+	const ctx = {
 		spec,
-		flowPath: relative(dirname(result.recordPath), result.flowPath),
-		artifactsDir: result.artifactsDir,
-		snapshotDir: result.snapshotDir,
-		reportPath: result.reportPath,
-		cassettePath: relative(dirname(result.recordPath), result.cassettePath),
-		cassetteFrameCount: result.cassetteFrameCount,
-		replayCommand: result.replayCommand,
-		commands: result.commands,
-		steps: result.steps,
+		viewport,
+		page,
+		artifactsDir,
+		snapshotDir,
+		updateSnapshots,
+		recordCassette,
+		masks: resolveAgentMasks(spec),
 		artifacts: result.artifacts,
-		errors: result.errors
+		replay: Boolean(args.cassette && !args.recordCassette),
+		cassette,
+		nextReplayPhase: 0
 	};
-	writeAgentRunRecordPath(result.recordPath, record);
+	try {
+		await page.goto(resolveViewportUrl(launchTarget.url, viewport), {
+			waitUntil: "domcontentloaded",
+			timeout: spec.defaults?.timeoutMs ?? 3e4
+		});
+		await waitForTerminalRoot(page, spec.defaults?.timeoutMs ?? 3e4);
+		await captureCassetteFrame(ctx, {
+			stepIndex: null,
+			stepType: "initial"
+		});
+		for (let i = 0; i < spec.steps.length; i += 1) {
+			const step = spec.steps[i];
+			const started = Date.now();
+			try {
+				await runAgentStep(ctx, step);
+				result.steps.push({
+					index: i,
+					type: step.type,
+					label: formatAgentStepLabel(step),
+					durationMs: Date.now() - started,
+					ok: true
+				});
+				await captureCassetteFrame(ctx, {
+					stepIndex: i,
+					stepType: step.type
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				result.ok = false;
+				result.errors.push(`${viewport.name} step ${i + 1} ${step.type}: ${message}`);
+				result.steps.push({
+					index: i,
+					type: step.type,
+					label: formatAgentStepLabel(step),
+					durationMs: Date.now() - started,
+					ok: false,
+					error: message
+				});
+				break;
+			}
+		}
+	} finally {
+		await withTimeout(context.close().catch(() => void 0), 5e3);
+		await launchTarget.session?.close();
+	}
 }
-function writeRunManifest(result) {
-	writeAgentManifestPath(agentManifestPath(result.artifactsDir), {
-		kind: "run",
-		ok: result.ok,
-		rootDir: result.artifactsDir,
-		primaryPath: result.recordPath,
-		commands: result.commands,
-		validation: {
-			ok: result.ok,
-			stages: [{
-				name: "run",
-				ok: result.ok,
-				totalCount: result.artifacts.length,
-				failureCount: result.artifacts.filter((artifact) => !artifact.ok).length
-			}]
-		},
-		files: [
-			{
-				path: result.flowPath,
-				kind: "flow",
-				role: "flow"
-			},
-			{
-				path: result.cassettePath,
-				kind: "cassette",
-				role: "cassette"
-			},
-			{
-				path: result.recordPath,
-				kind: "run-record",
-				role: "record",
-				ok: result.ok
-			},
-			{
-				path: result.reportPath,
-				kind: "report",
-				role: "report",
-				ok: result.ok
-			},
-			...result.artifacts.flatMap((artifact) => [{
-				path: artifact.path,
-				kind: artifact.kind,
-				role: "artifact",
-				ok: artifact.ok
-			}, {
-				path: artifact.diffPath,
-				kind: "diff",
-				role: "diff",
-				ok: artifact.ok
-			}])
-		]
+function resolveViewportUrl(url, viewport) {
+	return url.replaceAll("{viewportName}", encodeURIComponent(viewport.name)).replaceAll("{viewportWidth}", encodeURIComponent(String(viewport.width))).replaceAll("{viewportHeight}", encodeURIComponent(String(viewport.height)));
+}
+//#endregion
+//#region src/agent/runner.ts
+async function runAgentSpecPath(specPath, options = {}) {
+	return runAgentSpec((await loadAgentSpec(specPath)).raw, options);
+}
+async function replayAgentRecordPath(recordPath, options = {}) {
+	const raw = JSON.parse(readFileSync(recordPath, "utf8"));
+	if (isAgentCassetteLike(raw)) return replayAgentCassette(normalizeAgentCassette(raw), recordPath, options);
+	const record = readAgentRunRecordPath(recordPath);
+	if (record.cassettePath) {
+		const cassettePath = isAbsolute(record.cassettePath) ? record.cassettePath : resolve(dirname(recordPath), record.cassettePath);
+		return replayAgentCassette(readAgentCassettePath(cassettePath, record.spec), cassettePath, {
+			...options,
+			artifactsDir: options.artifactsDir ?? join(dirname(recordPath), "replay")
+		});
+	}
+	if (record.spec) return runAgentSpec(record.spec, {
+		...options,
+		config: void 0
+	});
+	if (!record.flowPath) throw new Error(`invalid agent run record: missing replay source in ${recordPath}`);
+	return runAgentSpecPath(isAbsolute(record.flowPath) ? record.flowPath : resolve(dirname(recordPath), record.flowPath), {
+		...options,
+		config: void 0
 	});
 }
-function formatStepLabel(step) {
-	if (step.type === "snapshot") return `snapshot ${step.name}`;
-	if (step.type === "waitForText") return `wait ${step.text ?? step.regex ?? ""}`;
-	if (step.type === "typeText") return `type ${step.text.slice(0, 24)}`;
-	if (step.type === "pressKey") return `press ${step.key}`;
-	if (step.type === "click") return `click ${step.selector ?? step.text ?? `${step.x},${step.y}`}`;
-	if (step.type === "mark") return `mark ${step.label ?? ""}`;
-	if (step.type === "sleep") return `sleep ${step.ms}ms`;
-	return step.type;
+async function runAgentSpec(input, options = {}) {
+	const { artifactsDir, cassette, cassettePath, flowPath, reportPath, result, rootDir, snapshotDir, spec, startedAt, updateSnapshots } = prepareAgentRun(input, options);
+	writeFlowArtifact(flowPath, spec);
+	let browser = null;
+	try {
+		browser = await launchAgentBrowser({ headless: options.headless ?? true });
+		for (const viewport of spec.viewports ?? []) await runAgentViewport({
+			browser,
+			spec,
+			viewport,
+			rootDir,
+			artifactsDir,
+			snapshotDir,
+			updateSnapshots,
+			recordCassette: !options.replayCassette,
+			cassette,
+			result
+		});
+	} catch (error) {
+		result.ok = false;
+		result.errors.push(error instanceof Error ? error.message : String(error));
+	} finally {
+		await closeBrowserSafely(browser);
+		result.durationMs = Date.now() - startedAt;
+		if (options.replaySourceCassettePath) writeFileSync(cassettePath, readFileSync(options.replaySourceCassettePath, "utf8"), "utf8");
+		else writeFileSync(cassettePath, JSON.stringify(cassette, null, 2) + "\n", "utf8");
+		result.cassetteFrameCount = cassette.frames.length;
+		writeRunRecord(result, spec);
+		await writeAgentReport(reportPath, result, { config: options.config });
+		writeRunManifest(result);
+	}
+	return result;
+}
+async function replayAgentCassette(cassette, cassettePath, options) {
+	const server = await startAgentCassetteServer(cassette);
+	try {
+		const replaySpec = structuredClone(cassette.spec);
+		const replayCassette = structuredClone(cassette);
+		return await runAgentSpec({
+			...replaySpec,
+			launch: {
+				mode: "url",
+				url: withReplayViewportQuery(server.url),
+				agentFlavor: replaySpec.launch.agentFlavor
+			}
+		}, {
+			...options,
+			artifactsDir: options.artifactsDir ?? join(dirname(cassettePath), "replay"),
+			replayCassette,
+			replaySourceCassettePath: cassettePath
+		});
+	} finally {
+		await server.close();
+	}
 }
-function envTruthy(value) {
-	return value === "1" || value === "true" || value === "yes";
+function withReplayViewportQuery(url) {
+	return `${url}${url.includes("?") ? "&" : "?"}viewportName={viewportName}&viewportWidth={viewportWidth}&viewportHeight={viewportHeight}`;
 }
-function printAgentLaunchPlan(input) {
-	return formatAgentLaunchCommand(normalizeAgentFlowSpec(input).launch);
+async function closeBrowserSafely(browser) {
+	if (!browser) return;
+	await withTimeout(browser.close().catch(() => void 0), 5e3);
 }
 function defaultSpecNameForPath(path) {
 	return sanitizeArtifactName(basename(path, extname(path)));
 }
 //#endregion
-export { agentManifestPath as C, writeAgentManifestPath as D, validateAgentManifestFiles as E, AGENT_MANIFEST_FILE_NAME as S, readAgentManifestPath as T, isAgentCassetteLike as _, runAgentSpecPath as a, sanitizeArtifactName as b, agentRunModeSchema as c, readAgentRunRecordPath as d, writeAgentRunRecordPath as f, normalizeAgentFlowSpecWithConfig as g, resolveAgentLaunchTarget as h, runAgentSpec as i, formatAgentArgv as l, createAgentTemplateSpec as m, printAgentLaunchPlan as n, loadAgentSpec as o, formatArgv as p, replayAgentRecordPath as r, AGENT_RUN_RECORD_SCHEMA_URL as s, defaultSpecNameForPath as t, isAgentRunRecordLike as u, readAgentCassettePath as v, isAgentManifestLike as w, launchAgentBrowser as x, normalizeAgentFlowSpec as y };
+export { writeAgentManifestPath as C, escapeHtml as D, escapeAttribute as E, normalizeAgentFlowSpec as O, validateAgentManifestFiles as S, readAgentCassettePath as T, formatArgv as _, formatAgentLaunchPlan as a, isAgentManifestLike as b, launchAgentBrowser as c, AGENT_RUN_RECORD_SCHEMA_URL as d, agentRunModeSchema as f, writeAgentRunRecordPath as g, readAgentRunRecordPath as h, runAgentSpecPath as i, sanitizeArtifactName as k, createAgentTemplateSpec as l, isAgentRunRecordLike as m, replayAgentRecordPath as n, resolveAgentLaunchTarget as o, formatAgentArgv as p, runAgentSpec as r, normalizeAgentFlowSpecWithConfig as s, defaultSpecNameForPath as t, loadAgentSpec as u, AGENT_MANIFEST_FILE_NAME as v, isAgentCassetteLike as w, readAgentManifestPath as x, agentManifestPath as y };