ptywright 0.1.1 → 0.2.0

package/dist/cli-DIUx2w6X.mjs

@@ -0,0 +1,3587 @@
+import { c as createDefaultPtyAdapter, l as resolvePtyBackend } from "./runner-zApMYWZx.mjs";
+import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-VHuEWWj_.mjs";
+import { C as isAgentManifestLike, E as writeAgentManifestPath, S as agentManifestPath, T as validateAgentManifestFiles, _ as normalizeAgentFlowSpec, a as runAgentSpecPath, b as launchAittyBrowserSession, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as readAgentCassettePath, h as isAgentCassetteLike, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as sanitizeArtifactName, w as readAgentManifestPath, x as AGENT_MANIFEST_FILE_NAME, y as launchAgentBrowser } from "./runner-DzZlFrt1.mjs";
+import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-Cpkh_O9B.mjs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { Buffer } from "node:buffer";
+//#region src/agent/check_summary.ts
+const AGENT_CHECK_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-check.schema.json";
+const countSummarySchema$1 = z.object({
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative()
+}).strict();
+const agentCommandSchema$2 = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentCheckCommandsSchema = z.object({
+	check: agentCommandSchema$2,
+	updateSnapshots: agentCommandSchema$2,
+	rerun: agentCommandSchema$2
+}).strict();
+const agentCheckJsonSummarySchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	ok: z.boolean(),
+	cassetteDir: z.string().min(1),
+	artifactsRoot: z.string().min(1),
+	summaryPath: z.string().min(1),
+	commands: agentCheckCommandsSchema,
+	inputs: countSummarySchema$1,
+	replay: z.object({
+		ok: z.boolean(),
+		totalCount: z.number().int().nonnegative(),
+		failureCount: z.number().int().nonnegative(),
+		reportPath: z.string(),
+		summaryPath: z.string()
+	}).strict(),
+	outputs: countSummarySchema$1,
+	failures: z.array(z.object({
+		stage: z.enum([
+			"input",
+			"replay",
+			"output"
+		]),
+		filePath: z.string().min(1),
+		kind: z.string().optional(),
+		errors: z.array(z.string())
+	}).strict())
+}).strict().superRefine((summary, ctx) => {
+	const failureCount = summary.inputs.failureCount + summary.replay.failureCount + summary.outputs.failureCount;
+	if (summary.ok !== (failureCount === 0)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["ok"],
+		message: "ok must be true only when all stages have zero failures"
+	});
+	if (summary.failures.length !== failureCount) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["failures"],
+		message: "failures.length must equal the sum of stage failure counts"
+	});
+	const expected = defaultAgentCheckCommands(summary);
+	if (!sameArgv$3(summary.commands.check.argv, expected.check.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"check",
+			"argv"
+		],
+		message: "check argv must match cassetteDir and artifactsRoot"
+	});
+	if (!sameArgv$3(summary.commands.updateSnapshots.argv, expected.updateSnapshots.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"updateSnapshots",
+			"argv"
+		],
+		message: "updateSnapshots argv must match cassetteDir and artifactsRoot"
+	});
+	if (!sameArgv$3(summary.commands.rerun.argv, expected.rerun.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"rerun",
+			"argv"
+		],
+		message: "rerun argv must match summaryPath"
+	});
+});
+function normalizeAgentCheckJsonSummary(input) {
+	try {
+		const parsed = agentCheckJsonSummarySchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-check.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent check summary: ${formatZodIssues$2(error)}`);
+		throw error;
+	}
+}
+function readAgentCheckSummaryPath(path) {
+	return normalizeAgentCheckJsonSummary(JSON.parse(readFileSync(path, "utf8")));
+}
+function writeAgentCheckSummaryPath(path, summary) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(normalizeAgentCheckJsonSummary(summary), null, 2) + "\n", "utf8");
+}
+function defaultAgentCheckCommands(summary) {
+	const check = [
+		"ptywright",
+		"agent",
+		"check",
+		summary.cassetteDir,
+		"--artifacts-root",
+		summary.artifactsRoot
+	];
+	return {
+		check: { argv: check },
+		updateSnapshots: { argv: [...check, "--update-snapshots"] },
+		rerun: { argv: [
+			"ptywright",
+			"agent",
+			"rerun",
+			summary.summaryPath
+		] }
+	};
+}
+function sameArgv$3(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function formatZodIssues$2(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/agent/summary.ts
+const AGENT_REPLAY_SUMMARY_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-replay-summary.schema.json";
+const agentCommandSchema$1 = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentReplaySummaryCommandsSchema = z.object({
+	replayAll: agentCommandSchema$1,
+	updateSnapshots: agentCommandSchema$1,
+	rerun: agentCommandSchema$1
+}).strict();
+const agentReplayFailedArtifactSchema = 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(),
+	error: z.string().optional()
+}).strict();
+const agentReplaySummaryEntrySchema = z.object({
+	filePath: z.string().min(1),
+	durationMs: z.number().int().nonnegative(),
+	ok: z.boolean(),
+	mode: agentRunModeSchema,
+	frames: z.number().int().nonnegative(),
+	reportPath: z.string().min(1),
+	recordPath: z.string().min(1),
+	cassettePath: z.string().min(1),
+	failedArtifacts: z.array(agentReplayFailedArtifactSchema),
+	errors: z.array(z.string())
+}).strict();
+const agentReplaySummarySchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	ok: z.boolean(),
+	dir: z.string().min(1),
+	suiteDir: z.string().min(1),
+	durationMs: z.number().int().nonnegative(),
+	reportPath: z.string().min(1),
+	summaryPath: z.string().min(1),
+	commands: agentReplaySummaryCommandsSchema,
+	updateSnapshots: z.boolean(),
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative(),
+	entries: z.array(agentReplaySummaryEntrySchema)
+}).strict().superRefine((summary, ctx) => {
+	if (summary.totalCount !== summary.entries.length) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["totalCount"],
+		message: "totalCount must equal entries.length"
+	});
+	const failureCount = summary.entries.filter((entry) => !entry.ok).length;
+	if (summary.failureCount !== failureCount) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["failureCount"],
+		message: "failureCount must equal failed entries"
+	});
+	if (summary.ok !== (failureCount === 0)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["ok"],
+		message: "ok must be true only when failureCount is zero"
+	});
+	const expected = defaultAgentReplaySummaryCommands(summary);
+	if (!sameArgv$2(summary.commands.replayAll.argv, expected.replayAll.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"replayAll",
+			"argv"
+		],
+		message: "replayAll argv must match dir and suiteDir"
+	});
+	if (!sameArgv$2(summary.commands.updateSnapshots.argv, expected.updateSnapshots.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"updateSnapshots",
+			"argv"
+		],
+		message: "updateSnapshots argv must match dir and suiteDir"
+	});
+	if (!sameArgv$2(summary.commands.rerun.argv, expected.rerun.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"rerun",
+			"argv"
+		],
+		message: "rerun argv must match summaryPath"
+	});
+});
+function normalizeAgentReplaySummary(input) {
+	try {
+		const parsed = agentReplaySummarySchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-replay-summary.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent replay summary: ${formatZodIssues$1(error)}`);
+		throw error;
+	}
+}
+function readAgentReplaySummaryPath(path) {
+	return normalizeAgentReplaySummary(JSON.parse(readFileSync(path, "utf8")));
+}
+function writeAgentReplaySummaryPath(path, summary) {
+	const normalized = normalizeAgentReplaySummary({
+		...summary,
+		$schema: summary.$schema ?? "https://ptywright.local/schemas/ptywright-agent-replay-summary.schema.json"
+	});
+	writeFileSync(path, JSON.stringify(normalized, null, 2) + "\n", "utf8");
+}
+function defaultAgentReplaySummaryCommands(summary) {
+	const replayAll = [
+		"ptywright",
+		"agent",
+		"replay-all",
+		summary.dir,
+		"--artifacts-root",
+		summary.suiteDir
+	];
+	return {
+		replayAll: { argv: replayAll },
+		updateSnapshots: { argv: [...replayAll, "--update-snapshots"] },
+		rerun: { argv: [
+			"ptywright",
+			"agent",
+			"rerun",
+			summary.summaryPath
+		] }
+	};
+}
+function sameArgv$2(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function formatZodIssues$1(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/agent/replay_all.ts
+async function replayAllAgentRecords(options = {}) {
+	const dir = resolve(options.dir?.trim() ? options.dir.trim() : join(".tmp", "agent"));
+	const suiteDir = resolve(options.artifactsRoot?.trim() ? options.artifactsRoot.trim() : join(".tmp", "agent-replay-all"));
+	const filePaths = listAgentReplayFiles(dir, { artifactsRoot: suiteDir });
+	const entries = [];
+	const startedAt = Date.now();
+	const updateSnapshots = options.updateSnapshots ?? false;
+	for (const filePath of filePaths) {
+		const artifactsDir = join(suiteDir, "tests", safeArtifactsDirName(relative(dir, filePath)));
+		const entryStartedAt = Date.now();
+		const result = await replayRecordEntry(filePath, artifactsDir, {
+			headless: options.headless ?? true,
+			updateSnapshots
+		});
+		entries.push({
+			filePath,
+			durationMs: Date.now() - entryStartedAt,
+			result
+		});
+	}
+	const durationMs = Date.now() - startedAt;
+	const reportPath = join(suiteDir, "index.html");
+	const summaryPath = join(suiteDir, "agent-replay.summary.json");
+	writeReplayAllSummary(summaryPath, {
+		ok: entries.every((entry) => entry.result.ok),
+		dir,
+		suiteDir,
+		durationMs,
+		reportPath,
+		summaryPath,
+		updateSnapshots,
+		entries
+	});
+	writeReplayAllReport(reportPath, {
+		dir,
+		durationMs,
+		updateSnapshots,
+		entries,
+		summaryPath
+	});
+	writeReplayAllManifest({
+		ok: entries.every((entry) => entry.result.ok),
+		dir,
+		suiteDir,
+		reportPath,
+		summaryPath,
+		updateSnapshots,
+		entries
+	});
+	return {
+		ok: entries.every((entry) => entry.result.ok),
+		dir,
+		suiteDir,
+		durationMs,
+		reportPath,
+		summaryPath,
+		updateSnapshots,
+		entries
+	};
+}
+function writeReplayAllManifest(result) {
+	const summary = formatAgentReplaySummary({
+		ok: result.ok,
+		dir: result.dir,
+		suiteDir: result.suiteDir,
+		durationMs: 0,
+		reportPath: result.reportPath,
+		summaryPath: result.summaryPath,
+		updateSnapshots: result.updateSnapshots,
+		entries: result.entries
+	});
+	writeAgentManifestPath(agentManifestPath(result.suiteDir), {
+		kind: "replay-suite",
+		ok: result.ok,
+		rootDir: result.suiteDir,
+		primaryPath: result.summaryPath,
+		commands: summary.commands,
+		validation: {
+			ok: result.ok,
+			stages: [{
+				name: "replay",
+				ok: result.ok,
+				totalCount: result.entries.length,
+				failureCount: result.entries.filter((entry) => !entry.result.ok).length
+			}]
+		},
+		files: [
+			{
+				path: result.summaryPath,
+				kind: "replay-summary",
+				role: "summary",
+				ok: result.ok
+			},
+			{
+				path: result.reportPath,
+				kind: "report",
+				role: "report",
+				ok: result.ok
+			},
+			...result.entries.flatMap((entry) => [
+				{
+					path: entry.result.recordPath,
+					kind: "run-record",
+					role: "record",
+					ok: entry.result.ok
+				},
+				{
+					path: entry.result.reportPath,
+					kind: "report",
+					role: "entry-report",
+					ok: entry.result.ok
+				},
+				...entry.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
+				}])
+			])
+		]
+	});
+}
+async function replayRecordEntry(filePath, artifactsDir, options) {
+	try {
+		return await replayAgentRecordPath(filePath, {
+			artifactsDir,
+			headless: options.headless,
+			updateSnapshots: options.updateSnapshots
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const startedAt = Date.now();
+		mkdirSync(artifactsDir, { recursive: true });
+		const replayArgv = [
+			"ptywright",
+			"agent",
+			"replay",
+			filePath
+		];
+		const result = {
+			ok: false,
+			name: safeArtifactsDirName(filePath),
+			mode: "replay",
+			agentFlavor: "generic",
+			startedAt,
+			durationMs: 0,
+			artifactsDir,
+			snapshotDir: join(artifactsDir, "snapshots"),
+			reportPath: join(artifactsDir, "index.html"),
+			recordPath: join(artifactsDir, "failed.agent-run.json"),
+			flowPath: "",
+			cassettePath: filePath,
+			replayCommand: formatAgentArgv(replayArgv),
+			commands: {
+				replay: { argv: replayArgv },
+				updateSnapshots: { argv: [...replayArgv, "--update-snapshots"] }
+			},
+			viewports: [],
+			cassetteFrameCount: 0,
+			steps: [],
+			artifacts: [],
+			errors: [message]
+		};
+		writeAgentRunRecordPath(result.recordPath, {
+			$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,
+			artifactsDir: result.artifactsDir,
+			snapshotDir: result.snapshotDir,
+			reportPath: result.reportPath,
+			cassettePath: result.cassettePath,
+			cassetteFrameCount: result.cassetteFrameCount,
+			replayCommand: result.replayCommand,
+			commands: result.commands,
+			steps: result.steps,
+			artifacts: result.artifacts,
+			errors: result.errors
+		});
+		writeFileSync(result.reportPath, renderFailedEntryReport(result), "utf8");
+		return result;
+	}
+}
+function renderFailedEntryReport(result) {
+	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)} failed replay</title>
+    <style>
+      :root { color-scheme: light; font-family: ui-sans-serif, system-ui, sans-serif; }
+      body { margin: 0; padding: 32px; background: oklch(97.5% 0.008 210); color: oklch(19% 0.018 230); }
+      main { display: grid; gap: 16px; max-width: 960px; }
+      pre { overflow: auto; border-radius: 8px; background: oklch(20% 0.015 230); color: oklch(92% 0.012 230); padding: 14px; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>${escapeHtml(result.name)}</h1>
+      <p>Replay failed before the agent runner could start.</p>
+      <pre>${escapeHtml(result.errors.join("\n"))}</pre>
+    </main>
+  </body>
+</html>`;
+}
+function listAgentReplayFiles(dir, options = {}) {
+	const resolvedDir = resolve(process.cwd(), dir);
+	const suiteDir = options.artifactsRoot?.trim() ? resolve(process.cwd(), options.artifactsRoot) : null;
+	return collectReplayFiles(resolvedDir, { skipGeneratedOutputDirs: suiteDir ? isSubpath(resolvedDir, suiteDir) : false });
+}
+function collectReplayFiles(dir, options = {}) {
+	const out = [];
+	const entries = readdirSync(dir);
+	const hasRunRecord = entries.some((entry) => entry.endsWith(".agent-run.json"));
+	for (const entry of entries) {
+		const abs = join(dir, entry);
+		if (statSync(abs).isDirectory()) {
+			if (entry === "replay") continue;
+			if (options.skipGeneratedOutputDirs && isGeneratedReplayOutputDir(abs)) continue;
+			out.push(...collectReplayFiles(abs, options));
+			continue;
+		}
+		if (hasRunRecord && entry.endsWith(".cassette.json")) continue;
+		if (entry.endsWith(".cassette.json") || entry.endsWith(".agent-run.json")) out.push(abs);
+	}
+	return out.sort((a, b) => a.localeCompare(b));
+}
+function isGeneratedReplayOutputDir(dir) {
+	const manifestPath = join(dir, AGENT_MANIFEST_FILE_NAME);
+	try {
+		if (samePath$1(readAgentManifestPath(manifestPath).rootDir, dir)) return true;
+	} catch {}
+	for (const entry of readdirSync(dir)) {
+		if (!entry.endsWith(".agent-run.json")) continue;
+		try {
+			const parsed = JSON.parse(readFileSync(join(dir, entry), "utf8"));
+			if (typeof parsed.artifactsDir === "string" && samePath$1(parsed.artifactsDir, dir)) return true;
+		} catch {}
+	}
+	return false;
+}
+function isSubpath(path, maybeParent) {
+	const child = resolve(process.cwd(), path);
+	const rel = relative(resolve(process.cwd(), maybeParent), child);
+	return rel === "" || !!rel && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function samePath$1(left, right) {
+	return resolve(process.cwd(), left) === resolve(process.cwd(), right);
+}
+function formatAgentReplaySummary(result) {
+	const entries = result.entries.map((entry) => ({
+		filePath: entry.filePath,
+		durationMs: entry.durationMs,
+		ok: entry.result.ok,
+		mode: entry.result.mode,
+		frames: entry.result.cassetteFrameCount,
+		reportPath: entry.result.reportPath,
+		recordPath: entry.result.recordPath,
+		cassettePath: entry.result.replaySourceCassettePath ?? entry.result.cassettePath,
+		failedArtifacts: entry.result.artifacts.filter((artifact) => !artifact.ok).map((artifact) => ({
+			name: artifact.name,
+			viewport: artifact.viewport,
+			kind: artifact.kind,
+			path: artifact.path,
+			baselinePath: artifact.baselinePath,
+			diffPath: artifact.diffPath,
+			error: artifact.error
+		})),
+		errors: entry.result.errors
+	}));
+	const failureCount = entries.filter((entry) => !entry.ok).length;
+	return normalizeAgentReplaySummary({
+		$schema: AGENT_REPLAY_SUMMARY_SCHEMA_URL,
+		version: 1,
+		ok: result.ok,
+		dir: result.dir,
+		suiteDir: result.suiteDir,
+		durationMs: result.durationMs,
+		reportPath: result.reportPath,
+		summaryPath: result.summaryPath,
+		commands: {
+			replayAll: { argv: [
+				"ptywright",
+				"agent",
+				"replay-all",
+				result.dir,
+				"--artifacts-root",
+				result.suiteDir
+			] },
+			updateSnapshots: { argv: [
+				"ptywright",
+				"agent",
+				"replay-all",
+				result.dir,
+				"--artifacts-root",
+				result.suiteDir,
+				"--update-snapshots"
+			] },
+			rerun: { argv: [
+				"ptywright",
+				"agent",
+				"rerun",
+				result.summaryPath
+			] }
+		},
+		updateSnapshots: result.updateSnapshots,
+		totalCount: entries.length,
+		failureCount,
+		entries
+	});
+}
+function writeReplayAllSummary(path, result) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeAgentReplaySummaryPath(path, formatAgentReplaySummary(result));
+}
+function writeReplayAllReport(path, args) {
+	mkdirSync(dirname(path), { recursive: true });
+	const rows = args.entries.map((entry) => renderEntry(entry, path)).join("\n");
+	const ok = args.entries.every((entry) => entry.result.ok);
+	writeFileSync(path, `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>ptywright agent replay report</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: oklch(97.5% 0.008 210);
+        --ink: oklch(19% 0.018 230);
+        --muted: oklch(48% 0.02 230);
+        --line: oklch(86% 0.018 230);
+        --panel: oklch(99% 0.006 210);
+        --good: oklch(55% 0.15 155);
+        --bad: oklch(58% 0.19 25);
+        --focus: oklch(55% 0.14 235);
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+      * { box-sizing: border-box; }
+      body { margin: 0; background: var(--bg); color: var(--ink); }
+      main {
+        display: grid;
+        gap: 22px;
+        width: min(1180px, calc(100vw - 32px));
+        margin: 0 auto;
+        padding: 32px 0 48px;
+      }
+      header {
+        display: grid;
+        gap: 10px;
+        border-bottom: 1px solid var(--line);
+        padding-bottom: 20px;
+      }
+      h1 { margin: 0; font-size: 28px; line-height: 1.15; letter-spacing: 0; }
+      .meta { display: flex; flex-wrap: wrap; gap: 8px; }
+      .pill {
+        display: inline-flex;
+        min-height: 32px;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 999px;
+        padding: 0 12px;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .pill.pass { color: var(--good); border-color: color-mix(in oklch, var(--good) 42%, var(--line)); }
+      .pill.fail { color: var(--bad); border-color: color-mix(in oklch, var(--bad) 42%, var(--line)); }
+      .entries { display: grid; gap: 10px; }
+      .entry {
+        display: grid;
+        grid-template-columns: 92px minmax(0, 1fr) auto;
+        gap: 14px;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: var(--panel);
+        padding: 12px;
+      }
+      .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.pass { background: color-mix(in oklch, var(--good) 12%, var(--panel)); color: var(--good); }
+      .badge.fail { background: color-mix(in oklch, var(--bad) 12%, var(--panel)); color: var(--bad); }
+      a { color: var(--focus); font-weight: 700; text-decoration: none; }
+      code { color: var(--muted); overflow-wrap: anywhere; }
+      .commands {
+        display: grid;
+        gap: 4px;
+        margin-top: 8px;
+      }
+      .commands code {
+        display: block;
+      }
+      @media (max-width: 720px) {
+        main { width: min(100vw - 20px, 1180px); padding-top: 18px; }
+        .entry { grid-template-columns: 1fr; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>ptywright agent replay report</h1>
+        <div class="meta">
+          <span class="pill ${ok ? "pass" : "fail"}">${ok ? "passed" : "failed"}</span>
+          <span class="pill">${args.entries.length} entries</span>
+          <span class="pill">${args.updateSnapshots ? "update snapshots" : "compare snapshots"}</span>
+          <span class="pill">${args.durationMs}ms</span>
+          <span class="pill">${escapeHtml(args.dir)}</span>
+          <a class="pill" href="${escapeAttribute(relativeHref(path, args.summaryPath))}">agent-replay.summary.json</a>
+        </div>
+      </header>
+      <section class="entries">
+        ${rows || "<p>No replay artifacts were found.</p>"}
+      </section>
+    </main>
+  </body>
+</html>`, "utf8");
+}
+function renderEntry(entry, reportPath) {
+	const state = entry.result.ok ? "pass" : "fail";
+	const source = entry.result.replaySourceCassettePath ?? entry.result.cassettePath;
+	const failedArtifacts = entry.result.artifacts.filter((artifact) => !artifact.ok);
+	return `<article class="entry">
+    <span class="badge ${state}">${state}</span>
+    <div>
+      <a href="${escapeAttribute(relativeHref(reportPath, entry.result.reportPath))}">${escapeHtml(entry.result.name)}</a>
+      <div><code>${escapeHtml(entry.filePath)}</code></div>
+      <div><code>${escapeHtml(source)}</code></div>
+      <div class="commands">
+        <code>replay ${escapeHtml(formatAgentArgv(entry.result.commands.replay.argv))}</code>
+        <code>update ${escapeHtml(formatAgentArgv(entry.result.commands.updateSnapshots.argv))}</code>
+        <code>commands ${escapeHtml(formatAgentArgv([
+		"ptywright",
+		"agent",
+		"commands",
+		entry.result.recordPath,
+		"--json"
+	]))}</code>
+      </div>
+      ${failedArtifacts.map((artifact) => renderFailedArtifact(artifact, reportPath)).join("")}
+      ${entry.result.errors.map((error) => `<div><code>${escapeHtml(error)}</code></div>`).join("")}
+    </div>
+    <code>${entry.result.mode} / ${entry.result.cassetteFrameCount} frames / ${entry.durationMs}ms</code>
+  </article>`;
+}
+function renderFailedArtifact(artifact, reportPath) {
+	const diffLink = artifact.diffPath ? `<a href="${escapeAttribute(relativeHref(reportPath, artifact.diffPath))}">diff</a>` : "";
+	return `<div>
+    ${`<a href="${escapeAttribute(relativeHref(reportPath, artifact.path))}">${escapeHtml(artifact.kind)}</a>`}${diffLink ? ` ${diffLink}` : ""}
+    <code>${escapeHtml(artifact.viewport)} / ${escapeHtml(artifact.name)}${artifact.error ? ` / ${artifact.error}` : ""}</code>
+  </div>`;
+}
+function safeArtifactsDirName(relPath) {
+	return relPath.replace(/[/\\]/g, "__");
+}
+function relativeHref(fromPath, targetPath) {
+	const href = relative(dirname(fromPath), targetPath);
+	return href.startsWith(".") ? href : `./${href}`;
+}
+function escapeHtml(input) {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeAttribute(input) {
+	return escapeHtml(input).replace(/'/g, "&#39;");
+}
+//#endregion
+//#region src/agent/promote_summary.ts
+const AGENT_PROMOTE_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-promote.schema.json";
+const countSummarySchema = z.object({
+	ok: z.boolean(),
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative()
+}).strict();
+const agentCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const agentPromoteCommandsSchema = z.object({
+	promote: agentCommandSchema,
+	check: agentCommandSchema,
+	updateSnapshots: agentCommandSchema,
+	rerun: agentCommandSchema
+}).strict();
+const agentPromoteSummarySchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	ok: z.boolean(),
+	sourcePath: z.string().min(1),
+	cassetteDir: z.string().min(1),
+	targetDir: z.string().min(1),
+	targetCassettePath: z.string().min(1),
+	snapshotDir: z.string().min(1),
+	artifactsRoot: z.string().min(1),
+	summaryPath: z.string().min(1),
+	updateSnapshots: z.boolean(),
+	commands: agentPromoteCommandsSchema,
+	validation: countSummarySchema,
+	replay: z.object({
+		ok: z.boolean(),
+		totalCount: z.number().int().nonnegative(),
+		failureCount: z.number().int().nonnegative(),
+		reportPath: z.string(),
+		summaryPath: z.string()
+	}).strict(),
+	failures: z.array(z.object({
+		stage: z.enum(["validation", "replay"]),
+		filePath: z.string().min(1),
+		kind: z.string().optional(),
+		errors: z.array(z.string())
+	}).strict())
+}).strict().superRefine((summary, ctx) => {
+	const failureCount = summary.validation.failureCount + summary.replay.failureCount;
+	if (summary.ok !== (summary.validation.ok && summary.replay.ok && failureCount === 0)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["ok"],
+		message: "ok must be true only when validation and replay have zero failures"
+	});
+	if (summary.failures.length !== failureCount) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["failures"],
+		message: "failures.length must equal validation plus replay failure counts"
+	});
+	const expected = defaultAgentPromoteCommands(summary);
+	if (!sameArgv$1(summary.commands.promote.argv, expected.promote.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"promote",
+			"argv"
+		],
+		message: "promote argv must match sourcePath, cassetteDir, snapshotDir, and artifactsRoot"
+	});
+	if (!sameArgv$1(summary.commands.check.argv, expected.check.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"check",
+			"argv"
+		],
+		message: "check argv must match cassetteDir and artifactsRoot"
+	});
+	if (!sameArgv$1(summary.commands.updateSnapshots.argv, expected.updateSnapshots.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"updateSnapshots",
+			"argv"
+		],
+		message: "updateSnapshots argv must match cassetteDir and artifactsRoot"
+	});
+	if (!sameArgv$1(summary.commands.rerun.argv, expected.rerun.argv)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"rerun",
+			"argv"
+		],
+		message: "rerun argv must match summaryPath"
+	});
+});
+function normalizeAgentPromoteSummary(input) {
+	try {
+		const parsed = agentPromoteSummarySchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-agent-promote.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid agent promote summary: ${formatZodIssues(error)}`);
+		throw error;
+	}
+}
+function readAgentPromoteSummaryPath(path) {
+	return normalizeAgentPromoteSummary(JSON.parse(readFileSync(path, "utf8")));
+}
+function writeAgentPromoteSummaryPath(path, summary) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(normalizeAgentPromoteSummary(summary), null, 2) + "\n", "utf8");
+}
+function defaultAgentPromoteCommands(summary) {
+	const promote = [
+		"ptywright",
+		"agent",
+		"promote",
+		summary.sourcePath,
+		"--cassette-dir",
+		summary.cassetteDir,
+		"--snapshot-dir",
+		summary.snapshotDir,
+		"--artifacts-root",
+		summary.artifactsRoot
+	];
+	if (summary.updateSnapshots) promote.push("--update-snapshots");
+	const check = [
+		"ptywright",
+		"agent",
+		"check",
+		summary.cassetteDir,
+		"--artifacts-root",
+		summary.artifactsRoot
+	];
+	return {
+		promote: { argv: promote },
+		check: { argv: check },
+		updateSnapshots: { argv: [...check, "--update-snapshots"] },
+		rerun: { argv: [
+			"ptywright",
+			"agent",
+			"rerun",
+			summary.summaryPath
+		] }
+	};
+}
+function sameArgv$1(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function formatZodIssues(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/agent/commands.ts
+async function readAgentArtifactCommandsPath(path) {
+	const resolved = resolveAgentArtifactCommandsPath(path);
+	const name = basename(resolved);
+	if (name.endsWith(".agent-run.json")) {
+		const bundleCommands = readPrimaryManifestCommands(resolved, "run-record");
+		if (bundleCommands) return bundleCommands;
+		return createArtifactCommands(resolved, "run-record", readAgentRunRecordPath(resolved).commands);
+	}
+	if (name === "agent-replay.summary.json") {
+		const bundleCommands = readPrimaryManifestCommands(resolved, "replay-summary");
+		if (bundleCommands) return bundleCommands;
+		return createArtifactCommands(resolved, "replay-summary", readAgentReplaySummaryPath(resolved).commands);
+	}
+	if (name === "agent-promote.summary.json") {
+		const bundleCommands = readPrimaryManifestCommands(resolved, "promote-summary");
+		if (bundleCommands) return bundleCommands;
+		return createArtifactCommands(resolved, "promote-summary", readAgentPromoteSummaryPath(resolved).commands);
+	}
+	if (name === "agent-check.summary.json") {
+		const bundleCommands = readPrimaryManifestCommands(resolved, "check-summary");
+		if (bundleCommands) return bundleCommands;
+		return createArtifactCommands(resolved, "check-summary", readAgentCheckSummaryPath(resolved).commands);
+	}
+	if (name === "ptywright-agent.manifest.json") return createArtifactCommands(resolved, "manifest", relocateManifestCommands(readAgentManifestPath(resolved), resolved));
+	if (name.endsWith(".cassette.json")) {
+		readAgentCassettePath(resolved);
+		return createArtifactCommands(resolved, "cassette", replayCommands(path));
+	}
+	if (name.endsWith(".flow.json") || name.endsWith(".flow.ts")) {
+		await loadAgentSpec(resolved);
+		return createArtifactCommands(resolved, "flow", runCommands(path));
+	}
+	return inferJsonCommands(resolved, path);
+}
+function resolveAgentArtifactCommandsPath(path) {
+	const resolved = resolve(process.cwd(), path);
+	if (!statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) return resolved;
+	const manifestPath = join(resolved, AGENT_MANIFEST_FILE_NAME);
+	if (existsSync(manifestPath)) return manifestPath;
+	throw new Error(`agent artifact directory is missing ${AGENT_MANIFEST_FILE_NAME}: ${path}. Pass a supported artifact file, or a manifest bundle directory.`);
+}
+function readPrimaryManifestCommands(artifactPath, kind) {
+	const bundle = readMovedPrimaryManifest(artifactPath, kind);
+	if (!bundle) return null;
+	return createArtifactCommands(artifactPath, kind, relocateManifestCommands(bundle.manifest, bundle.manifestPath), { manifestPath: bundle.manifestPath });
+}
+function findMovedPrimaryManifestBundle(artifactPath, kind) {
+	const bundle = readMovedPrimaryManifest(resolve(process.cwd(), artifactPath), kind);
+	if (!bundle) return null;
+	const manifestDir = dirname(bundle.manifestPath);
+	return {
+		manifestPath: bundle.manifestPath,
+		artifactsRoot: portableCliPath(manifestDir),
+		replayInputDir: findManifestReplayInputDir(bundle.manifest, manifestDir)
+	};
+}
+function readMovedPrimaryManifest(artifactPath, kind) {
+	const manifestPath = join(dirname(artifactPath), AGENT_MANIFEST_FILE_NAME);
+	if (!existsSync(manifestPath)) return null;
+	let manifest;
+	try {
+		manifest = readAgentManifestPath(manifestPath);
+	} catch {
+		return null;
+	}
+	const primary = manifestPrimaryFile(manifest);
+	if (!primary || primary.kind !== kind) return null;
+	if (!samePath(isAbsolute(primary.path) ? primary.path : resolve(dirname(manifestPath), primary.path), artifactPath)) return null;
+	if (samePath(manifest.rootDir, dirname(manifestPath))) return null;
+	return {
+		manifest,
+		manifestPath
+	};
+}
+function formatAgentArtifactCommandLines(result) {
+	return [
+		`kind=${result.kind}`,
+		`path=${result.path}`,
+		result.manifestPath ? `manifest=${result.manifestPath}` : null,
+		...Object.entries(result.commands).map(([name, command]) => `${name}: ${formatAgentArgv(command.argv)}`)
+	].filter((line) => line !== null);
+}
+function selectAgentArtifactCommand(result, name) {
+	const command = result.commands[name];
+	if (!command) {
+		const available = Object.keys(result.commands).sort().join(", ");
+		throw new Error(`unknown agent artifact command: ${name}${available ? ` (available: ${available})` : ""}`);
+	}
+	return {
+		path: result.path,
+		kind: result.kind,
+		manifestPath: result.manifestPath,
+		cwd: result.cwd,
+		name,
+		command,
+		shell: result.shell[name] ?? formatAgentArgv(command.argv)
+	};
+}
+function validateAgentArtifactCommands(result) {
+	for (const [name, command] of Object.entries(result.commands)) validateAgentCommandArgv(command.argv, name);
+}
+function validateAgentManifestCommandTargets(manifest, manifestPath) {
+	const failures = [];
+	const primaryCommands = readManifestPrimaryCommands(manifest, manifestPath, failures);
+	if (primaryCommands) compareManifestCommandMaps(manifest.commands, primaryCommands, failures);
+	if (manifest.kind === "run") {
+		const recordPath = findManifestFileStoredPath(manifest, "run-record", "record");
+		if (!recordPath) failures.push("missing manifest run-record file for replay command");
+		else {
+			checkPathCommand(manifest, "replay", "replay", recordPath, manifestPath, failures);
+			checkPathCommand(manifest, "updateSnapshots", "replay", recordPath, manifestPath, failures);
+		}
+	}
+	if (manifest.kind === "check") {
+		const summaryPath = findManifestFileStoredPath(manifest, "check-summary", "summary");
+		if (!summaryPath) failures.push("missing manifest check-summary file for rerun command");
+		else checkPathCommand(manifest, "rerun", "rerun", summaryPath, manifestPath, failures);
+		checkRootFlag(manifest, "check", failures);
+		checkRootFlag(manifest, "updateSnapshots", failures);
+	}
+	if (manifest.kind === "replay-suite") {
+		const summaryPath = findManifestFileStoredPath(manifest, "replay-summary", "summary");
+		if (!summaryPath) failures.push("missing manifest replay-summary file for rerun command");
+		else checkPathCommand(manifest, "rerun", "rerun", summaryPath, manifestPath, failures);
+		checkRootFlag(manifest, "replayAll", failures);
+		checkRootFlag(manifest, "updateSnapshots", failures);
+	}
+	if (manifest.kind === "promote") {
+		const summaryPath = findManifestFileStoredPath(manifest, "promote-summary", "summary");
+		if (!summaryPath) failures.push("missing manifest promote-summary file for rerun command");
+		else checkPathCommand(manifest, "rerun", "rerun", summaryPath, manifestPath, failures);
+		checkRootFlag(manifest, "promote", failures);
+		checkRootFlag(manifest, "check", failures);
+		checkRootFlag(manifest, "updateSnapshots", failures);
+	}
+	if (failures.length > 0) throw new Error(`invalid agent manifest commands: ${failures.join("; ")}`);
+}
+function validateAgentCommandArgv(argv, name = "<unknown>") {
+	const [binary, group, subcommand] = argv;
+	if (binary !== "ptywright" || group !== "agent" || !isSupportedAgentSubcommand(subcommand)) throw new Error(`command ${name} argv must start with a supported ptywright agent command`);
+}
+function sameArgv(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function findManifestFileStoredPath(manifest, kind, role) {
+	return (manifest.files.find((candidate) => candidate.kind === kind && candidate.role === role) ?? manifest.files.find((candidate) => candidate.kind === kind))?.path ?? null;
+}
+function readManifestPrimaryCommands(manifest, manifestPath, failures) {
+	const primary = manifestPrimaryFile(manifest);
+	if (!primary) {
+		failures.push(`missing manifest primary artifact for ${manifest.kind}`);
+		return null;
+	}
+	const baseDir = manifestPath ? dirname(resolve(process.cwd(), manifestPath)) : resolve(process.cwd(), manifest.rootDir);
+	const filePath = isAbsolute(primary.path) ? primary.path : resolve(baseDir, primary.path);
+	try {
+		if (primary.kind === "run-record") return readAgentRunRecordPath(filePath).commands;
+		if (primary.kind === "check-summary") return readAgentCheckSummaryPath(filePath).commands;
+		if (primary.kind === "replay-summary") return readAgentReplaySummaryPath(filePath).commands;
+		if (primary.kind === "promote-summary") return readAgentPromoteSummaryPath(filePath).commands;
+	} catch (error) {
+		failures.push(`unable to read manifest primary artifact ${primary.path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return null;
+}
+function manifestPrimaryFile(manifest) {
+	if (manifest.kind === "run") return findManifestFile(manifest, "run-record", "record");
+	if (manifest.kind === "check") return findManifestFile(manifest, "check-summary", "summary");
+	if (manifest.kind === "replay-suite") return findManifestFile(manifest, "replay-summary", "summary");
+	return findManifestFile(manifest, "promote-summary", "summary");
+}
+function findManifestFile(manifest, kind, role) {
+	const file = manifest.files.find((candidate) => candidate.kind === kind && candidate.role === role) ?? manifest.files.find((candidate) => candidate.kind === kind);
+	if (!file) return null;
+	return {
+		path: file.path,
+		kind
+	};
+}
+function compareManifestCommandMaps(actual, expected, failures) {
+	const actualNames = Object.keys(actual).sort();
+	const expectedNames = Object.keys(expected).sort();
+	if (!sameStringList(actualNames, expectedNames)) failures.push(`manifest command names must match primary artifact commands: ${expectedNames.join(",")}`);
+	for (const [name, command] of Object.entries(expected)) {
+		const actualCommand = actual[name];
+		if (!actualCommand) continue;
+		if (!sameArgv(actualCommand.argv, command.argv)) failures.push(`command ${name} argv must match primary artifact ${formatAgentArgv(command.argv)}`);
+	}
+}
+function sameStringList(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function checkPathCommand(manifest, name, subcommand, expectedStoredPath, manifestPath, failures) {
+	const command = manifest.commands[name];
+	if (!command) return;
+	const [binary, group, actualSubcommand, targetPath] = command.argv;
+	if (binary !== "ptywright" || group !== "agent" || actualSubcommand !== subcommand) {
+		failures.push(`command ${name} argv must be ptywright agent ${subcommand}`);
+		return;
+	}
+	if (!targetPath || !sameManifestStoredPath(targetPath, manifest, expectedStoredPath, manifestPath)) failures.push(`command ${name} argv must target manifest file ${expectedStoredPath}`);
+}
+function checkRootFlag(manifest, name, failures) {
+	const command = manifest.commands[name];
+	if (!command) return;
+	const value = getArgvFlag(command.argv, "--artifacts-root");
+	if (!value || !samePath(value, manifest.rootDir)) failures.push(`command ${name} argv must target manifest rootDir`);
+}
+function manifestStoredPath(manifest, path) {
+	if (isAbsolute(path)) return path;
+	return resolve(process.cwd(), manifest.rootDir, path);
+}
+function sameManifestStoredPath(actual, manifest, expectedStoredPath, manifestPath) {
+	if (samePath(actual, manifestStoredPath(manifest, expectedStoredPath))) return true;
+	if (!manifestPath || isAbsolute(expectedStoredPath)) return false;
+	return samePath(actual, resolve(dirname(resolve(process.cwd(), manifestPath)), expectedStoredPath));
+}
+function samePath(left, right) {
+	return resolve(process.cwd(), left) === resolve(process.cwd(), right);
+}
+function getArgvFlag(argv, flag) {
+	const index = argv.indexOf(flag);
+	if (index < 0) return void 0;
+	return argv[index + 1];
+}
+async function inferJsonCommands(resolved, originalPath) {
+	const ext = extname(resolved);
+	if (ext !== ".json" && ext !== ".ts") throw new Error(`unsupported agent artifact for commands: ${originalPath}`);
+	if (ext === ".ts") {
+		await loadAgentSpec(resolved);
+		return createArtifactCommands(resolved, "flow", runCommands(originalPath));
+	}
+	const parsed = JSON.parse(readFileSync(resolved, "utf8"));
+	if (isAgentCassetteLike(parsed)) {
+		readAgentCassettePath(resolved);
+		return createArtifactCommands(resolved, "cassette", replayCommands(originalPath));
+	}
+	if (isAgentRunRecordLike(parsed)) return createArtifactCommands(resolved, "run-record", readAgentRunRecordPath(resolved).commands);
+	if (isReplaySummaryLike$2(parsed)) return createArtifactCommands(resolved, "replay-summary", readAgentReplaySummaryPath(resolved).commands);
+	if (isPromoteSummaryLike$2(parsed)) return createArtifactCommands(resolved, "promote-summary", readAgentPromoteSummaryPath(resolved).commands);
+	if (isCheckSummaryLike$2(parsed)) return createArtifactCommands(resolved, "check-summary", readAgentCheckSummaryPath(resolved).commands);
+	if (isAgentManifestLike(parsed)) return createArtifactCommands(resolved, "manifest", relocateManifestCommands(readAgentManifestPath(resolved), resolved));
+	if (isAgentFlowLike$1(parsed)) {
+		await loadAgentSpec(resolved);
+		return createArtifactCommands(resolved, "flow", runCommands(originalPath));
+	}
+	throw new Error(`unsupported agent artifact for commands: ${originalPath}`);
+}
+function createArtifactCommands(path, kind, commands, options = {}) {
+	return {
+		path,
+		kind,
+		manifestPath: options.manifestPath,
+		cwd: process.cwd(),
+		shell: Object.fromEntries(Object.entries(commands).map(([name, command]) => [name, formatAgentArgv(command.argv)])),
+		commands
+	};
+}
+function relocateManifestCommands(manifest, manifestPath) {
+	return Object.fromEntries(Object.entries(manifest.commands).map(([name, command]) => [name, { argv: relocateManifestArgv(command.argv, manifest, manifestPath) }]));
+}
+function relocateManifestArgv(argv, manifest, manifestPath) {
+	const [, , subcommand] = argv;
+	if (argv[0] !== "ptywright" || argv[1] !== "agent") return [...argv];
+	const manifestDir = dirname(manifestPath);
+	const artifactsRootArg = portableCliPath(manifestDir);
+	if (subcommand === "replay") {
+		const recordPath = findManifestFilePath(manifest, manifestDir, "run-record", "record");
+		if (!recordPath) return [...argv];
+		return [
+			argv[0],
+			argv[1],
+			argv[2],
+			recordPath,
+			...argv.slice(4)
+		];
+	}
+	if (subcommand === "rerun") {
+		if (manifest.kind === "replay-suite") {
+			const replayDir = findManifestReplayInputDir(manifest, manifestDir);
+			if (replayDir) return setArgvFlag([
+				argv[0],
+				argv[1],
+				"replay-all",
+				replayDir,
+				...argv.slice(4)
+			], "--artifacts-root", artifactsRootArg);
+		}
+		const summaryPath = findManifestSummaryPath(manifest, manifestDir);
+		if (!summaryPath) return [...argv];
+		return setArgvFlag([
+			argv[0],
+			argv[1],
+			argv[2],
+			summaryPath,
+			...argv.slice(4)
+		], "--artifacts-root", artifactsRootArg);
+	}
+	if (subcommand === "replay-all" && manifest.kind === "replay-suite") {
+		const replayDir = findManifestReplayInputDir(manifest, manifestDir);
+		return setArgvFlag([
+			argv[0],
+			argv[1],
+			argv[2],
+			replayDir ?? argv[3] ?? "",
+			...argv.slice(4)
+		], "--artifacts-root", artifactsRootArg);
+	}
+	if (subcommand === "check" || subcommand === "replay-all" || subcommand === "promote") return setArgvFlag([...argv], "--artifacts-root", artifactsRootArg);
+	return [...argv];
+}
+function findManifestSummaryPath(manifest, manifestDir) {
+	if (manifest.kind === "check") return findManifestFilePath(manifest, manifestDir, "check-summary", "summary");
+	if (manifest.kind === "replay-suite") return findManifestFilePath(manifest, manifestDir, "replay-summary", "summary");
+	if (manifest.kind === "promote") return findManifestFilePath(manifest, manifestDir, "promote-summary", "summary");
+	return null;
+}
+function findManifestReplayInputDir(manifest, manifestDir) {
+	const [replayRoot] = (manifest.files.find((file) => file.kind === "run-record" && !isAbsolute(file.path))?.path)?.split(/[/\\]+/g) ?? [];
+	if (replayRoot) return portableCliPath(join(manifestDir, replayRoot));
+	const recordPaths = manifest.files.filter((file) => file.kind === "run-record").map((file) => isAbsolute(file.path) ? file.path : join(manifestDir, file.path));
+	if (recordPaths.length === 0) return null;
+	const commonDir = commonAncestorDir(recordPaths);
+	return commonDir ? portableCliPath(commonDir) : null;
+}
+function findManifestFilePath(manifest, manifestDir, kind, role) {
+	const file = manifest.files.find((candidate) => candidate.kind === kind && candidate.role === role) ?? manifest.files.find((candidate) => candidate.kind === kind);
+	if (!file) return null;
+	return portableCliPath(isAbsolute(file.path) ? file.path : join(manifestDir, file.path));
+}
+function commonAncestorDir(paths) {
+	const [first, ...rest] = paths.map((path) => resolve(process.cwd(), path));
+	if (!first) return null;
+	let parts = dirname(first).split(/[\\/]+/g);
+	for (const path of rest) {
+		const nextParts = dirname(path).split(/[\\/]+/g);
+		const limit = Math.min(parts.length, nextParts.length);
+		let index = 0;
+		while (index < limit && parts[index] === nextParts[index]) index += 1;
+		parts = parts.slice(0, index);
+	}
+	if (parts.length === 0) return null;
+	return parts.join("/") || "/";
+}
+function setArgvFlag(argv, flag, value) {
+	const index = argv.indexOf(flag);
+	if (index >= 0) return [
+		...argv.slice(0, index + 1),
+		value,
+		...argv.slice(index + 2)
+	];
+	return [
+		...argv,
+		flag,
+		value
+	];
+}
+function portableCliPath(path) {
+	const abs = resolve(process.cwd(), path);
+	const rel = relative(process.cwd(), abs);
+	if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
+	return abs;
+}
+function replayCommands(path) {
+	const replay = [
+		"ptywright",
+		"agent",
+		"replay",
+		path
+	];
+	return {
+		replay: { argv: replay },
+		updateSnapshots: { argv: [...replay, "--update-snapshots"] }
+	};
+}
+function runCommands(path) {
+	const run = [
+		"ptywright",
+		"agent",
+		"run",
+		path
+	];
+	return {
+		run: { argv: run },
+		updateSnapshots: { argv: [...run, "--update-snapshots"] }
+	};
+}
+function isSupportedAgentSubcommand(value) {
+	return value === "run" || value === "record" || value === "replay" || value === "promote" || value === "replay-all" || value === "rerun" || value === "commands" || value === "inspect" || value === "exec" || value === "check" || value === "validate" || value === "init";
+}
+function isReplaySummaryLike$2(input) {
+	return typeof input === "object" && input !== null && Array.isArray(input.entries) && "totalCount" in input && "failureCount" in input;
+}
+function isPromoteSummaryLike$2(input) {
+	return typeof input === "object" && input !== null && "targetCassettePath" in input && "validation" in input && "replay" in input && Array.isArray(input.failures);
+}
+function isCheckSummaryLike$2(input) {
+	return typeof input === "object" && input !== null && "inputs" in input && "outputs" in input && "replay" in input && Array.isArray(input.failures);
+}
+function isAgentFlowLike$1(input) {
+	return typeof input === "object" && input !== null && "launch" in input && Array.isArray(input.steps);
+}
+//#endregion
+//#region src/agent/validate.ts
+async function validateAgentArtifactsPath(path, options = {}) {
+	const resolved = resolve(process.cwd(), path);
+	const files = statSync(resolved).isDirectory() ? listAgentArtifactFiles(resolved, Boolean(options.preferManifestBundle)) : [resolved];
+	const entries = [];
+	for (const filePath of files) entries.push(await validateAgentArtifactFile(filePath));
+	if (entries.length === 0) entries.push({
+		filePath: resolved,
+		kind: "unknown",
+		ok: false,
+		error: "no agent artifacts found"
+	});
+	const failureCount = entries.filter((entry) => !entry.ok).length;
+	return {
+		ok: failureCount === 0,
+		path: resolved,
+		totalCount: entries.length,
+		failureCount,
+		entries
+	};
+}
+async function validateAgentArtifactFile(filePath) {
+	const resolved = resolve(process.cwd(), filePath);
+	const kind = inferAgentArtifactKind(resolved, true);
+	if (!kind) return {
+		filePath: resolved,
+		kind: "unknown",
+		ok: false,
+		error: "unsupported agent artifact"
+	};
+	try {
+		await validateByKind(resolved, kind);
+		return {
+			filePath: resolved,
+			kind,
+			ok: true
+		};
+	} catch (error) {
+		return {
+			filePath: resolved,
+			kind,
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function listAgentArtifactFiles(dir, topLevel = false) {
+	const manifestPath = join(dir, AGENT_MANIFEST_FILE_NAME);
+	if (topLevel && safeIsFile(manifestPath)) return [manifestPath];
+	const out = [];
+	for (const entry of readdirSync(dir)) {
+		if (entry === ".git" || entry === "node_modules") continue;
+		const abs = join(dir, entry);
+		if (statSync(abs).isDirectory()) {
+			out.push(...listAgentArtifactFiles(abs));
+			continue;
+		}
+		if (inferAgentArtifactKind(abs, false)) out.push(abs);
+	}
+	return out.sort((a, b) => a.localeCompare(b));
+}
+function safeIsFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+async function validateByKind(path, kind) {
+	if (kind === "flow") {
+		if (extname(path) === ".json") {
+			normalizeAgentFlowSpec(JSON.parse(readFileSync(path, "utf8")));
+			return;
+		}
+		await loadAgentSpec(path);
+		return;
+	}
+	if (kind === "cassette") {
+		readAgentCassettePath(path);
+		return;
+	}
+	if (kind === "run-record") {
+		validateRawAgentCommandArgv(path);
+		readAgentRunRecordPath(path);
+		await validateResolvedAgentArtifactCommands(path);
+		return;
+	}
+	if (kind === "replay-summary") {
+		validateRawAgentCommandArgv(path);
+		readAgentReplaySummaryPath(path);
+		await validateResolvedAgentArtifactCommands(path);
+		return;
+	}
+	if (kind === "promote-summary") {
+		validateRawAgentCommandArgv(path);
+		readAgentPromoteSummaryPath(path);
+		await validateResolvedAgentArtifactCommands(path);
+		return;
+	}
+	if (kind === "manifest") {
+		const manifest = readAgentManifestPath(path);
+		validateAgentArtifactCommands(await readAgentArtifactCommandsPath(path));
+		validateAgentManifestCommandTargets(manifest, path);
+		validateAgentManifestFiles(manifest, path);
+		return;
+	}
+	validateRawAgentCommandArgv(path);
+	readAgentCheckSummaryPath(path);
+	await validateResolvedAgentArtifactCommands(path);
+}
+async function validateResolvedAgentArtifactCommands(path) {
+	const commands = await readAgentArtifactCommandsPath(path);
+	validateAgentArtifactCommands(commands);
+	if (!commands.manifestPath) return;
+	const manifest = readAgentManifestPath(commands.manifestPath);
+	validateAgentManifestCommandTargets(manifest, commands.manifestPath);
+	validateAgentManifestFiles(manifest, commands.manifestPath);
+}
+function validateRawAgentCommandArgv(path) {
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	if (typeof parsed !== "object" || parsed === null) return;
+	const commands = parsed.commands;
+	if (typeof commands !== "object" || commands === null || Array.isArray(commands)) return;
+	for (const [name, command] of Object.entries(commands)) {
+		const argv = typeof command === "object" && command !== null ? command.argv : void 0;
+		if (!Array.isArray(argv) || !argv.every((arg) => typeof arg === "string")) continue;
+		validateAgentCommandArgv(argv, name);
+	}
+}
+function inferAgentArtifactKind(path, allowExplicitFlowFile) {
+	const name = basename(path);
+	if (name.endsWith(".cassette.json")) return "cassette";
+	if (name.endsWith(".agent-run.json")) return "run-record";
+	if (name === "agent-replay.summary.json") return "replay-summary";
+	if (name === "agent-promote.summary.json") return "promote-summary";
+	if (name === "agent-check.summary.json") return "check-summary";
+	if (name === "ptywright-agent.manifest.json") return "manifest";
+	if (name.endsWith(".flow.json") || name.endsWith(".flow.ts")) return "flow";
+	const ext = extname(path);
+	if (allowExplicitFlowFile && (ext === ".json" || ext === ".ts")) return inferExplicitArtifactKind(path);
+	if (ext === ".json") return inferJsonArtifactKind(path);
+	return null;
+}
+function inferExplicitArtifactKind(path) {
+	if (extname(path) === ".ts") return "flow";
+	return inferJsonArtifactKind(path) ?? "flow";
+}
+function inferJsonArtifactKind(path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+	if (isAgentCassetteLike(parsed)) return "cassette";
+	if (isAgentRunRecordLike(parsed)) return "run-record";
+	if (isPromoteSummaryLike$1(parsed)) return "promote-summary";
+	if (isCheckSummaryLike$1(parsed)) return "check-summary";
+	if (isReplaySummaryLike$1(parsed)) return "replay-summary";
+	if (isAgentManifestLike(parsed)) return "manifest";
+	if (isAgentFlowLike(parsed)) return "flow";
+	return null;
+}
+function isPromoteSummaryLike$1(input) {
+	return typeof input === "object" && input !== null && "targetCassettePath" in input && "validation" in input && "replay" in input && Array.isArray(input.failures);
+}
+function isReplaySummaryLike$1(input) {
+	return typeof input === "object" && input !== null && Array.isArray(input.entries) && "totalCount" in input && "failureCount" in input;
+}
+function isCheckSummaryLike$1(input) {
+	return typeof input === "object" && input !== null && "inputs" in input && "outputs" in input && "replay" in input && Array.isArray(input.failures);
+}
+function isAgentFlowLike(input) {
+	return typeof input === "object" && input !== null && "launch" in input && Array.isArray(input.steps);
+}
+//#endregion
+//#region src/agent/check.ts
+async function checkAgentRegression(options = {}) {
+	const cassetteDir = options.cassetteDir ?? "tests/agent-cassettes";
+	const artifactsRoot = options.artifactsRoot ?? ".tmp/agent-check";
+	const summaryPath = join(artifactsRoot, "agent-check.summary.json");
+	const validationBefore = await validateAgentArtifactsPath(cassetteDir);
+	if (!validationBefore.ok) return writeSummaryAndValidateOutputs({
+		ok: false,
+		cassetteDir,
+		artifactsRoot,
+		summaryPath,
+		validationBefore,
+		replay: emptyReplayResult$1(cassetteDir, artifactsRoot),
+		validationAfter: emptyValidationResult(artifactsRoot)
+	});
+	const replay = await replayAllAgentRecords({
+		dir: cassetteDir,
+		artifactsRoot,
+		headless: options.headless ?? true,
+		updateSnapshots: options.updateSnapshots ?? false
+	});
+	return writeSummaryAndValidateOutputs({
+		ok: validationBefore.ok && replay.ok,
+		cassetteDir,
+		artifactsRoot,
+		summaryPath,
+		validationBefore,
+		replay,
+		validationAfter: emptyValidationResult(artifactsRoot)
+	});
+}
+function emptyReplayResult$1(dir, suiteDir) {
+	return {
+		ok: false,
+		dir,
+		suiteDir,
+		durationMs: 0,
+		reportPath: "",
+		summaryPath: "",
+		updateSnapshots: false,
+		entries: []
+	};
+}
+async function writeSummaryAndValidateOutputs(result) {
+	writeAgentCheckSummaryPath(result.summaryPath, formatAgentCheckJson(result));
+	const validationAfter = await validateAgentArtifactsPath(result.artifactsRoot);
+	const finalResult = {
+		...result,
+		ok: result.validationBefore.ok && result.replay.ok && validationAfter.ok,
+		validationAfter
+	};
+	writeAgentCheckSummaryPath(finalResult.summaryPath, formatAgentCheckJson(finalResult));
+	writeCheckManifest(finalResult);
+	return finalResult;
+}
+function writeCheckManifest(result) {
+	const summary = formatAgentCheckJson(result);
+	writeAgentManifestPath(agentManifestPath(result.artifactsRoot), {
+		kind: "check",
+		ok: result.ok,
+		rootDir: result.artifactsRoot,
+		primaryPath: result.summaryPath,
+		commands: summary.commands,
+		validation: {
+			ok: result.validationBefore.ok && result.replay.ok && result.validationAfter.ok,
+			stages: [
+				{
+					name: "inputs",
+					ok: result.validationBefore.ok,
+					totalCount: result.validationBefore.totalCount,
+					failureCount: result.validationBefore.failureCount
+				},
+				{
+					name: "replay",
+					ok: result.replay.ok,
+					totalCount: result.replay.entries.length,
+					failureCount: result.replay.entries.filter((entry) => !entry.result.ok).length
+				},
+				{
+					name: "outputs",
+					ok: result.validationAfter.ok,
+					totalCount: result.validationAfter.totalCount,
+					failureCount: result.validationAfter.failureCount
+				}
+			]
+		},
+		files: [
+			{
+				path: result.summaryPath,
+				kind: "check-summary",
+				role: "summary",
+				ok: result.ok
+			},
+			{
+				path: result.replay.summaryPath,
+				kind: "replay-summary",
+				role: "replay-summary",
+				ok: result.replay.ok
+			},
+			{
+				path: result.replay.reportPath,
+				kind: "report",
+				role: "replay-report",
+				ok: result.replay.ok
+			},
+			...result.replay.entries.flatMap((entry) => [
+				{
+					path: entry.result.recordPath,
+					kind: "run-record",
+					role: "record",
+					ok: entry.result.ok
+				},
+				{
+					path: entry.result.reportPath,
+					kind: "report",
+					role: "entry-report",
+					ok: entry.result.ok
+				},
+				...entry.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 emptyValidationResult(path) {
+	return {
+		ok: true,
+		path,
+		totalCount: 0,
+		failureCount: 0,
+		entries: []
+	};
+}
+function parseArgs(argv) {
+	const out = {};
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (arg === "--dir" && next) {
+			out.cassetteDir = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--artifacts-root" && next) {
+			out.artifactsRoot = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--update-snapshots") {
+			out.updateSnapshots = true;
+			continue;
+		}
+		if (arg === "--headed") {
+			out.headless = false;
+			continue;
+		}
+		if (arg === "--json") {
+			out.json = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	return out;
+}
+function formatAgentCheckLines(result) {
+	return [
+		`${result.ok ? "ok" : "failed"} agent-check`,
+		`inputs=${result.validationBefore.totalCount} failures=${result.validationBefore.failureCount}`,
+		result.replay.summaryPath ? `summary=${result.replay.summaryPath}` : null,
+		`checkSummary=${result.summaryPath}`,
+		result.replay.reportPath ? `report=${result.replay.reportPath}` : null,
+		`outputs=${result.validationAfter.totalCount} failures=${result.validationAfter.failureCount}`,
+		...result.validationBefore.entries.filter((entry) => !entry.ok).flatMap((entry) => [`- input ${entry.filePath}`, `  error=${entry.error ?? ""}`]),
+		...result.replay.entries.filter((entry) => !entry.result.ok).flatMap((entry) => [`- replay ${entry.filePath}`, ...entry.result.errors.map((error) => `  error=${error}`)]),
+		...result.validationAfter.entries.filter((entry) => !entry.ok).flatMap((entry) => [`- output ${entry.filePath}`, `  error=${entry.error ?? ""}`])
+	].filter(Boolean);
+}
+function formatAgentCheckJson(result) {
+	const replayFailures = result.replay.entries.filter((entry) => !entry.result.ok);
+	return normalizeAgentCheckJsonSummary({
+		$schema: AGENT_CHECK_SCHEMA_URL,
+		version: 1,
+		ok: result.ok,
+		cassetteDir: result.cassetteDir,
+		artifactsRoot: result.artifactsRoot,
+		summaryPath: result.summaryPath,
+		commands: {
+			check: { argv: [
+				"ptywright",
+				"agent",
+				"check",
+				result.cassetteDir,
+				"--artifacts-root",
+				result.artifactsRoot
+			] },
+			updateSnapshots: { argv: [
+				"ptywright",
+				"agent",
+				"check",
+				result.cassetteDir,
+				"--artifacts-root",
+				result.artifactsRoot,
+				"--update-snapshots"
+			] },
+			rerun: { argv: [
+				"ptywright",
+				"agent",
+				"rerun",
+				result.summaryPath
+			] }
+		},
+		inputs: {
+			totalCount: result.validationBefore.totalCount,
+			failureCount: result.validationBefore.failureCount
+		},
+		replay: {
+			ok: result.replay.ok,
+			totalCount: result.replay.entries.length,
+			failureCount: replayFailures.length,
+			reportPath: result.replay.reportPath,
+			summaryPath: result.replay.summaryPath
+		},
+		outputs: {
+			totalCount: result.validationAfter.totalCount,
+			failureCount: result.validationAfter.failureCount
+		},
+		failures: [
+			...result.validationBefore.entries.filter((entry) => !entry.ok).map((entry) => ({
+				stage: "input",
+				filePath: entry.filePath,
+				kind: entry.kind,
+				errors: entry.error ? [entry.error] : []
+			})),
+			...replayFailures.map((entry) => ({
+				stage: "replay",
+				filePath: entry.filePath,
+				errors: entry.result.errors
+			})),
+			...result.validationAfter.entries.filter((entry) => !entry.ok).map((entry) => ({
+				stage: "output",
+				filePath: entry.filePath,
+				kind: entry.kind,
+				errors: entry.error ? [entry.error] : []
+			}))
+		]
+	});
+}
+function logCheckResult(result) {
+	for (const line of formatAgentCheckLines(result)) (result.ok ? console.log : console.error)(line);
+}
+if (import.meta.main) try {
+	const args = parseArgs(process.argv.slice(2));
+	const result = await checkAgentRegression(args);
+	if (args.json) console.log(JSON.stringify(formatAgentCheckJson(result), null, 2));
+	else logCheckResult(result);
+	process.exitCode = result.ok ? 0 : 1;
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+}
+//#endregion
+//#region src/agent/inspect.ts
+async function inspectAgentArtifactPath(path) {
+	const target = resolveInspectTarget(path);
+	const targetPath = target.targetPath;
+	const validation = await validateInspectTarget(path, targetPath);
+	const commands = await maybeReadCommands(targetPath);
+	const manifest = maybeReadManifest$1(targetPath);
+	return {
+		path: resolve(process.cwd(), path),
+		targetPath,
+		kind: commands?.kind ?? validation.entries[0]?.kind ?? "unknown",
+		ok: validation.ok,
+		directory: target.directory,
+		validation,
+		commands,
+		manifest
+	};
+}
+function formatAgentInspectLines(result) {
+	const lines = [
+		`${result.ok ? "ok" : "failed"} agent-inspect`,
+		`kind=${result.kind}`,
+		`path=${result.targetPath}`,
+		`validation=${result.validation.ok ? "ok" : "failed"} count=${result.validation.totalCount}`
+	];
+	if (result.validation.failureCount > 0) {
+		lines.push(`failures=${result.validation.failureCount}`);
+		lines.push(...formatValidationFailures(result.validation.entries));
+	}
+	if (result.directory) {
+		lines.push(`directoryManifest=${result.directory.hasManifest ? "found" : "missing"} path=${result.directory.manifestPath}`);
+		if (result.directory.hint) lines.push(`hint=${result.directory.hint}`);
+	}
+	if (result.manifest) {
+		lines.push(`manifest=${result.manifest.path}`, `manifestKind=${result.manifest.kind}`, `manifestFiles=${result.manifest.files.totalCount}`, `manifestBytes=${result.manifest.files.totalBytes}`);
+		for (const [kind, count] of Object.entries(result.manifest.files.byKind)) lines.push(`manifestFileKind.${kind}=${count}`);
+		if (result.manifest.validation) lines.push(`manifestValidation=${result.manifest.validation.ok ? "ok" : "failed"}`, ...result.manifest.validation.stages.map((stage) => `manifestStage.${stage.name}=${stage.ok ? "ok" : "failed"} count=${stage.totalCount} failures=${stage.failureCount}`));
+		if (result.manifest.files.failures.length > 0) lines.push(...result.manifest.files.failures.map((file) => `manifestFileFailure=${file.path} kind=${file.kind}${file.role ? ` role=${file.role}` : ""}`));
+	}
+	if (result.commands) {
+		if (result.commands.manifestPath) lines.push(`commandsManifest=${result.commands.manifestPath}`);
+		lines.push(`commands=${Object.keys(result.commands.commands).sort().join(",")}`, ...formatAgentArtifactCommandLines(result.commands).filter((line) => !line.startsWith("kind=") && !line.startsWith("path=")).map((line) => `command.${line}`));
+	}
+	return lines;
+}
+function resolveInspectTarget(path) {
+	const resolved = resolve(process.cwd(), path);
+	if (!statSync(resolved).isDirectory()) return { targetPath: resolved };
+	const manifestPath = join(resolved, AGENT_MANIFEST_FILE_NAME);
+	const hasManifest = existsSync(manifestPath);
+	return {
+		targetPath: hasManifest ? manifestPath : resolved,
+		directory: {
+			isDirectory: true,
+			manifestPath,
+			hasManifest,
+			hint: hasManifest ? void 0 : `${AGENT_MANIFEST_FILE_NAME} is required for portable commands/exec bundle workflows; use agent validate <dir> for recursive discovery.`
+		}
+	};
+}
+async function validateInspectTarget(originalPath, targetPath) {
+	if (targetPath !== resolve(process.cwd(), originalPath)) {
+		const entry = await validateAgentArtifactFile(targetPath);
+		return {
+			ok: entry.ok,
+			path: targetPath,
+			totalCount: 1,
+			failureCount: entry.ok ? 0 : 1,
+			entries: [entry]
+		};
+	}
+	return validateAgentArtifactsPath(targetPath);
+}
+async function maybeReadCommands(path) {
+	try {
+		return await readAgentArtifactCommandsPath(path);
+	} catch {
+		return;
+	}
+}
+function maybeReadManifest$1(path) {
+	if (basename(path) !== "ptywright-agent.manifest.json") return;
+	let manifest;
+	try {
+		manifest = readAgentManifestPath(path);
+	} catch {
+		return;
+	}
+	const byKind = {};
+	let totalBytes = 0;
+	const failures = [];
+	for (const file of manifest.files) {
+		byKind[file.kind] = (byKind[file.kind] ?? 0) + 1;
+		totalBytes += file.bytes;
+		if (file.ok === false) failures.push({
+			path: file.path,
+			kind: file.kind,
+			role: file.role
+		});
+	}
+	return {
+		path,
+		kind: manifest.kind,
+		ok: manifest.ok,
+		rootDir: manifest.rootDir,
+		primaryPath: resolveManifestPrimaryPath(manifest, path),
+		generatedAt: manifest.generatedAt,
+		validation: manifest.validation,
+		files: {
+			totalCount: manifest.files.length,
+			totalBytes,
+			byKind: Object.fromEntries(Object.entries(byKind).sort(([a], [b]) => a.localeCompare(b))),
+			failures
+		}
+	};
+}
+function resolveManifestPrimaryPath(manifest, manifestPath) {
+	const manifestDir = dirname(manifestPath);
+	const primaryFile = manifest.files.find((file) => file.role === "summary") ?? manifest.files.find((file) => file.role === "record") ?? manifest.files.find((file) => file.kind === "run-record") ?? manifest.files.find((file) => file.kind.endsWith("-summary"));
+	if (primaryFile) return isAbsolute(primaryFile.path) ? primaryFile.path : join(manifestDir, primaryFile.path);
+	return isAbsolute(manifest.primaryPath) ? manifest.primaryPath : resolve(process.cwd(), manifest.primaryPath);
+}
+function formatValidationFailures(entries) {
+	return entries.filter((entry) => !entry.ok).flatMap((entry) => [
+		`- ${entry.filePath}`,
+		`  kind=${entry.kind}`,
+		entry.error ? `  error=${entry.error}` : null
+	]).filter((line) => line !== null);
+}
+//#endregion
+//#region src/agent/promote.ts
+async function promoteAgentCassette(options) {
+	const sourceCassette = readAgentCassettePath(resolveSourceCassettePath(resolve(process.cwd(), options.sourcePath)));
+	const name = sanitizeArtifactName(sourceCassette.name);
+	const cassetteDir = options.cassetteDir ?? "tests/agent-cassettes";
+	const snapshotDir = options.snapshotDir ?? join("tests", "agent-snapshots", name);
+	const artifactsRoot = options.artifactsRoot ?? join(".tmp", "agent-promote", name);
+	const targetDir = join(cassetteDir, name);
+	const targetCassettePath = join(targetDir, `${name}.cassette.json`);
+	const summaryPath = join(artifactsRoot, "agent-promote.summary.json");
+	const updateSnapshots = options.updateSnapshots ?? false;
+	mkdirSync(targetDir, { recursive: true });
+	mkdirSync(artifactsRoot, { recursive: true });
+	const promotedCassette = {
+		...sourceCassette,
+		spec: {
+			...sourceCassette.spec,
+			snapshotDir
+		}
+	};
+	writeFileSync(targetCassettePath, JSON.stringify(promotedCassette, null, 2) + "\n", "utf8");
+	const validation = await validateAgentArtifactsPath(targetCassettePath);
+	let replay = emptyReplayResult(targetDir, artifactsRoot, updateSnapshots);
+	if (validation.ok) replay = await replayAllAgentRecords({
+		dir: targetDir,
+		artifactsRoot,
+		headless: options.headless ?? true,
+		updateSnapshots
+	});
+	const result = {
+		ok: validation.ok && replay.ok,
+		sourcePath: options.sourcePath,
+		cassetteDir,
+		targetDir,
+		targetCassettePath,
+		snapshotDir,
+		artifactsRoot,
+		summaryPath,
+		updateSnapshots,
+		validation,
+		replay
+	};
+	writeAgentPromoteSummaryPath(summaryPath, formatAgentPromoteSummary(result));
+	writePromoteManifest(result);
+	return result;
+}
+function formatAgentPromoteSummary(result) {
+	const replayFailures = result.replay.entries.filter((entry) => !entry.result.ok);
+	return normalizeAgentPromoteSummary({
+		$schema: AGENT_PROMOTE_SCHEMA_URL,
+		version: 1,
+		ok: result.ok,
+		sourcePath: result.sourcePath,
+		cassetteDir: result.cassetteDir,
+		targetDir: result.targetDir,
+		targetCassettePath: result.targetCassettePath,
+		snapshotDir: result.snapshotDir,
+		artifactsRoot: result.artifactsRoot,
+		summaryPath: result.summaryPath,
+		updateSnapshots: result.updateSnapshots,
+		commands: {
+			promote: { argv: [
+				"ptywright",
+				"agent",
+				"promote",
+				result.sourcePath,
+				"--cassette-dir",
+				result.cassetteDir,
+				"--snapshot-dir",
+				result.snapshotDir,
+				"--artifacts-root",
+				result.artifactsRoot,
+				...result.updateSnapshots ? ["--update-snapshots"] : []
+			] },
+			check: { argv: [
+				"ptywright",
+				"agent",
+				"check",
+				result.cassetteDir,
+				"--artifacts-root",
+				result.artifactsRoot
+			] },
+			updateSnapshots: { argv: [
+				"ptywright",
+				"agent",
+				"check",
+				result.cassetteDir,
+				"--artifacts-root",
+				result.artifactsRoot,
+				"--update-snapshots"
+			] },
+			rerun: { argv: [
+				"ptywright",
+				"agent",
+				"rerun",
+				result.summaryPath
+			] }
+		},
+		validation: {
+			ok: result.validation.ok,
+			totalCount: result.validation.totalCount,
+			failureCount: result.validation.failureCount
+		},
+		replay: {
+			ok: result.replay.ok,
+			totalCount: result.replay.entries.length,
+			failureCount: replayFailures.length,
+			reportPath: result.replay.reportPath,
+			summaryPath: result.replay.summaryPath
+		},
+		failures: [...result.validation.entries.filter((entry) => !entry.ok).map((entry) => ({
+			stage: "validation",
+			filePath: entry.filePath,
+			kind: entry.kind,
+			errors: entry.error ? [entry.error] : []
+		})), ...replayFailures.map((entry) => ({
+			stage: "replay",
+			filePath: entry.filePath,
+			errors: entry.result.errors
+		}))]
+	});
+}
+function formatAgentPromoteLines(result) {
+	return [
+		`${result.ok ? "ok" : "failed"} agent-promote`,
+		`source=${result.sourcePath}`,
+		`cassette=${result.targetCassettePath}`,
+		`snapshots=${result.snapshotDir}`,
+		`summary=${result.summaryPath}`,
+		result.replay.reportPath ? `report=${result.replay.reportPath}` : null,
+		`validation=${result.validation.failureCount}/${result.validation.totalCount}`,
+		`replay=${result.replay.entries.filter((entry) => !entry.result.ok).length}/${result.replay.entries.length}`,
+		...result.validation.entries.filter((entry) => !entry.ok).flatMap((entry) => [`- validation ${entry.filePath}`, `  error=${entry.error ?? ""}`]),
+		...result.replay.entries.filter((entry) => !entry.result.ok).flatMap((entry) => [`- replay ${entry.filePath}`, ...entry.result.errors.map((error) => `  error=${error}`)])
+	].filter(Boolean);
+}
+function writePromoteManifest(result) {
+	const summary = formatAgentPromoteSummary(result);
+	writeAgentManifestPath(agentManifestPath(result.artifactsRoot), {
+		kind: "promote",
+		ok: result.ok,
+		rootDir: result.artifactsRoot,
+		primaryPath: result.summaryPath,
+		commands: summary.commands,
+		validation: {
+			ok: result.validation.ok && result.replay.ok,
+			stages: [{
+				name: "validation",
+				ok: result.validation.ok,
+				totalCount: result.validation.totalCount,
+				failureCount: result.validation.failureCount
+			}, {
+				name: "replay",
+				ok: result.replay.ok,
+				totalCount: result.replay.entries.length,
+				failureCount: result.replay.entries.filter((entry) => !entry.result.ok).length
+			}]
+		},
+		files: [
+			{
+				path: result.summaryPath,
+				kind: "promote-summary",
+				role: "summary",
+				ok: result.ok
+			},
+			{
+				path: result.targetCassettePath,
+				kind: "cassette",
+				role: "promoted-cassette"
+			},
+			{
+				path: result.replay.summaryPath,
+				kind: "replay-summary",
+				role: "replay-summary",
+				ok: result.replay.ok
+			},
+			{
+				path: result.replay.reportPath,
+				kind: "report",
+				role: "replay-report",
+				ok: result.replay.ok
+			},
+			...result.replay.entries.flatMap((entry) => [
+				{
+					path: entry.result.recordPath,
+					kind: "run-record",
+					role: "record",
+					ok: entry.result.ok
+				},
+				{
+					path: entry.result.reportPath,
+					kind: "report",
+					role: "entry-report",
+					ok: entry.result.ok
+				},
+				...entry.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 resolveSourceCassettePath(sourcePath) {
+	if (sourcePath.endsWith(".cassette.json")) return sourcePath;
+	if (sourcePath.endsWith(".agent-run.json")) {
+		const record = readAgentRunRecordPath(sourcePath);
+		if (!record.cassettePath) throw new Error(`agent run record does not reference a cassette: ${sourcePath}`);
+		return resolve(dirname(sourcePath), record.cassettePath);
+	}
+	throw new Error(`agent promote requires .cassette.json or .agent-run.json: ${sourcePath}`);
+}
+function emptyReplayResult(dir, suiteDir, updateSnapshots) {
+	return {
+		ok: false,
+		dir,
+		suiteDir,
+		durationMs: 0,
+		reportPath: "",
+		summaryPath: "",
+		updateSnapshots,
+		entries: []
+	};
+}
+//#endregion
+//#region src/agent/recorder.ts
+async function recordAgentSpecPath(specPath, options) {
+	return recordAgentSpec((await loadAgentSpec(specPath)).spec, options);
+}
+async function recordAgentSpec(input, options) {
+	const spec = normalizeAgentFlowSpec(input);
+	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
+	const launchMode = spec.launch.mode ?? (spec.launch.url ? "url" : "aitty");
+	const outPath = isAbsolute(options.outPath) ? options.outPath : resolve(process.cwd(), options.outPath);
+	const durationMs = options.durationMs ?? 3e4;
+	const steps = [];
+	let browser = null;
+	const session = launchMode === "aitty" ? await launchAittyBrowserSession(spec.launch, { rootDir }) : null;
+	const url = launchMode === "url" ? spec.launch.url : session.url;
+	try {
+		browser = await launchAgentBrowser({ headless: options.headless ?? false });
+		const viewport = spec.viewports?.[0] ?? {
+			name: "desktop",
+			width: 1280,
+			height: 820
+		};
+		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();
+		await installRecorderHooks(page);
+		await page.goto(url, {
+			waitUntil: "domcontentloaded",
+			timeout: spec.defaults?.timeoutMs ?? 3e4
+		});
+		await page.locator("[data-terminal-root]").first().waitFor({
+			state: "attached",
+			timeout: spec.defaults?.timeoutMs ?? 3e4
+		});
+		await page.waitForTimeout(durationMs);
+		steps.push(...await readRecordedSteps(page));
+		await context.close();
+		if (options.includeSnapshot ?? true) {
+			steps.push({
+				type: "waitForStableDom",
+				quietMs: 600,
+				intervalMs: 150,
+				timeoutMs: spec.defaults?.timeoutMs ?? 3e4
+			});
+			steps.push({
+				type: "snapshot",
+				name: "recorded-final",
+				targets: [
+					"terminal",
+					"dom",
+					"screenshot"
+				]
+			});
+		}
+		const recorded = {
+			...spec,
+			steps: steps.length > 0 ? steps : spec.steps
+		};
+		mkdirSync(dirname(outPath), { recursive: true });
+		writeFileSync(outPath, JSON.stringify(recorded, null, 2) + "\n", "utf8");
+		return {
+			ok: true,
+			outPath,
+			stepCount: recorded.steps.length,
+			url
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			outPath,
+			stepCount: steps.length,
+			url,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		await browser?.close();
+		await session?.close();
+	}
+}
+async function installRecorderHooks(page) {
+	await page.addInitScript(() => {
+		const state = {
+			steps: [],
+			textBuffer: ""
+		};
+		const flushText = () => {
+			if (!state.textBuffer) return;
+			state.steps.push({
+				type: "typeText",
+				text: state.textBuffer
+			});
+			state.textBuffer = "";
+		};
+		window.addEventListener("keydown", (event) => {
+			if (event.metaKey || event.ctrlKey || event.altKey) {
+				flushText();
+				state.steps.push({
+					type: "pressKey",
+					key: formatKey(event)
+				});
+				return;
+			}
+			if (event.key === "Enter") {
+				if (state.textBuffer) {
+					state.steps.push({
+						type: "typeText",
+						text: state.textBuffer,
+						enter: true
+					});
+					state.textBuffer = "";
+				} else state.steps.push({
+					type: "pressKey",
+					key: "Enter"
+				});
+				return;
+			}
+			if (event.key.length === 1) {
+				state.textBuffer += event.key;
+				return;
+			}
+			flushText();
+			state.steps.push({
+				type: "pressKey",
+				key: formatKey(event)
+			});
+		}, true);
+		window.addEventListener("click", (event) => {
+			flushText();
+			state.steps.push({
+				type: "click",
+				x: Math.max(0, Math.round(event.clientX)),
+				y: Math.max(0, Math.round(event.clientY))
+			});
+		}, true);
+		Object.defineProperty(window, "__ptywrightAgentRecorder", {
+			value: { read() {
+				flushText();
+				return state.steps.slice();
+			} },
+			configurable: true
+		});
+		function formatKey(event) {
+			const parts = [];
+			if (event.ctrlKey) parts.push("Control");
+			if (event.altKey) parts.push("Alt");
+			if (event.metaKey) parts.push("Meta");
+			if (event.shiftKey && event.key.length !== 1) parts.push("Shift");
+			parts.push(event.key === " " ? "Space" : event.key);
+			return parts.join("+");
+		}
+	});
+}
+async function readRecordedSteps(page) {
+	return page.evaluate(() => {
+		return window.__ptywrightAgentRecorder?.read() ?? [];
+	});
+}
+//#endregion
+//#region src/agent/rerun.ts
+async function rerunAgentSummary(options) {
+	const path = resolve(process.cwd(), options.path);
+	const kind = inferSummaryKind(path);
+	if (kind === "check-summary") {
+		const summary = readAgentCheckSummaryPath(path);
+		const movedBundle = findMovedPrimaryManifestBundle(path, "check-summary");
+		return {
+			kind,
+			result: await checkAgentRegression({
+				cassetteDir: movedBundle?.replayInputDir ?? summary.cassetteDir,
+				artifactsRoot: options.artifactsRoot ?? movedBundle?.artifactsRoot ?? summary.artifactsRoot,
+				headless: options.headless ?? true,
+				updateSnapshots: options.updateSnapshots ?? false
+			})
+		};
+	}
+	if (kind === "promote-summary") {
+		const summary = readAgentPromoteSummaryPath(path);
+		const movedBundle = findMovedPrimaryManifestBundle(path, "promote-summary");
+		return {
+			kind,
+			result: await promoteAgentCassette({
+				sourcePath: summary.sourcePath,
+				cassetteDir: summary.cassetteDir,
+				snapshotDir: summary.snapshotDir,
+				artifactsRoot: options.artifactsRoot ?? movedBundle?.artifactsRoot ?? summary.artifactsRoot,
+				headless: options.headless ?? true,
+				updateSnapshots: options.updateSnapshots ?? summary.updateSnapshots
+			})
+		};
+	}
+	if (kind === "replay-summary") {
+		const summary = readAgentReplaySummaryPath(path);
+		const movedReplayBundle = findMovedPrimaryManifestBundle(path, "replay-summary");
+		return {
+			kind,
+			result: await replayAllAgentRecords({
+				dir: movedReplayBundle?.replayInputDir ?? summary.dir,
+				artifactsRoot: options.artifactsRoot ?? movedReplayBundle?.artifactsRoot ?? summary.suiteDir,
+				headless: options.headless ?? true,
+				updateSnapshots: options.updateSnapshots ?? false
+			})
+		};
+	}
+	throw new Error(`unsupported agent summary: ${options.path}`);
+}
+function inferSummaryKind(path) {
+	const name = basename(path);
+	if (name === "agent-check.summary.json") return "check-summary";
+	if (name === "agent-promote.summary.json") return "promote-summary";
+	if (name === "agent-replay.summary.json") return "replay-summary";
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+	if (isCheckSummaryLike(parsed)) return "check-summary";
+	if (isPromoteSummaryLike(parsed)) return "promote-summary";
+	if (isReplaySummaryLike(parsed)) return "replay-summary";
+	return null;
+}
+function isPromoteSummaryLike(input) {
+	return typeof input === "object" && input !== null && "targetCassettePath" in input && "validation" in input && "replay" in input && Array.isArray(input.failures);
+}
+function isCheckSummaryLike(input) {
+	return typeof input === "object" && input !== null && "inputs" in input && "outputs" in input && "replay" in input && Array.isArray(input.failures);
+}
+function isReplaySummaryLike(input) {
+	return typeof input === "object" && input !== null && Array.isArray(input.entries) && "totalCount" in input && "failureCount" in input;
+}
+//#endregion
+//#region src/mcp/http_server.ts
+function parseAllowedOrigins(value) {
+	if (!value?.trim()) return void 0;
+	return value.split(/[\s,]+/g).map((v) => v.trim()).filter(Boolean);
+}
+function isOriginAllowed(origin, allowed) {
+	if (allowed.includes("*")) return true;
+	return allowed.includes(origin);
+}
+function withCorsHeaders(init, origin, allowed) {
+	if (!origin) return init;
+	if (!isOriginAllowed(origin, allowed)) return init;
+	const headers = new Headers(init.headers);
+	headers.set("access-control-allow-origin", origin);
+	headers.set("vary", "origin");
+	headers.set("access-control-allow-methods", "GET,POST,DELETE,OPTIONS");
+	headers.set("access-control-allow-headers", "content-type,mcp-session-id,last-event-id,mcp-protocol-version");
+	headers.set("access-control-expose-headers", "mcp-session-id,mcp-protocol-version");
+	return {
+		...init,
+		headers
+	};
+}
+async function startPtywrightHttpServer(options) {
+	const hostname = options?.hostname?.trim() ? options.hostname.trim() : "127.0.0.1";
+	const desiredPort = options?.port ?? 3e3;
+	const cors = options?.cors ?? true;
+	const { server, sessions } = createPtywrightServer({ capabilities: options?.capabilities });
+	const transport = new WebStandardStreamableHTTPServerTransport();
+	await server.connect(transport);
+	let allowedOrigins = options?.allowedOrigins ?? parseAllowedOrigins(process.env.PTYWRIGHT_HTTP_ALLOWED_ORIGINS) ?? [];
+	const srv = Bun.serve({
+		hostname,
+		port: desiredPort,
+		fetch: async (req) => {
+			const url = new URL(req.url);
+			const origin = req.headers.get("origin");
+			if (url.pathname === "/health") {
+				const init = withCorsHeaders({
+					status: 200,
+					headers: { "content-type": "application/json" }
+				}, cors ? origin : null, allowedOrigins);
+				return new Response(JSON.stringify({ status: "ok" }), init);
+			}
+			if (url.pathname !== "/mcp") {
+				const init = withCorsHeaders({
+					status: 404,
+					headers: { "content-type": "text/plain; charset=utf-8" }
+				}, cors ? origin : null, allowedOrigins);
+				return new Response("not found", init);
+			}
+			if (origin && !isOriginAllowed(origin, allowedOrigins)) return new Response("forbidden", {
+				status: 403,
+				headers: cors ? {
+					"content-type": "text/plain; charset=utf-8",
+					"access-control-allow-origin": origin,
+					vary: "origin"
+				} : { "content-type": "text/plain; charset=utf-8" }
+			});
+			if (req.method === "OPTIONS") return new Response(null, withCorsHeaders({ status: 204 }, origin, allowedOrigins));
+			const res = await transport.handleRequest(req);
+			if (!cors) return res;
+			const init = withCorsHeaders({
+				status: res.status,
+				statusText: res.statusText,
+				headers: res.headers
+			}, origin, allowedOrigins);
+			return new Response(res.body, init);
+		}
+	});
+	const port = srv.port;
+	if (port === void 0) {
+		await srv.stop();
+		sessions.closeAll();
+		await server.close();
+		throw new Error("failed to bind HTTP server port");
+	}
+	if (allowedOrigins.length === 0) allowedOrigins = [`http://localhost:${port}`, `http://127.0.0.1:${port}`];
+	return {
+		url: `http://${hostname}:${port}/mcp`,
+		hostname,
+		port,
+		close: async () => {
+			await srv.stop();
+			sessions.closeAll();
+			await server.close();
+		}
+	};
+}
+//#endregion
+//#region src/pty-cassette/cli.ts
+function ptyUsage() {
+	return [
+		"ptywright pty <command>",
+		"",
+		"Commands:",
+		"  pty record --out <file> -- <command> [args...]  Record a raw PTY cassette",
+		"  pty replay <file>                               Replay recorded PTY output",
+		"  pty inspect <file>                              Print cassette summary",
+		"  pty validate <file>                             Validate cassette schema",
+		"",
+		"Record options:",
+		"  --out <file>             Output cassette JSON path",
+		"  --cols <n>               Terminal columns (default: stdout cols or 80)",
+		"  --rows <n>               Terminal rows (default: stdout rows or 24)",
+		"  --term <name>            TERM/name value (default: xterm-256color)",
+		"  --cwd <dir>              Child working directory (default: cwd)",
+		"  --backend <name>         auto|bun-terminal|bun-pty",
+		"  --env KEY=VALUE          Add/override child env (repeatable)",
+		"",
+		"Replay/inspect/validate options:",
+		"  --speed <n>              Replay timing multiplier; 0 means instant (default: 0)",
+		"  --json                   Print machine-readable output"
+	].join("\n");
+}
+async function cmdPty(argv) {
+	const [mode, ...rest] = argv;
+	if (isHelp$1(mode)) {
+		console.log(ptyUsage());
+		return 0;
+	}
+	if (mode === "record") {
+		const result = await recordPtyCassetteCommand(parseRecordArgs(rest));
+		console.log(`record=${result.path}`);
+		console.log(`events=${result.eventCount}`);
+		return result.exitCode;
+	}
+	if (mode === "replay") {
+		const args = parseReplayArgs(rest);
+		const replay = createPtyCassetteReplay(args.path, { speed: args.speed });
+		replay.onData((data) => {
+			process.stdout.write(data);
+		});
+		await replay.start();
+		return 0;
+	}
+	if (mode === "inspect") {
+		const args = parseArtifactArgs(rest);
+		const result = inspectPtyCassettePath(args.path);
+		if (args.json) console.log(JSON.stringify(result, null, 2));
+		else for (const line of formatPtyCassetteInspectLines(result)) console.log(line);
+		return 0;
+	}
+	if (mode === "validate") {
+		const args = parseArtifactArgs(rest);
+		const result = validatePtyCassette(JSON.parse(await Bun.file(args.path).text()));
+		if (args.json) console.log(JSON.stringify(result.ok ? {
+			ok: true,
+			path: args.path
+		} : result, null, 2));
+		else if (result.ok) console.log(`ok pty-cassette path=${args.path}`);
+		else for (const error of result.errors) console.error(error);
+		return result.ok ? 0 : 1;
+	}
+	throw new Error("missing pty subcommand: record|replay|inspect|validate\n\n" + ptyUsage());
+}
+async function recordPtyCassetteCommand(args) {
+	const env = mergeEnv({
+		TERM: args.term,
+		COLORTERM: "truecolor"
+	}, args.env);
+	const pty = createDefaultPtyAdapter(args.backend).spawn(args.command, args.args, {
+		cols: args.cols,
+		rows: args.rows,
+		cwd: args.cwd,
+		env,
+		name: args.term
+	});
+	const recorder = createPtyCassetteRecorder({
+		terminal: {
+			cols: args.cols,
+			rows: args.rows,
+			term: args.term
+		},
+		command: {
+			file: args.command,
+			args: args.args,
+			cwd: args.cwd,
+			env: args.env
+		}
+	});
+	const wrapped = wrapPtyLike(toPtyLike(pty), { recorder });
+	const cleanup = attachInteractiveBridge(wrapped, args);
+	const exit = await new Promise((resolveExit) => {
+		wrapped.onExit((event) => {
+			resolveExit({ exitCode: event.exitCode });
+		});
+	});
+	cleanup();
+	wrapped.writeCassette(args.outPath);
+	const cassette = readPtyCassettePath(args.outPath);
+	wrapped.dispose();
+	return {
+		path: args.outPath,
+		eventCount: cassette.events.length,
+		exitCode: exit.exitCode
+	};
+}
+function parseRecordArgs(argv) {
+	const out = {
+		cols: terminalCols(),
+		rows: terminalRows(),
+		term: "xterm-256color",
+		cwd: process.cwd(),
+		backend: resolvePtyBackend(void 0),
+		env: {}
+	};
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (arg === "--") {
+			const [command, ...args] = argv.slice(i + 1);
+			if (!command) throw new Error("missing command after --\n\n" + ptyUsage());
+			out.command = command;
+			out.args = args;
+			break;
+		}
+		if (!arg) continue;
+		if (!arg.startsWith("-")) {
+			out.command = arg;
+			out.args = argv.slice(i + 1);
+			break;
+		}
+		if (arg === "--out" && next) {
+			out.outPath = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--cols" && next) {
+			out.cols = parsePositiveInt(next, "--cols");
+			i += 1;
+			continue;
+		}
+		if (arg === "--rows" && next) {
+			out.rows = parsePositiveInt(next, "--rows");
+			i += 1;
+			continue;
+		}
+		if (arg === "--term" && next) {
+			out.term = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--cwd" && next) {
+			out.cwd = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--backend" && next) {
+			out.backend = resolvePtyBackend(next);
+			i += 1;
+			continue;
+		}
+		if (arg === "--env" && next) {
+			const eq = next.indexOf("=");
+			if (eq <= 0) throw new Error(`invalid --env: ${next}`);
+			out.env[next.slice(0, eq)] = next.slice(eq + 1);
+			i += 1;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg}\n\n` + ptyUsage());
+	}
+	if (!out.outPath) throw new Error("missing --out <file>\n\n" + ptyUsage());
+	if (!out.command) throw new Error("missing command to record\n\n" + ptyUsage());
+	return {
+		outPath: out.outPath,
+		command: out.command,
+		args: out.args ?? [],
+		cols: out.cols ?? terminalCols(),
+		rows: out.rows ?? terminalRows(),
+		term: out.term ?? "xterm-256color",
+		cwd: out.cwd ?? process.cwd(),
+		backend: out.backend ?? "auto",
+		env: out.env
+	};
+}
+function parseReplayArgs(argv) {
+	const out = { speed: 0 };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (!out.path && arg && !arg.startsWith("-")) {
+			out.path = arg;
+			continue;
+		}
+		if (arg === "--speed" && next) {
+			const speed = Number.parseFloat(next);
+			if (!Number.isFinite(speed) || speed < 0) throw new Error(`invalid --speed: ${next}`);
+			out.speed = speed;
+			i += 1;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}\n\n` + ptyUsage());
+	}
+	if (!out.path) throw new Error("missing <file>\n\n" + ptyUsage());
+	return {
+		path: out.path,
+		speed: out.speed
+	};
+}
+function parseArtifactArgs(argv) {
+	const out = { json: false };
+	for (const arg of argv) {
+		if (!out.path && arg && !arg.startsWith("-")) {
+			out.path = arg;
+			continue;
+		}
+		if (arg === "--json") {
+			out.json = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}\n\n` + ptyUsage());
+	}
+	if (!out.path) throw new Error("missing <file>\n\n" + ptyUsage());
+	return {
+		path: out.path,
+		json: out.json
+	};
+}
+function attachInteractiveBridge(pty, args) {
+	const onData = (data) => {
+		process.stdout.write(typeof data === "string" ? data : Buffer.from(data));
+	};
+	const onInput = (data) => {
+		pty.write(data);
+	};
+	const onResize = () => {
+		pty.resize?.(terminalCols(args.cols), terminalRows(args.rows));
+	};
+	const rawState = setRawMode(true);
+	const outputDisposable = pty.onData(onData);
+	process.stdin.on("data", onInput);
+	process.on("SIGWINCH", onResize);
+	return () => {
+		dispose(outputDisposable);
+		process.stdin.off("data", onInput);
+		process.off("SIGWINCH", onResize);
+		setRawMode(rawState);
+	};
+}
+function toPtyLike(pty) {
+	return {
+		write: (data) => pty.write(typeof data === "string" ? data : Buffer.from(data).toString()),
+		resize: (cols, rows) => pty.resize(cols, rows),
+		kill: (signal) => pty.kill(signal),
+		onData: (listener) => pty.onData(listener),
+		onExit: (listener) => pty.onExit(listener)
+	};
+}
+function terminalCols(fallback = 80) {
+	return process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : fallback;
+}
+function terminalRows(fallback = 24) {
+	return process.stdout.rows && process.stdout.rows > 0 ? process.stdout.rows : fallback;
+}
+function parsePositiveInt(value, name) {
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`invalid ${name}: ${value}`);
+	return parsed;
+}
+function mergeEnv(base, override) {
+	const env = {};
+	for (const [key, value] of Object.entries(process.env)) if (typeof value === "string") env[key] = value;
+	for (const [key, value] of Object.entries(base)) env[key] = value;
+	for (const [key, value] of Object.entries(override)) env[key] = value;
+	return env;
+}
+function setRawMode(enabled) {
+	if (!process.stdin.isTTY) return false;
+	const stdin = process.stdin;
+	const wasRaw = Boolean(stdin.isRaw);
+	process.stdin.setRawMode(enabled);
+	process.stdin.resume();
+	return wasRaw;
+}
+function dispose(disposable) {
+	if (!disposable) return;
+	if (typeof disposable === "function") disposable();
+	else disposable.dispose();
+}
+function isHelp$1(arg) {
+	return arg === "-h" || arg === "--help" || arg === "help";
+}
+//#endregion
+//#region src/script/commands.ts
+function readScriptArtifactCommandsPath(path) {
+	const manifestCommands = readManifestBackedCommands(path);
+	if (manifestCommands) return manifestCommands;
+	const resolved = resolveScriptRunSummaryPath(path);
+	const summaryManifest = findScriptSummaryManifest(resolved);
+	if (summaryManifest) {
+		validateScriptManifest(summaryManifest.manifest, summaryManifest.manifestPath);
+		return createScriptArtifactCommands(resolved, relocateScriptManifestCommands(summaryManifest.manifest, summaryManifest.manifestPath), { manifestPath: summaryManifest.manifestPath });
+	}
+	return createScriptArtifactCommands(resolved, readScriptRunSummaryPath(resolved).commands);
+}
+function formatScriptArtifactCommandLines(result) {
+	return [
+		`kind=${result.kind}`,
+		`path=${result.path}`,
+		result.manifestPath ? `manifest=${result.manifestPath}` : null,
+		...Object.entries(result.commands).map(([name, command]) => `${name}: ${formatArgv(command.argv)}`)
+	].filter((line) => line !== null);
+}
+function selectScriptArtifactCommand(result, name) {
+	if (!isScriptCommandName(name)) {
+		const available = Object.keys(result.commands).sort().join(", ");
+		throw new Error(`unknown script artifact command: ${name}${available ? ` (available: ${available})` : ""}`);
+	}
+	const command = result.commands[name];
+	return {
+		path: result.path,
+		kind: result.kind,
+		manifestPath: result.manifestPath,
+		cwd: result.cwd,
+		name,
+		command,
+		shell: result.shell[name] ?? formatArgv(command.argv)
+	};
+}
+function validateScriptCommandArgv(argv, name = "<unknown>") {
+	const [binary, subcommand] = argv;
+	if (binary !== "ptywright" || subcommand !== "run-all") throw new Error(`command ${name} argv must start with a supported ptywright script command`);
+}
+function createScriptArtifactCommands(path, commands, options = {}) {
+	return {
+		path,
+		kind: "run-summary",
+		manifestPath: options.manifestPath,
+		cwd: process.cwd(),
+		shell: Object.fromEntries(Object.entries(commands).map(([name, command]) => [name, formatArgv(command.argv)])),
+		commands
+	};
+}
+function readManifestBackedCommands(path) {
+	const manifestPath = resolveScriptManifestPath(path);
+	if (!manifestPath.endsWith("ptywright-script.manifest.json")) return null;
+	if (!existsSync(manifestPath)) return null;
+	const manifest = readScriptManifestPath(manifestPath);
+	validateScriptManifest(manifest, manifestPath);
+	return createScriptArtifactCommands(resolveManifestPrimaryPath$1(manifest, manifestPath), relocateScriptManifestCommands(manifest, manifestPath), { manifestPath });
+}
+function isScriptCommandName(name) {
+	return name === "runAll" || name === "updateGoldens";
+}
+//#endregion
+//#region src/script/inspect.ts
+function inspectScriptArtifactPath(path) {
+	const manifestPath = resolveScriptManifestPath(path);
+	const hasManifest = existsSync(manifestPath);
+	const commands = readScriptArtifactCommandsPath(hasManifest ? manifestPath : path);
+	const manifest = hasManifest ? maybeReadManifest(manifestPath) : void 0;
+	if (!manifest) readScriptRunSummaryPath(path);
+	return {
+		path: resolve(process.cwd(), path),
+		targetPath: hasManifest ? manifestPath : resolve(process.cwd(), path),
+		kind: hasManifest ? "manifest" : "run-summary",
+		ok: true,
+		commands,
+		manifest
+	};
+}
+function formatScriptInspectLines(result) {
+	const lines = [
+		"ok script-inspect",
+		`kind=${result.kind}`,
+		`path=${result.targetPath}`
+	];
+	if (result.manifest) {
+		lines.push(`manifest=${result.manifest.path}`, `manifestFiles=${result.manifest.files.totalCount}`, `manifestBytes=${result.manifest.files.totalBytes}`, `total=${result.manifest.totalCount}`, `failures=${result.manifest.failureCount}`);
+		for (const [kind, count] of Object.entries(result.manifest.files.byKind)) lines.push(`manifestFileKind.${kind}=${count}`);
+		if (result.manifest.files.failures.length > 0) lines.push(...result.manifest.files.failures.map((file) => `manifestFileFailure=${file.path} kind=${file.kind}${file.role ? ` role=${file.role}` : ""}`));
+	}
+	if (result.commands) {
+		if (result.commands.manifestPath) lines.push(`commandsManifest=${result.commands.manifestPath}`);
+		lines.push(`commands=${Object.keys(result.commands.commands).sort().join(",")}`, ...formatScriptArtifactCommandLines(result.commands).filter((line) => !line.startsWith("kind=") && !line.startsWith("path=")).map((line) => `command.${line}`));
+	}
+	return lines;
+}
+function maybeReadManifest(path) {
+	if (basename(path) !== "ptywright-script.manifest.json") return void 0;
+	const manifest = readScriptManifestPath(path);
+	validateScriptManifest(manifest, path);
+	const byKind = {};
+	let totalBytes = 0;
+	const failures = [];
+	for (const file of manifest.files) {
+		byKind[file.kind] = (byKind[file.kind] ?? 0) + 1;
+		totalBytes += file.bytes;
+		if (file.ok === false) failures.push({
+			path: file.path,
+			kind: file.kind,
+			role: file.role
+		});
+	}
+	return {
+		path,
+		ok: manifest.ok,
+		rootDir: manifest.rootDir,
+		primaryPath: resolveManifestPrimaryPath$1(manifest, path),
+		generatedAt: manifest.generatedAt,
+		totalCount: manifest.totalCount,
+		failureCount: manifest.failureCount,
+		files: {
+			totalCount: manifest.files.length,
+			totalBytes,
+			byKind: Object.fromEntries(Object.entries(byKind).sort(([a], [b]) => a.localeCompare(b))),
+			failures
+		}
+	};
+}
+//#endregion
+//#region src/cli.ts
+function usage() {
+	return [
+		"ptywright <command>",
+		"",
+		"Commands:",
+		"  mcp                 Start the MCP server over stdio (default)",
+		"  mcp-http            Start the MCP server over Streamable HTTP",
+		"  agent run <file>    Run a browser-hosted terminal-agent flow",
+		"  agent record <file> --out <file>  Record browser interactions into a flow",
+		"  agent replay <run>  Replay a recorded terminal-agent flow without AI",
+		"  agent promote <run> Promote a run/cassette into the committed cassette suite",
+		"  agent replay-all [dir]  Replay all agent cassettes/run records in a directory",
+		"  agent rerun <summary>  Rerun from agent replay/check/promote summary metadata",
+		"  agent commands <artifact>  Print replay/update argv from an agent artifact",
+		"  agent inspect <artifact|dir>  Inspect validation, files, and commands for an agent artifact",
+		"  agent exec <artifact> --command <name>  Execute one command from an agent artifact",
+		"  agent check [dir]  Validate and replay committed agent cassettes",
+		"  agent validate <path>  Validate agent flow/cassette/run-record/summary artifacts",
+		"  agent init <flavor> <file>  Write a starter agent flow spec",
+		"  pty record --out <file> -- <command> [args...]  Record a raw PTY cassette",
+		"  pty replay <file>     Replay a raw PTY cassette without rerunning the command",
+		"  pty inspect <file>    Inspect a raw PTY cassette",
+		"  pty validate <file>   Validate a raw PTY cassette",
+		"  run <file>           Run one script (JSON/TS) and write artifacts",
+		"  run-all [dir]        Run all scripts in a directory and write a suite report",
+		"  script commands <summary|dir>  Print replay/update argv from a script run summary",
+		"  script inspect <summary|dir>  Inspect validation, files, and commands for a script artifact",
+		"  script exec <summary|dir> --command <name>  Execute one command from a script summary",
+		"  script validate <summary|dir>  Validate a script run summary artifact",
+		"  help                Show help",
+		"",
+		"Run options:",
+		"  --artifacts-dir <dir>    Override artifacts directory",
+		"  --steps <module.ts>      Inject custom step handlers",
+		"  --update-goldens         Update golden snapshots",
+		"",
+		"Run-all options:",
+		"  --dir <dir>              Directory to scan (default: scripts)",
+		"  --artifacts-root <dir>   Suite artifacts root (default: .tmp/run-all)",
+		"  --steps <module.ts>      Inject custom step handlers",
+		"  --update-goldens         Update golden snapshots",
+		"",
+		"Script artifact options:",
+		"  --command <name>         Select a reusable command (runAll|updateGoldens)",
+		"  --json                   Print machine-readable script artifact output",
+		"",
+		"Agent options:",
+		"  --artifacts-dir <dir>    Override agent run artifact directory",
+		"  --cassette-dir <dir>     Committed cassette directory for promote/check",
+		"  --snapshot-dir <dir>     Snapshot directory for promoted cassettes",
+		"  --out <file>             Output path for agent record",
+		"  --duration-ms <ms>       Recording window duration",
+		"  --artifacts-root <dir>   Override agent replay-all artifact root",
+		"  --command <name>          Print one agent artifact command by name",
+		"  --update-snapshots       Update terminal/DOM snapshots",
+		"  --headed                 Show the browser while running",
+		"  --json                   Print machine-readable agent check output",
+		"",
+		"PTY cassette options:",
+		"  --out <file>             Output cassette JSON path",
+		"  --cols <n> / --rows <n>  Terminal size for recording",
+		"  --term <name>            TERM/name value (default: xterm-256color)",
+		"  --backend <name>         auto|bun-terminal|bun-pty",
+		"  --speed <n>              Replay timing multiplier; 0 means instant",
+		"",
+		"MCP options:",
+		"  --caps <list>            Capabilities: all|core|debug|script|recording",
+		"",
+		"MCP HTTP options (mcp-http):",
+		"  --host <host>            Bind host (default: 127.0.0.1)",
+		"  --port <port>            Bind port (default: 3000)",
+		"  --allowed-origins <list> Comma/space separated Origin allowlist",
+		"  --no-cors                Disable CORS headers"
+	].join("\n");
+}
+function isHelp(arg) {
+	return arg === "-h" || arg === "--help" || arg === "help";
+}
+function logLines(lines, stderr) {
+	const filtered = lines.map((l) => l?.trim()).filter(Boolean);
+	for (const line of filtered) (stderr ? console.error : console.log)(line);
+}
+function parseCaps(value) {
+	const parts = value.split(/[\s,]+/g).map((p) => p.trim().toLowerCase()).filter(Boolean);
+	const out = [];
+	for (const p of parts) if (p === "all") out.push("all");
+	else if (p === "core") out.push("core");
+	else if (p === "debug") out.push("debug");
+	else if (p === "script" || p === "scripts" || p === "runner" || p === "run") out.push("script");
+	else if (p === "recording" || p === "record" || p === "rec") out.push("recording");
+	else throw new Error(`unknown capability: ${p}`);
+	return out;
+}
+function parseRunArgs(argv) {
+	const out = { updateGoldens: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (!out.scriptPath && arg && !arg.startsWith("-")) {
+			out.scriptPath = arg;
+			continue;
+		}
+		if (arg === "--artifacts-dir" && next) {
+			out.artifactsDir = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--steps" && next) {
+			out.stepsPath = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--update-goldens") {
+			out.updateGoldens = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	if (!out.scriptPath) throw new Error("missing <file>\n\n" + usage());
+	return out;
+}
+function parseRunAllArgs(argv) {
+	const out = { updateGoldens: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (!out.dir && arg && !arg.startsWith("-")) {
+			out.dir = arg;
+			continue;
+		}
+		if (arg === "--dir" && next) {
+			out.dir = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--artifacts-root" && next) {
+			out.artifactsRoot = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--steps" && next) {
+			out.stepsPath = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--update-goldens") {
+			out.updateGoldens = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	return out;
+}
+async function cmdMcp(argv) {
+	let capabilities;
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (isHelp(arg)) {
+			console.log(usage());
+			return;
+		}
+		if (arg === "--caps" && next) {
+			capabilities = parseCaps(next);
+			i += 1;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	const { server, sessions } = createPtywrightServer({ capabilities });
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	function shutdown() {
+		sessions.closeAll();
+		server.close();
+	}
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+}
+async function cmdMcpHttp(argv) {
+	let capabilities;
+	let hostname;
+	let port;
+	let allowedOrigins;
+	let cors = true;
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (isHelp(arg)) {
+			console.log(usage());
+			return;
+		}
+		if (arg === "--caps" && next) {
+			capabilities = parseCaps(next);
+			i += 1;
+			continue;
+		}
+		if ((arg === "--host" || arg === "--hostname") && next) {
+			hostname = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--port" && next) {
+			const value = Number.parseInt(next, 10);
+			if (!Number.isFinite(value) || value < 0) throw new Error(`invalid --port: ${next}`);
+			port = value;
+			i += 1;
+			continue;
+		}
+		if (arg === "--allowed-origins" && next) {
+			allowedOrigins = next.split(/[\s,]+/g).map((v) => v.trim()).filter(Boolean);
+			i += 1;
+			continue;
+		}
+		if (arg === "--no-cors") {
+			cors = false;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	const handle = await startPtywrightHttpServer({
+		hostname,
+		port,
+		capabilities,
+		allowedOrigins,
+		cors
+	});
+	console.log(`listening ${handle.url}`);
+	console.log(`health http://${handle.hostname}:${handle.port}/health`);
+	function shutdown() {
+		handle.close();
+	}
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+}
+async function cmdRun(argv) {
+	const args = parseRunArgs(argv);
+	const result = await runScriptPath(args.scriptPath, {
+		artifactsDir: args.artifactsDir,
+		updateGoldens: args.updateGoldens,
+		stepsPath: args.stepsPath
+	});
+	if (!result.ok) {
+		logLines([
+			result.error,
+			result.artifactsDir ? `artifacts=${result.artifactsDir}` : null,
+			result.reportPath ? `report=${result.reportPath}` : null,
+			result.castPath ? `cast=${result.castPath}` : null,
+			result.failureArtifacts?.lastViewPath ? `last=${result.failureArtifacts.lastViewPath}` : null,
+			result.failureArtifacts?.errorPath ? `error=${result.failureArtifacts.errorPath}` : null
+		], true);
+		return 1;
+	}
+	logLines([
+		`ok artifacts=${result.artifactsDir}`,
+		result.reportPath ? `report=${result.reportPath}` : null,
+		result.castPath ? `cast=${result.castPath}` : null
+	], false);
+	return 0;
+}
+async function cmdRunAll(argv) {
+	const args = parseRunAllArgs(argv);
+	const result = await runAllScripts({
+		dir: args.dir,
+		artifactsRoot: args.artifactsRoot,
+		stepsPath: args.stepsPath,
+		updateGoldens: args.updateGoldens
+	});
+	const failures = result.entries.filter((e) => !e.result.ok);
+	if (failures.length === 0) {
+		console.log(`ok count=${result.entries.length} dir=${result.dir}\nreport=${result.reportPath}\nsummary=${result.summaryPath}`);
+		return 0;
+	}
+	console.error(`failed count=${failures.length}/${result.entries.length} dir=${result.dir}\nreport=${result.reportPath}\nsummary=${result.summaryPath}`);
+	for (const f of failures) {
+		if (f.result.ok) continue;
+		console.error(`- ${f.filePath}: ${f.result.error}`);
+		if (f.result.failureArtifacts) {
+			console.error(`  artifacts=${f.result.artifactsDir ?? ""}`);
+			console.error(`  last=${f.result.failureArtifacts.lastViewPath}`);
+			console.error(`  error=${f.result.failureArtifacts.errorPath}`);
+		}
+	}
+	return 1;
+}
+function parseScriptArgs(argv) {
+	const [mode, ...rest] = argv;
+	if (mode !== "commands" && mode !== "exec" && mode !== "inspect" && mode !== "validate") throw new Error("missing script subcommand: commands|inspect|exec|validate\n\n" + usage());
+	const out = { json: false };
+	for (let i = 0; i < rest.length; i += 1) {
+		const arg = rest[i];
+		const next = rest[i + 1];
+		if (!out.path && arg && !arg.startsWith("-")) {
+			out.path = arg;
+			continue;
+		}
+		if (arg === "--command" && next) {
+			out.commandName = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--json") {
+			out.json = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	if (!out.path) throw new Error(`missing ${mode === "validate" ? "<summary|dir>" : "<artifact>"} for script ${mode}\n\n` + usage());
+	if (mode === "exec" && !out.commandName) throw new Error(`missing --command <name> for script exec\n\n` + usage());
+	return {
+		mode,
+		path: out.path,
+		commandName: out.commandName,
+		json: out.json
+	};
+}
+async function cmdScript(argv) {
+	const args = parseScriptArgs(argv);
+	if (args.mode === "validate") {
+		const manifestPath = resolveScriptManifestPath(args.path);
+		const hasManifest = manifestPath.endsWith("ptywright-script.manifest.json") ? readOptionalScriptManifest(manifestPath) : null;
+		const summaryPath = hasManifest ? resolveScriptRunSummaryPath(hasManifest.primaryPath) : resolveScriptRunSummaryPath(args.path);
+		if (hasManifest) validateScriptManifest(hasManifest, manifestPath);
+		const summary = readScriptRunSummaryPath(summaryPath);
+		if (args.json) logLines([JSON.stringify({
+			ok: true,
+			kind: hasManifest ? "manifest" : "run-summary",
+			path: summaryPath,
+			manifestPath: hasManifest ? manifestPath : void 0,
+			totalCount: summary.totalCount,
+			failureCount: summary.failureCount
+		}, null, 2)], false);
+		else logLines([
+			"ok script-summary",
+			`path=${summaryPath}`,
+			hasManifest ? `manifest=${manifestPath}` : null,
+			`count=${summary.totalCount}`,
+			`failures=${summary.failureCount}`
+		], false);
+		return 0;
+	}
+	if (args.mode === "inspect") {
+		const result = inspectScriptArtifactPath(args.path);
+		if (args.json) logLines([JSON.stringify(result, null, 2)], false);
+		else logLines(formatScriptInspectLines(result), false);
+		return 0;
+	}
+	const result = readScriptArtifactCommandsPath(args.path);
+	if (args.mode === "commands") {
+		if (args.commandName) {
+			const selected = selectScriptArtifactCommand(result, args.commandName);
+			if (args.json) logLines([JSON.stringify(selected, null, 2)], false);
+			else logLines([selected.shell], false);
+			return 0;
+		}
+		if (args.json) logLines([JSON.stringify(result, null, 2)], false);
+		else logLines(formatScriptArtifactCommandLines(result), false);
+		return 0;
+	}
+	const selected = selectScriptArtifactCommand(result, args.commandName);
+	const commandArgv = selected.command.argv;
+	validateScriptCommandArgv(commandArgv, selected.name);
+	const [, subcommand, ...rest] = commandArgv;
+	if (subcommand === "run-all") return cmdRunAll(rest);
+	throw new Error(`unsupported script artifact command: ${subcommand ?? ""}`);
+}
+function readOptionalScriptManifest(path) {
+	try {
+		return readScriptManifestPath(path);
+	} catch {
+		return null;
+	}
+}
+function parseAgentArgs(argv) {
+	const [mode, ...rest] = argv;
+	if (mode !== "run" && mode !== "replay" && mode !== "promote" && mode !== "replay-all" && mode !== "rerun" && mode !== "commands" && mode !== "inspect" && mode !== "exec" && mode !== "init" && mode !== "record" && mode !== "validate" && mode !== "check") throw new Error("missing agent subcommand: run|record|replay|promote|replay-all|rerun|commands|inspect|exec|check|validate|init\n\n" + usage());
+	const out = {
+		updateSnapshots: false,
+		headed: false,
+		json: false
+	};
+	for (let i = 0; i < rest.length; i += 1) {
+		const arg = rest[i];
+		const next = rest[i + 1];
+		if (mode === "init" && !out.flavor && arg && !arg.startsWith("-")) {
+			out.flavor = parseAgentFlavor(arg);
+			continue;
+		}
+		if (arg === "--artifacts-root" && next) {
+			out.artifactsRoot = next;
+			i += 1;
+			continue;
+		}
+		if ((arg === "--cassette-dir" || arg === "--dir") && next) {
+			out.cassetteDir = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--snapshot-dir" && next) {
+			out.snapshotDir = next;
+			i += 1;
+			continue;
+		}
+		if (!out.path && arg && !arg.startsWith("-")) {
+			out.path = arg;
+			continue;
+		}
+		if (arg === "--artifacts-dir" && next) {
+			out.artifactsDir = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--out" && next) {
+			out.outPath = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--duration-ms" && next) {
+			const value = Number.parseInt(next, 10);
+			if (!Number.isFinite(value) || value < 0) throw new Error(`invalid --duration-ms: ${next}`);
+			out.durationMs = value;
+			i += 1;
+			continue;
+		}
+		if (arg === "--command" && next) {
+			out.commandName = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--update-snapshots") {
+			out.updateSnapshots = true;
+			continue;
+		}
+		if (arg === "--headed") {
+			out.headed = true;
+			continue;
+		}
+		if (arg === "--json") {
+			out.json = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	if (mode === "init" && !out.flavor) throw new Error(`missing <flavor> for agent init\n\n` + usage());
+	if (!out.path && mode !== "replay-all" && mode !== "check") throw new Error(`missing ${mode === "rerun" ? "<summary>" : mode === "commands" || mode === "inspect" || mode === "exec" ? "<artifact>" : "<file>"} for agent ${mode}\n\n` + usage());
+	if (mode === "record" && !out.outPath) throw new Error(`missing --out <file> for agent record\n\n` + usage());
+	if (mode === "exec" && !out.commandName) throw new Error(`missing --command <name> for agent exec\n\n` + usage());
+	return {
+		mode,
+		path: out.path,
+		flavor: out.flavor,
+		artifactsDir: out.artifactsDir,
+		artifactsRoot: out.artifactsRoot,
+		cassetteDir: out.cassetteDir,
+		snapshotDir: out.snapshotDir,
+		outPath: out.outPath,
+		durationMs: out.durationMs,
+		commandName: out.commandName,
+		updateSnapshots: out.updateSnapshots,
+		headed: out.headed,
+		json: out.json
+	};
+}
+async function cmdAgent(argv) {
+	const args = parseAgentArgs(argv);
+	if (args.mode === "init") {
+		const spec = createAgentTemplateSpec(args.flavor ?? "generic");
+		const path = args.path;
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify({
+			$schema: "../schemas/ptywright-agent.schema.json",
+			...spec
+		}, null, 2) + "\n", "utf8");
+		logLines([`ok wrote ${path}`], false);
+		return 0;
+	}
+	if (args.mode === "record") {
+		const result = await recordAgentSpecPath(args.path, {
+			outPath: args.outPath,
+			durationMs: args.durationMs,
+			headless: !args.headed
+		});
+		logLines([
+			`${result.ok ? "ok" : "failed"} record=${result.outPath}`,
+			`steps=${result.stepCount}`,
+			result.url ? `url=${result.url}` : null,
+			result.error ? `error=${result.error}` : null
+		], !result.ok);
+		return result.ok ? 0 : 1;
+	}
+	if (args.mode === "validate") {
+		const result = await validateAgentArtifactsPath(args.path, { preferManifestBundle: true });
+		if (args.json) {
+			logLines([JSON.stringify(result, null, 2)], false);
+			return result.ok ? 0 : 1;
+		}
+		const failures = result.entries.filter((entry) => !entry.ok);
+		logLines([
+			`${result.ok ? "ok" : "failed"} count=${result.totalCount} path=${result.path}`,
+			result.failureCount > 0 ? `failures=${result.failureCount}` : null,
+			...failures.flatMap((entry) => [
+				`- ${entry.filePath}`,
+				`  kind=${entry.kind}`,
+				entry.error ? `  error=${entry.error}` : null
+			])
+		], !result.ok);
+		return result.ok ? 0 : 1;
+	}
+	if (args.mode === "commands") {
+		const result = await readAgentArtifactCommandsPath(args.path);
+		const manifestPath = result.kind === "manifest" ? result.path : result.manifestPath;
+		if (manifestPath) {
+			const manifest = readAgentManifestPath(manifestPath);
+			validateAgentManifestCommandTargets(manifest, manifestPath);
+			validateAgentManifestFiles(manifest, manifestPath);
+		}
+		if (args.commandName) {
+			const selected = selectAgentArtifactCommand(result, args.commandName);
+			if (args.json) logLines([JSON.stringify(selected, null, 2)], false);
+			else logLines([selected.shell], false);
+			return 0;
+		}
+		if (args.json) logLines([JSON.stringify(result, null, 2)], false);
+		else logLines(formatAgentArtifactCommandLines(result), false);
+		return 0;
+	}
+	if (args.mode === "inspect") {
+		const result = await inspectAgentArtifactPath(args.path);
+		if (args.json) logLines([JSON.stringify(result, null, 2)], false);
+		else logLines(formatAgentInspectLines(result), !result.ok);
+		return result.ok ? 0 : 1;
+	}
+	if (args.mode === "exec") {
+		const result = await readAgentArtifactCommandsPath(args.path);
+		const manifestPath = result.kind === "manifest" ? result.path : result.manifestPath;
+		if (manifestPath) {
+			const manifest = readAgentManifestPath(manifestPath);
+			validateAgentManifestCommandTargets(manifest, manifestPath);
+			validateAgentManifestFiles(manifest, manifestPath);
+		}
+		const selected = selectAgentArtifactCommand(result, args.commandName);
+		const argv = selected.command.argv;
+		validateAgentCommandArgv(argv, selected.name);
+		const [, , subcommand, ...rest] = argv;
+		return cmdAgent([subcommand ?? "", ...rest]);
+	}
+	if (args.mode === "check") {
+		const result = await checkAgentRegression({
+			cassetteDir: args.path ?? args.cassetteDir,
+			artifactsRoot: args.artifactsRoot,
+			headless: !args.headed,
+			updateSnapshots: args.updateSnapshots
+		});
+		if (args.json) logLines([JSON.stringify(formatAgentCheckJson(result), null, 2)], false);
+		else logLines(formatAgentCheckLines(result), !result.ok);
+		return result.ok ? 0 : 1;
+	}
+	if (args.mode === "promote") {
+		const result = await promoteAgentCassette({
+			sourcePath: args.path,
+			cassetteDir: args.cassetteDir,
+			snapshotDir: args.snapshotDir,
+			artifactsRoot: args.artifactsRoot,
+			headless: !args.headed,
+			updateSnapshots: args.updateSnapshots
+		});
+		if (args.json) logLines([JSON.stringify(formatAgentPromoteSummary(result), null, 2)], false);
+		else logLines(formatAgentPromoteLines(result), !result.ok);
+		return result.ok ? 0 : 1;
+	}
+	if (args.mode === "rerun") {
+		const rerun = await rerunAgentSummary({
+			path: args.path,
+			artifactsRoot: args.artifactsRoot,
+			headless: !args.headed,
+			updateSnapshots: args.updateSnapshots
+		});
+		if (rerun.kind === "check-summary") {
+			if (args.json) logLines([JSON.stringify(formatAgentCheckJson(rerun.result), null, 2)], false);
+			else logLines(formatAgentCheckLines(rerun.result), !rerun.result.ok);
+			return rerun.result.ok ? 0 : 1;
+		}
+		if (rerun.kind === "promote-summary") {
+			if (args.json) logLines([JSON.stringify(formatAgentPromoteSummary(rerun.result), null, 2)], false);
+			else logLines(formatAgentPromoteLines(rerun.result), !rerun.result.ok);
+			return rerun.result.ok ? 0 : 1;
+		}
+		const failures = rerun.result.entries.filter((entry) => !entry.result.ok);
+		if (args.json) {
+			logLines([JSON.stringify(formatAgentReplaySummary(rerun.result), null, 2)], false);
+			return failures.length === 0 ? 0 : 1;
+		}
+		logLines([
+			`${failures.length === 0 ? "ok" : "failed"} rerun=${rerun.kind}`,
+			`count=${rerun.result.entries.length}`,
+			`dir=${rerun.result.dir}`,
+			`report=${rerun.result.reportPath}`,
+			`summary=${rerun.result.summaryPath}`,
+			...failures.flatMap((entry) => [`- ${entry.filePath}`, ...entry.result.errors.map((error) => `  error=${error}`)])
+		], failures.length > 0);
+		return failures.length === 0 ? 0 : 1;
+	}
+	if (args.mode === "replay-all") {
+		const result = await replayAllAgentRecords({
+			dir: args.path,
+			artifactsRoot: args.artifactsRoot,
+			headless: !args.headed,
+			updateSnapshots: args.updateSnapshots
+		});
+		const failures = result.entries.filter((entry) => !entry.result.ok);
+		if (args.json) {
+			logLines([JSON.stringify(formatAgentReplaySummary(result), null, 2)], false);
+			return failures.length === 0 ? 0 : 1;
+		}
+		if (failures.length === 0) {
+			logLines([
+				`ok count=${result.entries.length} dir=${result.dir}`,
+				`report=${result.reportPath}`,
+				`summary=${result.summaryPath}`
+			], false);
+			return 0;
+		}
+		logLines([
+			`failed count=${failures.length}/${result.entries.length} dir=${result.dir}`,
+			`report=${result.reportPath}`,
+			`summary=${result.summaryPath}`,
+			...failures.flatMap((entry) => [`- ${entry.filePath}`, ...entry.result.errors.map((error) => `  error=${error}`)])
+		], true);
+		return 1;
+	}
+	const options = {
+		artifactsDir: args.artifactsDir,
+		updateSnapshots: args.updateSnapshots,
+		headless: !args.headed
+	};
+	const result = args.mode === "run" ? await runAgentSpecPath(args.path, options) : await replayAgentRecordPath(args.path, options);
+	if (args.json) {
+		logLines([JSON.stringify(readAgentRunRecordPath(result.recordPath), null, 2)], false);
+		return result.ok ? 0 : 1;
+	}
+	logLines([
+		`${result.ok ? "ok" : "failed"} agent=${result.name}`,
+		`report=${result.reportPath}`,
+		`record=${result.recordPath}`,
+		`flow=${result.flowPath}`,
+		`cassette=${result.cassettePath}`,
+		`snapshots=${result.snapshotDir}`,
+		`mode=${result.mode}`,
+		`frames=${result.cassetteFrameCount}`,
+		result.replayCommand ? `replay=${result.replayCommand}` : null,
+		...result.errors.map((error) => `error=${error}`)
+	], !result.ok);
+	return result.ok ? 0 : 1;
+}
+function parseAgentFlavor(value) {
+	if (value === "codex" || value === "claude" || value === "droid" || value === "generic") return value;
+	if (value === "droidx") return "droid";
+	throw new Error(`unknown agent flavor: ${value}`);
+}
+async function main(argv = process.argv.slice(2)) {
+	const [command, ...rest] = argv;
+	if (!command) {
+		await cmdMcp([]);
+		return;
+	}
+	if (isHelp(command)) {
+		console.log(usage());
+		return;
+	}
+	if (command === "mcp") {
+		await cmdMcp(rest);
+		return;
+	}
+	if (command === "mcp-http") {
+		await cmdMcpHttp(rest);
+		return;
+	}
+	if (command === "agent") {
+		process.exitCode = await cmdAgent(rest);
+		return;
+	}
+	if (command === "pty") {
+		process.exitCode = await cmdPty(rest);
+		return;
+	}
+	if (command === "run") {
+		process.exitCode = await cmdRun(rest);
+		return;
+	}
+	if (command === "run-all") {
+		process.exitCode = await cmdRunAll(rest);
+		return;
+	}
+	if (command === "script") {
+		process.exitCode = await cmdScript(rest);
+		return;
+	}
+	throw new Error(`unknown command: ${command}\n\n` + usage());
+}
+if (import.meta.main) try {
+	await main();
+} catch (error) {
+	console.error(error.message);
+	process.exitCode = 1;
+}
+//#endregion
+export { main as t };