ptywright 0.3.0 → 0.5.0

package/dist/{runner-zi0nItvB.mjs → runner-C1gPRyCM.mjs}

@@ -1,223 +1,20 @@
-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 { 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 { 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 +31,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 +44,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 +194,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 +238,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 +253,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 +284,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,130 +377,340 @@ 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/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
+//#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: []
 	};
 }
-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 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);
+}
+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);
+}
+//#endregion
+//#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(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
+function formatArgv(argv) {
+	return argv.map(formatArg).join(" ");
+}
+function formatArg(arg) {
+	if (/^[A-Za-z0-9_./:=@+-]+$/.test(arg)) return arg;
+	return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+//#endregion
+//#region src/agent/run_record.ts
+const AGENT_RUN_RECORD_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-run.schema.json";
+const agentRunModeSchema = z.enum(["live", "replay"]);
+const agentRecordedStepSchema = z.object({
+	index: z.number().int().nonnegative(),
+	type: z.string().min(1),
+	label: z.string(),
+	durationMs: z.number().int().nonnegative(),
+	ok: z.boolean(),
+	error: z.string().optional()
+}).strict();
+const agentRunArtifactSchema = z.object({
+	name: z.string().min(1),
+	viewport: z.string().min(1),
+	kind: z.enum([
+		"terminal",
+		"dom",
+		"screenshot"
+	]),
+	path: z.string().min(1),
+	baselinePath: z.string().min(1).optional(),
+	diffPath: z.string().min(1).optional(),
+	hash: z.string().min(1).optional(),
+	ok: z.boolean(),
+	error: z.string().optional()
+}).strict();
+const agentCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentRunRecordCommandsSchema = z.object({
+	replay: agentCommandSchema,
+	updateSnapshots: agentCommandSchema
+}).strict();
+const agentRunRecordSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	name: z.string().min(1),
+	ok: z.boolean(),
+	startedAt: z.string().min(1),
+	durationMs: z.number().int().nonnegative(),
+	mode: agentRunModeSchema,
+	spec: agentFlowSpecSchema.optional(),
+	flowPath: z.string().min(1).optional(),
+	artifactsDir: z.string().min(1),
+	snapshotDir: z.string().min(1),
+	reportPath: z.string().min(1),
+	cassettePath: z.string().min(1).optional(),
+	cassetteFrameCount: z.number().int().nonnegative(),
+	replayCommand: z.string().min(1),
+	commands: agentRunRecordCommandsSchema,
+	steps: z.array(agentRecordedStepSchema),
+	artifacts: z.array(agentRunArtifactSchema),
+	errors: z.array(z.string())
+}).strict().superRefine((record, ctx) => {
+	if (!record.cassettePath && !record.flowPath && !record.spec) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "agent run record requires cassettePath, flowPath, or spec"
+	});
+	const replayCommand = formatArgv(record.commands.replay.argv);
+	if (record.replayCommand !== replayCommand) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["replayCommand"],
+		message: "replayCommand must match commands.replay.argv"
+	});
+	if (!isReplayArgv(record.commands.replay.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"replay",
+			"argv"
+		],
+		message: "replay argv must be a ptywright agent replay command"
+	});
+	const expectedUpdateSnapshots = [...record.commands.replay.argv, "--update-snapshots"];
+	if (!sameArgv(record.commands.updateSnapshots.argv, expectedUpdateSnapshots)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"updateSnapshots",
+			"argv"
+		],
+		message: "updateSnapshots argv must extend commands.replay.argv"
+	});
+});
+function normalizeAgentRunRecord(input) {
+	try {
+		const parsed = agentRunRecordSchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-run.schema.json",
+			spec: parsed.spec ? normalizeAgentFlowSpec(parsed.spec) : void 0
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent run record: ${formatZodIssues(error)}`);
+		throw error;
+	}
 }
-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 formatAgentArgv(argv) {
+	return formatArgv(argv);
 }
-function formatBrowserLaunchCommand(command) {
-	return [command.file, ...command.args].join(" ");
+function isReplayArgv(argv) {
+	return argv.length >= 4 && argv[0] === "ptywright" && argv[1] === "agent" && argv[2] === "replay";
 }
-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 readAgentRunRecordPath(path) {
+	return normalizeAgentRunRecord(JSON.parse(readFileSync(path, "utf8")));
+}
+function writeAgentRunRecordPath(path, record) {
+	const normalized = normalizeAgentRunRecord({
+		...record,
+		$schema: record.$schema ?? "https://ptywright.local/schemas/ptywright-agent-run.schema.json"
 	});
+	writeFileSync(path, JSON.stringify(normalized, null, 2) + "\n", "utf8");
 }
-//#endregion
-//#region src/agent/launch.ts
-function buildAgentLaunchCommand(launch, options = {}) {
-	if (resolveAgentLaunchMode(launch) === "url") return null;
-	return buildCommandLaunchCommand(launch, options);
+function isAgentRunRecordLike(input) {
+	if (typeof input !== "object" || input === null) return false;
+	const candidate = input;
+	return candidate.version === 1 && ("cassettePath" in candidate || "flowPath" in candidate || "spec" in candidate);
 }
-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));
+//#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;
 	return {
-		mode,
-		url: session.url,
-		session
+		spec: normalizeAgentFlowSpec(raw),
+		raw,
+		path: resolved
 	};
 }
-function formatAgentLaunchCommand(launch) {
-	const command = buildAgentLaunchCommand(launch);
-	return command ? formatBrowserLaunchCommand(command) : "launch.mode=url";
-}
 //#endregion
 //#region src/agent/presets.ts
 const COMMON_AGENT_MASKS = [
@@ -777,7 +744,7 @@ const COMMON_AGENT_MASKS = [
 ];
 const FLAVOR_MASKS = {
 	codex: [{
-		regex: "\\b(?:gpt|o)[A-Za-z0-9._:-]+\\b",
+		regex: "\\b(?:gpt-[A-Za-z0-9._:-]+|o[0-9][A-Za-z0-9._:-]*)\\b",
 		flags: "gi",
 		replacement: "<model>"
 	}, {
@@ -867,157 +834,982 @@ function createAgentTemplateSpec(flavor) {
 	};
 }
 //#endregion
-//#region src/common/argv.ts
-function formatArgv(argv) {
-	return argv.map(formatArg).join(" ");
+//#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 10px;
+        color: var(--muted);
+        font-size: 12px;
+        text-decoration: none;
+      }
+      .viewer-link {
+        color: var(--focus);
+        font-weight: 700;
+      }
+      .viewer-stage {
+        display: grid;
+        grid-template-columns: max-content;
+        grid-template-rows: max-content;
+        min-width: 0;
+        min-height: 0;
+        justify-content: start;
+        align-content: start;
+        overflow: auto;
+        background:
+          radial-gradient(circle at top left, rgba(121, 192, 255, 0.1), transparent 32%),
+          #060a13;
+        padding: 14px;
+      }
+      .viewer-viewport {
+        width: var(--config-viewport-width);
+        height: var(--config-viewport-height);
+        max-width: none;
+        max-height: none;
+        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: var(--config-viewport-width);
+      }
+      .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: var(--config-viewport-width);
+          height: var(--config-viewport-height);
+          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 formatArg(arg) {
-	if (/^[A-Za-z0-9_./:=@+-]+$/.test(arg)) return arg;
-	return `'${arg.replace(/'/g, "'\\''")}'`;
+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/run_record.ts
-const AGENT_RUN_RECORD_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-run.schema.json";
-const agentRunModeSchema = z.enum(["live", "replay"]);
-const agentRecordedStepSchema = z.object({
-	index: z.number().int().nonnegative(),
-	type: z.string().min(1),
-	label: z.string(),
-	durationMs: z.number().int().nonnegative(),
-	ok: z.boolean(),
-	error: z.string().optional()
-}).strict();
-const agentRunArtifactSchema = z.object({
-	name: z.string().min(1),
-	viewport: z.string().min(1),
-	kind: z.enum([
-		"terminal",
-		"dom",
-		"screenshot"
-	]),
-	path: z.string().min(1),
-	baselinePath: z.string().min(1).optional(),
-	diffPath: z.string().min(1).optional(),
-	hash: z.string().min(1).optional(),
-	ok: z.boolean(),
-	error: z.string().optional()
-}).strict();
-const agentCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
-const agentRunRecordCommandsSchema = z.object({
-	replay: agentCommandSchema,
-	updateSnapshots: agentCommandSchema
-}).strict();
-const agentRunRecordSchema = z.object({
-	$schema: z.string().optional(),
-	version: z.literal(1),
-	name: z.string().min(1),
-	ok: z.boolean(),
-	startedAt: z.string().min(1),
-	durationMs: z.number().int().nonnegative(),
-	mode: agentRunModeSchema,
-	spec: agentFlowSpecSchema.optional(),
-	flowPath: z.string().min(1).optional(),
-	artifactsDir: z.string().min(1),
-	snapshotDir: z.string().min(1),
-	reportPath: z.string().min(1),
-	cassettePath: z.string().min(1).optional(),
-	cassetteFrameCount: z.number().int().nonnegative(),
-	replayCommand: z.string().min(1),
-	commands: agentRunRecordCommandsSchema,
-	steps: z.array(agentRecordedStepSchema),
-	artifacts: z.array(agentRunArtifactSchema),
-	errors: z.array(z.string())
-}).strict().superRefine((record, ctx) => {
-	if (!record.cassettePath && !record.flowPath && !record.spec) ctx.addIssue({
-		code: z.ZodIssueCode.custom,
-		message: "agent run record requires cassettePath, flowPath, or spec"
-	});
-	const replayCommand = formatArgv(record.commands.replay.argv);
-	if (record.replayCommand !== replayCommand) ctx.addIssue({
-		code: z.ZodIssueCode.custom,
-		path: ["replayCommand"],
-		message: "replayCommand must match commands.replay.argv"
-	});
-	if (!isReplayArgv(record.commands.replay.argv)) ctx.addIssue({
-		code: z.ZodIssueCode.custom,
-		path: [
-			"commands",
-			"replay",
-			"argv"
-		],
-		message: "replay argv must be a ptywright agent replay command"
-	});
-	const expectedUpdateSnapshots = [...record.commands.replay.argv, "--update-snapshots"];
-	if (!sameArgv(record.commands.updateSnapshots.argv, expectedUpdateSnapshots)) ctx.addIssue({
-		code: z.ZodIssueCode.custom,
-		path: [
-			"commands",
-			"updateSnapshots",
-			"argv"
-		],
-		message: "updateSnapshots argv must extend commands.replay.argv"
-	});
-});
-function normalizeAgentRunRecord(input) {
+//#region src/agent/report_view_options.ts
+function isMobileViewport(viewport) {
+	return Boolean(viewport?.isMobile || viewport?.hasTouch || (viewport?.width ?? 9999) <= 720);
+}
+function resolveReportViewOptions(result) {
+	const launchArgSets = [readFlowLaunchArgs(result.flowPath), readCassetteLaunchArgs(result.replaySourceCassettePath ?? result.cassettePath)];
+	const screenModeArg = readFlagValueFromArgSets(launchArgSets, "--experimental-screen-mode");
+	const themeArg = readFlagValueFromArgSets(launchArgSets, "--theme");
+	const fontSizeArg = readFlagValueFromArgSets(launchArgSets, "--font-size");
+	const lineHeightArg = readFlagValueFromArgSets(launchArgSets, "--line-height");
+	return {
+		fontSize: parsePositiveNumber(fontSizeArg) ?? 15,
+		lineHeight: parsePositiveNumber(lineHeightArg) ?? 1.6,
+		screenMode: screenModeArg && screenModeArg !== "termvision" ? "plain" : "termvision",
+		theme: themeArg === "light" ? "light" : "dark"
+	};
+}
+function readCassetteLaunchArgs(cassettePath) {
 	try {
-		const parsed = agentRunRecordSchema.parse(input);
-		return {
-			...parsed,
-			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-run.schema.json",
-			spec: parsed.spec ? normalizeAgentFlowSpec(parsed.spec) : void 0
-		};
-	} catch (error) {
-		if (error instanceof z.ZodError) throw new Error(`invalid agent run record: ${formatZodIssues(error)}`);
-		throw error;
+		return normalizeStringArray(JSON.parse(readFileSync(cassettePath, "utf8")).spec?.launch?.args);
+	} catch {
+		return [];
 	}
 }
-function formatAgentArgv(argv) {
-	return formatArgv(argv);
+function readFlowLaunchArgs(flowPath) {
+	try {
+		return normalizeStringArray(JSON.parse(readFileSync(flowPath, "utf8")).launch?.args);
+	} catch {
+		return [];
+	}
 }
-function sameArgv(left, right) {
-	return left.length === right.length && left.every((value, index) => value === right[index]);
+function normalizeStringArray(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
-function isReplayArgv(argv) {
-	return argv.length >= 4 && argv[0] === "ptywright" && argv[1] === "agent" && argv[2] === "replay";
+function readFlagValueFromArgSets(argSets, flag) {
+	for (const args of argSets) {
+		const value = readFlagValue(args, flag);
+		if (value !== void 0) return value;
+	}
 }
-function readAgentRunRecordPath(path) {
-	return normalizeAgentRunRecord(JSON.parse(readFileSync(path, "utf8")));
+function readFlagValue(args, flag) {
+	const index = args.indexOf(flag);
+	return index >= 0 ? args[index + 1] : void 0;
 }
-function writeAgentRunRecordPath(path, record) {
-	const normalized = normalizeAgentRunRecord({
-		...record,
-		$schema: record.$schema ?? "https://ptywright.local/schemas/ptywright-agent-run.schema.json"
+function parsePositiveNumber(value) {
+	if (value === void 0) return void 0;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+//#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
 	});
-	writeFileSync(path, JSON.stringify(normalized, null, 2) + "\n", "utf8");
 }
-function isAgentRunRecordLike(input) {
-	if (typeof input !== "object" || input === null) return false;
-	const candidate = input;
-	return candidate.version === 1 && ("cassettePath" in candidate || "flowPath" in candidate || "spec" in candidate);
+//#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 formatZodIssues(error) {
-	return error.issues.map((issue) => {
-		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
-	}).join("; ");
+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;
 }
-//#endregion
-//#region src/agent/report.ts
-function writeAgentReport(path, result) {
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, renderAgentReportHtml(result), "utf8");
+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;
 }
-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";
+//#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">
+<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(`${result.name} terminal-agent report`)}</title>
-    <style>
-      :root {
+    <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
+function writeArtifactViewerPages(result) {
+	const viewportsByName = new Map(result.viewports.map((viewport) => [viewport.name, viewport]));
+	const viewOptions = resolveReportViewOptions(result);
+	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();
+	if (aittyAssets) for (const { artifact, content } of readableArtifacts) {
+		if (artifact.kind !== "dom") continue;
+		const viewport = viewportsByName.get(artifact.viewport);
+		const domPreviewPath = artifactDomPreviewPath(artifact);
+		mkdirSync(dirname(domPreviewPath), { recursive: true });
+		writeFileSync(domPreviewPath, renderDomPreviewDocument(content, viewport, viewOptions, resolveAittyPreviewAssets(domPreviewPath, aittyAssets, result.artifactsDir)), "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: 14px;
+      }
+      .artifact {
+        display: grid;
+        gap: 12px;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 12px;
+        background: var(--panel);
+      }
+      .artifact-summary {
+        display: grid;
+        grid-template-columns: auto minmax(0, 1fr) minmax(96px, auto);
+        gap: 14px;
+        align-items: start;
+      }
+      .artifact-meta {
+        display: grid;
+        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 {
+        color: var(--muted);
+        overflow-wrap: anywhere;
+      }
+      .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);
@@ -1085,10 +1877,16 @@ function renderAgentReportHtml(result) {
         font-size: 13px;
       }
       .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)"};
         font-weight: 700;
       }
+      .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);
+      }
       .panel {
         display: grid;
         gap: 16px;
@@ -1097,73 +1895,23 @@ function renderAgentReportHtml(result) {
         background: var(--panel);
         padding: 18px;
       }
-      .summary {
-        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;
-      }
-      .artifacts {
-        display: grid;
-        gap: 10px;
-      }
-      .artifact {
-        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);
-      }
-      .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;
-        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);
-      }
-      .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;
       }
@@ -1176,6 +1924,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;
@@ -1184,20 +1936,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>
@@ -1206,7 +2001,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}
@@ -1225,9 +2020,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",
@@ -1241,84 +2036,266 @@ 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
+function writeAgentReport(path, result) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeArtifactViewerPages(result);
+	writeFileSync(path, renderAgentReportHtml(result), "utf8");
+}
+//#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
+	};
 }
-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>`;
+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")) return {
-		spec: normalizeAgentFlowSpec(JSON.parse(readFileSync(resolved, "utf8"))),
-		path: resolved
+//#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 mod = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
+	const session = await launchBrowserSessionFromCommand(buildCommandLaunchCommand(launch, options));
 	return {
-		spec: normalizeAgentFlowSpec(mod.default ?? mod.spec),
-		path: resolved
+		mode,
+		url: session.url,
+		session
 	};
 }
-//#endregion
-//#region src/agent/runner.ts
-async function runAgentSpecPath(specPath, options = {}) {
-	return runAgentSpec((await loadAgentSpec(specPath)).spec, 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);
-	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);
+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 = normalizeAgentFlowSpec(input);
+	const spec = normalizeAgentFlowSpecWithConfig(input, options.replayCassette ? void 0 : options.config);
 	const name = sanitizeArtifactName(spec.name ?? "agent-flow");
 	const artifactsDir = resolve(rootDir, options.artifactsDir ?? spec.artifactsDir ?? join(".tmp", "agent", name));
 	const snapshotDir = resolve(rootDir, spec.snapshotDir ?? join("snapshots", name));
@@ -1336,161 +2313,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,
-		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 = {
+		rootDir,
 		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();
-	}
+		name,
+		artifactsDir,
+		snapshotDir,
+		reportPath,
+		recordPath,
+		flowPath,
+		cassettePath,
+		updateSnapshots,
+		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 {
@@ -1501,85 +2368,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",
@@ -1587,7 +2464,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, {
@@ -1626,7 +2504,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);
@@ -1703,172 +2584,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;
+	}
+	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;
 	}
-	throw new Error(`timed out waiting for stable terminal DOM`);
+	if (step.type === "mark") return;
 }
-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 ?? "";
+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()
 	});
-	if (text === null) throw new Error("terminal root is not attached");
-	return text;
 }
-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);
+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);
+		writeAgentReport(reportPath, result);
+		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 { isAgentManifestLike as C, writeAgentManifestPath as E, agentManifestPath as S, validateAgentManifestFiles as T, readAgentCassettePath as _, runAgentSpecPath as a, launchAgentBrowser as b, agentRunModeSchema as c, readAgentRunRecordPath as d, writeAgentRunRecordPath as f, isAgentCassetteLike 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, normalizeAgentFlowSpec as v, readAgentManifestPath as w, AGENT_MANIFEST_FILE_NAME as x, sanitizeArtifactName 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 };