ccqa 1.46.1 → 1.47.1

package/dist/diagnose-CSQzwS5f.mjs

@@ -0,0 +1,2222 @@
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { ZodError, z } from "zod";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/runtime/env-vars.ts
+const ENV_VAR_RE = /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g;
+const ANY_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+const BRACED_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+* Replace every `$NAME` / `${NAME}` reference in `value` using `lookup`. When
+* `lookup` returns `undefined`, the original reference text is preserved
+* (callers that want empty-string substitution should wrap with `?? ""`).
+*/
+function substituteVars(value, lookup) {
+	ANY_VAR_RE.lastIndex = 0;
+	return value.replace(ANY_VAR_RE, (match, braced, plain) => {
+		const replacement = lookup(braced ?? plain ?? "");
+		return replacement === void 0 ? match : replacement;
+	});
+}
+/**
+* Iterate every `${NAME}` / `$NAME` reference name (case-insensitive form)
+* appearing in `value`. Used by callers that want to enumerate refs without
+* also substituting, e.g. the env-scrub map builder. The reference name
+* grammar is the canonical one shared with `substituteVars`.
+*/
+function* iterEnvRefNames(value) {
+	ANY_VAR_RE.lastIndex = 0;
+	let m;
+	while ((m = ANY_VAR_RE.exec(value)) !== null) {
+		const name = m[1] ?? m[2];
+		if (name) yield name;
+	}
+}
+/**
+* Resolve every `$VAR` / `${VAR}` reference against `overrides`, then the
+* current process env. `overrides` carries values an invoker injects into a
+* child process (e.g. CCQA_RUN_ID), which beat the parent env there.
+*
+* Missing variables expand to the empty string, mirroring `sh` behaviour.
+* Throwing would force ccqa to be invoked with every var set even for
+* unused blocks, which is more user-hostile than letting the test fail
+* downstream with a clearer message ("login form rejected: empty password").
+*/
+function resolveEnvRefs(value, overrides = {}) {
+	return value.replace(ENV_VAR_RE, (_, braced, plain) => {
+		const name = braced ?? plain ?? "";
+		return overrides[name] ?? process.env[name] ?? "";
+	});
+}
+/**
+* Embed `$VAR` / `${VAR}` as a JS template-literal expression that reads
+* `process.env.VAR ?? ""` at runtime. Used by `ccqa generate` so the test
+* script never bakes in the secret value.
+*
+* Returns a JavaScript string-literal expression (template literal when env
+* refs are present, plain string literal otherwise).
+*
+* Examples:
+*   "${PASSWORD}"             -> '`${process.env.PASSWORD ?? ""}`'
+*   "user-${SUFFIX}@x.com"    -> '`user-${process.env.SUFFIX ?? ""}@x.com`'
+*   "literal value"           -> '"literal value"'
+*/
+function envRefsToJsExpression(value) {
+	return refsToJsExpression(value, () => null);
+}
+/**
+* Generalised version of `envRefsToJsExpression`. Each `$NAME` / `${NAME}`
+* reference in `value` is passed to `nameToExpr(name)` first:
+*
+* - If it returns a string, that string is interpolated as a JS expression
+*   (no quoting / no `?? ""` wrap — the caller decides the shape).
+* - If it returns `null`, the reference is treated as a missing env var
+*   and expands to `process.env.<NAME> ?? ""` (the legacy behaviour).
+*
+* Used by the block codegen path: param names map to `params.<name>`,
+* everything else falls through to `process.env.X ?? ""`.
+*/
+function refsToJsExpression(value, nameToExpr, refRe = ANY_VAR_RE) {
+	refRe.lastIndex = 0;
+	if (!refRe.test(value)) return JSON.stringify(value);
+	const escaped = value.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, (_match, offset, source) => {
+		const probe = new RegExp(refRe.source, "g");
+		let m;
+		while ((m = probe.exec(source)) !== null) if (m.index === offset) return "${";
+		return "\\${";
+	});
+	refRe.lastIndex = 0;
+	return `\`${escaped.replace(refRe, (_match, braced, plain) => {
+		const name = braced ?? plain ?? "";
+		const expr = nameToExpr(name);
+		return expr !== null ? `\${${expr}}` : `\${process.env.${name} ?? ""}`;
+	})}\``;
+}
+/** `${VAR}` only. For prose, where a bare `$WORD` is a word and not a reference. */
+function bracedRefsToJsExpression(value) {
+	return refsToJsExpression(value, () => null, BRACED_VAR_RE);
+}
+//#endregion
+//#region src/spec/yaml-schema.ts
+/**
+* An action step: one user-facing browser interaction. `instruction` and
+* `expected` are the natural-language description handed to Claude during
+* `ccqa trace`. URLs live inside `instruction`, either verbatim or via
+* `${ENV_VAR}` references (resolved at runtime).
+*/
+const ActionStepSchema = z.object({
+	instruction: z.string().min(1),
+	expected: z.string().min(1)
+}).strict();
+/**
+* An include step: invokes a reusable block (`.ccqa/blocks/<name>/spec.yaml`).
+* `params` values are plain strings; env refs (`${VAR}`) inside them are
+* resolved at expand time the same way step instructions are.
+*/
+const IncludeStepSchema = z.object({
+	include: z.string().min(1),
+	params: z.record(z.string(), z.string()).optional()
+}).strict();
+/**
+* A claim about the page decided by a model rather than by a selector match,
+* for output a run cannot predict. `from` narrows what it reads to one
+* element; omitted, the page's visible text. See docs/spec.md.
+*/
+const JudgeByLlmStepSchema = z.object({
+	judgeByLlm: z.string().min(1),
+	from: z.string().min(1).optional()
+}).strict();
+/**
+* A spec step is an action, an include, or a judge-by-LLM — discriminated by the
+* presence of the `include` / `judgeByLlm` key (see the predicates below).
+*/
+const StepSchema = z.union([
+	ActionStepSchema,
+	IncludeStepSchema,
+	JudgeByLlmStepSchema
+]);
+/**
+* Execution mode for `ccqa run`:
+*   - `deterministic` (default): vitest replays the recorded `test.spec.ts`.
+*   - `live`: Claude drives agent-browser per step (for fragile UIs where
+*     codegen is impractical). Cost ~$0.5 per spec.
+*/
+const SpecModeSchema = z.enum(["deterministic", "live"]);
+/**
+* A name a spec chooses that ccqa resolves to a path or looks up in a
+* registry. Restricted to a slug so it cannot escape a directory.
+*/
+function slug(what) {
+	return z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, `${what} must be a slug (letters, digits, '.', '_', '-'; no path separators)`);
+}
+/**
+* A saved browser session (cookies + localStorage) to restore before the spec
+* runs, resolved to `.ccqa/sessions/<profile>/<name>.json` at run time.
+*/
+const SessionNameSchema = slug("session name");
+/**
+* Sessions to restore before a `mode: live` spec runs: one name or a list,
+* always read back as a list. Multiple names are merged (their cookies +
+* localStorage are unioned) and restored together, so a spec can start
+* signed-in to several providers at once.
+*/
+const SessionFieldSchema = z.union([SessionNameSchema, z.array(SessionNameSchema).min(1)]).transform((v) => Array.isArray(v) ? v : [v]);
+/**
+* A generation-target id: which plugin turns this spec into runnable tests
+* (e.g. "agent-browser", "playwright", "runn"). Whether the id names a
+* registered target is the registry's responsibility, so new targets don't
+* require a schema change.
+*/
+const TargetIdSchema = slug("target");
+/** The built-in recorder-backed target. `mode:` / `session:` only apply to it. */
+const AGENT_BROWSER_TARGET = "agent-browser";
+/**
+* Top-level spec schema. `.strict()` rejects any unknown key.
+*
+* `mode:` and `session:` are agent-browser-only fields, enforced here when
+* `target:` names another target. When `target:` is omitted the effective
+* target comes from config (`defaultTarget`, falling back to agent-browser),
+* which this schema can't see — so mode/session pass parsing and the
+* post-resolution check is the target resolver's responsibility.
+*/
+const TestSpecSchema = z.object({
+	title: z.string().min(1),
+	disabled: z.boolean().optional(),
+	target: TargetIdSchema.optional(),
+	mode: SpecModeSchema.optional(),
+	session: SessionFieldSchema.optional(),
+	steps: z.array(StepSchema).min(1)
+}).strict().superRefine((spec, ctx) => {
+	if (spec.target === void 0 || spec.target === "agent-browser") return;
+	for (const key of ["mode", "session"]) if (spec[key] !== void 0) ctx.addIssue({
+		code: "custom",
+		path: [key],
+		message: `\`${key}\` only applies to the agent-browser target — remove it or drop \`target: ${spec.target}\``
+	});
+});
+/** Default mode when `mode:` is absent. */
+const DEFAULT_SPEC_MODE = "deterministic";
+/**
+* A block param declaration. `required` defaults to true; only explicit
+* `required: false` makes it optional. `secret: true` flags the value as
+* sensitive — codegen renders such values as `process.env.<NAME> ?? ""`
+* template literals so the secret never ends up baked into test.spec.ts.
+*/
+const BlockParamSchema = z.object({
+	name: z.string().min(1),
+	required: z.boolean().optional(),
+	secret: z.boolean().optional()
+}).strict();
+/**
+* Block schema. A block step is an action or a judge-by-LLM — nested blocks are
+* forbidden, so including a block from inside another block fails parsing here
+* (the parser maps the union's cryptic failure into a nested-block message).
+*/
+const BlockSpecSchema = z.object({
+	title: z.string().min(1),
+	params: z.array(BlockParamSchema).optional(),
+	steps: z.array(z.union([ActionStepSchema, JudgeByLlmStepSchema])).min(1)
+}).strict();
+/** Runtime predicates for the StepSchema union. */
+function isIncludeStep(step) {
+	return "include" in step;
+}
+function isJudgeByLlmStep(step) {
+	return "judgeByLlm" in step;
+}
+/** Returns true if a block param is required (default: true). */
+function isParamRequired(param) {
+	return param.required !== false;
+}
+//#endregion
+//#region src/spec/parser.ts
+/** The spec/block root (an `unrecognized_keys` issue there has an empty path). */
+const atRoot = (path) => path.length === 0;
+/** A block param entry — the issue path is `params.<index>`. */
+const atBlockParam = (path) => path.length === 2 && path[0] === "params" && typeof path[1] === "number";
+const UNREAD_PARAM_FIELD = "nothing reads it (a block param reaches the prompts as its name, required and secret only). Delete the line.";
+const REMOVED_FIELDS = {
+	relatedPaths: {
+		at: atRoot,
+		message: "which specs a change affects is now decided by `ccqa select-specs`, which reads the diff instead of a declared path list. Delete the field."
+	},
+	dummy: {
+		at: atBlockParam,
+		message: UNREAD_PARAM_FIELD
+	},
+	description: {
+		at: atBlockParam,
+		message: UNREAD_PARAM_FIELD
+	}
+};
+/** Parse a spec.yaml. Schema rejections are rewritten with actionable messages. */
+function parseTestSpec(content, source = "spec.yaml") {
+	const raw = parseYamlOrThrow(content, source);
+	try {
+		return TestSpecSchema.parse(raw);
+	} catch (e) {
+		throw enrichZodError(e, source, false, raw);
+	}
+}
+/**
+* Throw-suppressed sibling of `parseTestSpec`. Used by report-side helpers
+* that derive cosmetic data (title, step descriptions) from spec.yaml and
+* want a missing or malformed file to degrade silently rather than abort
+* the report.
+*/
+function tryParseTestSpec(yaml) {
+	if (!yaml) return null;
+	try {
+		return parseTestSpec(yaml);
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse a block's spec.yaml. Block-specific errors include the targeted
+* nested-block message (the underlying zod failure on an `include` key
+* inside a block step is hard to read).
+*/
+function parseBlockSpec(content, source = "block spec.yaml") {
+	const raw = parseYamlOrThrow(content, source);
+	try {
+		return BlockSpecSchema.parse(raw);
+	} catch (e) {
+		throw enrichZodError(e, source, true, raw);
+	}
+}
+function parseYamlOrThrow(content, source) {
+	try {
+		return parse(content);
+	} catch (e) {
+		throw new Error(`Failed to parse YAML (${source}): ${e.message}`);
+	}
+}
+function enrichZodError(error, source, isBlock, raw) {
+	if (!(error instanceof ZodError)) return error;
+	const lines = [`Invalid ${source}:`];
+	for (const issue of error.issues) for (const [path, message] of explain(issue, isBlock, raw)) lines.push(`  - ${path.join(".") || "(root)"}: ${message}`);
+	return new Error(lines.join("\n"));
+}
+const NESTED_BLOCK_MESSAGE = "Nested blocks are not supported — flatten by inlining the included block's steps into this block.";
+function explain(issue, isBlock, raw) {
+	const asIs = [[issue.path, humanizeIssue(issue, isBlock, raw)]];
+	if (issue.code !== "invalid_union" || !issue.errors?.length) return asIs;
+	if (isBlock && stepKind(raw, issue.path) === "include") return asIs;
+	const best = pickBranch(issue.errors, stepKind(raw, issue.path));
+	if (!best?.length) return asIs;
+	return best.map((b) => {
+		const path = [...issue.path, ...b.path];
+		return [path, humanizeIssue({
+			...b,
+			path
+		}, isBlock, raw)];
+	});
+}
+/** Which kind of step the author was writing, read from the key they used. */
+function stepKind(raw, path) {
+	const node = nodeAt(raw, path);
+	if (!isRecord(node)) return null;
+	for (const key of ["include", "judgeByLlm"]) if (key in node) return key;
+	return "instruction";
+}
+/**
+* The branch the author meant: the one that accepts the key they wrote. Any
+* other branch reports that key as unrecognized, which would tell them the
+* key they just used does not exist. Ties among the rest go to the branch
+* that recognized the most of what they wrote.
+*/
+function pickBranch(branches, kind) {
+	const accepts = kind === null ? branches : branches.filter((b) => !rejectsKey(b, kind));
+	return (accepts.length > 0 ? accepts : branches).reduce((a, b) => unknownKeyCount(a) <= unknownKeyCount(b) ? a : b);
+}
+function rejectsKey(issues, key) {
+	return issues.some((i) => Array.isArray(i.keys) && i.keys.includes(key));
+}
+function unknownKeyCount(issues) {
+	return issues.reduce((n, i) => n + (Array.isArray(i.keys) ? i.keys.length : 0), 0);
+}
+function humanizeIssue(issue, isBlock, raw) {
+	if (isBlock && issue.code === "invalid_union" && stepKind(raw, issue.path) === "include") return NESTED_BLOCK_MESSAGE;
+	if (issue.code === "unrecognized_keys") {
+		const keys = Array.isArray(issue.keys) ? issue.keys : [];
+		if (isBlock && keys.includes("include")) return NESTED_BLOCK_MESSAGE;
+		const removed = keys.filter((k) => REMOVED_FIELDS[k]?.at(issue.path));
+		const stillUnknown = keys.filter((k) => !REMOVED_FIELDS[k]?.at(issue.path));
+		const parts = removed.map((k) => `\`${k}\` is no longer part of the spec schema — ${REMOVED_FIELDS[k].message}`);
+		if (stillUnknown.length > 0) parts.push(`Unknown keys: ${stillUnknown.join(", ")}`);
+		return parts.join(" ");
+	}
+	return issue.message;
+}
+function nodeAt(raw, path) {
+	let node = raw;
+	for (const segment of path) {
+		if (!isRecord(node)) return void 0;
+		node = node[segment];
+	}
+	return node;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+//#endregion
+//#region src/spec/expand.ts
+/** Runtime predicates for the ExpandedStep union. */
+function isExpandedJudgeByLlmStep(step) {
+	return "judgeByLlm" in step;
+}
+function isExpandedActionStep(step) {
+	return !("judgeByLlm" in step);
+}
+function isJudgeBody(step) {
+	return "judgeByLlm" in step;
+}
+/**
+* Walk the spec's top-level steps, inlining any `- include: <block>` reference
+* as the block's own steps in order. The result is a flat `step-NN`-numbered
+* sequence — block boundaries survive only as the `source` tag, so trace and
+* codegen never need a separate block code path.
+*/
+function expandSpec(spec, options) {
+	const out = [];
+	let counter = 0;
+	const allocId = () => {
+		counter += 1;
+		return `step-${String(counter).padStart(2, "0")}`;
+	};
+	for (const step of spec.steps) if (isIncludeStep(step)) {
+		const block = resolveBlock(step.include, step.params ?? {}, options.blocks);
+		const substitute = (text) => substituteVars(text, block.lookup);
+		for (const blockStep of block.steps) out.push(expandStep(blockStep, allocId(), step.include, substitute));
+	} else out.push(expandStep(step, allocId(), "spec", (text) => text));
+	return out;
+}
+/**
+* `expandSpec` for a target that emits no judge call. A claim is refused by
+* name rather than dropped: one that goes unjudged is a test that passes
+* without testing. Blocks carry steps the spec does not name, which is why
+* this runs after expansion rather than in the schema.
+*/
+function expandActionSteps(spec, options, specKey, target) {
+	return expandSpec(spec, options).map((step) => {
+		if (isExpandedJudgeByLlmStep(step)) {
+			const from = step.source === "spec" ? "" : ` (from block \`${step.source}\`)`;
+			throw new Error(`${specKey}: step ${step.id}${from} uses \`judgeByLlm\`, but the "${target.id}" target cannot honour it — ${target.reason}`);
+		}
+		return step;
+	});
+}
+/** `substitute` resolves a block's `$param` refs; a spec's own steps have none, so it passes text through. */
+function expandStep(step, id, source, substitute) {
+	if (isJudgeByLlmStep(step)) return {
+		id,
+		source,
+		judgeByLlm: substitute(step.judgeByLlm),
+		...step.from !== void 0 ? { from: substitute(step.from) } : {}
+	};
+	return {
+		id,
+		source,
+		instruction: substitute(step.instruction),
+		expected: substitute(step.expected)
+	};
+}
+function resolveBlock(blockName, rawParams, blocks) {
+	const block = blocks.get(blockName);
+	if (!block) throw new Error(`Unknown block: "${blockName}". Define it under .ccqa/blocks/${blockName}/spec.yaml.`);
+	const declaredParams = new Map((block.params ?? []).map((p) => [p.name, p]));
+	for (const key of Object.keys(rawParams)) if (!declaredParams.has(key)) throw new Error(`Block "${blockName}" received unknown param "${key}". Declared params: ${[...declaredParams.keys()].join(", ") || "(none)"}.`);
+	for (const [pname, def] of declaredParams) if (isParamRequired(def) && !(pname in rawParams)) throw new Error(`Block "${blockName}" is missing required param "${pname}".`);
+	const lookup = (name) => {
+		if (Object.prototype.hasOwnProperty.call(rawParams, name)) return rawParams[name];
+	};
+	return {
+		steps: block.steps,
+		lookup
+	};
+}
+/**
+* Collect every block name referenced by a spec (top-level only — blocks
+* cannot nest). Used by the store / drift layers to know which blocks to
+* load or invalidate.
+*/
+function collectIncludedBlockNames(spec) {
+	const names = /* @__PURE__ */ new Set();
+	for (const step of spec.steps) if (isIncludeStep(step)) names.add(step.include);
+	return [...names];
+}
+//#endregion
+//#region src/claude/env-keys.ts
+/**
+* Variables that carry a credential the Claude Code process can use on its
+* own, with no login on the host: an API key, a gateway bearer token, or a
+* subscription token from `claude setup-token`.
+*/
+const CREDENTIAL_ENV_KEYS = [
+	"ANTHROPIC_API_KEY",
+	"ANTHROPIC_AUTH_TOKEN",
+	"CLAUDE_CODE_OAUTH_TOKEN"
+];
+/**
+* Standard Claude Code environment variables that select the API endpoint and
+* credentials. ccqa forwards whichever of these are set to the underlying
+* Claude Code process; it does not read or interpret their values.
+*
+* - `ANTHROPIC_BASE_URL`      — the API endpoint to send requests to.
+* - `ANTHROPIC_AUTH_TOKEN`    — sent as `Authorization: Bearer <token>`.
+* - `ANTHROPIC_API_KEY`       — API key, when used instead of a token.
+* - `ANTHROPIC_CUSTOM_HEADERS` — extra request headers.
+* - `CLAUDE_CODE_OAUTH_TOKEN` — long-lived subscription token from
+*   `claude setup-token`, the headless-CI counterpart of a login.
+*/
+const ENDPOINT_ENV_KEYS = [
+	"ANTHROPIC_BASE_URL",
+	"ANTHROPIC_CUSTOM_HEADERS",
+	...CREDENTIAL_ENV_KEYS
+];
+//#endregion
+//#region src/cli/logger.ts
+const STEP_ICONS = {
+	STEP_START: "▶",
+	STEP_DONE: "✓",
+	ASSERTION_FAILED: "✗",
+	STEP_SKIPPED: "⊘",
+	RUN_COMPLETED: "■"
+};
+/**
+* When a `withBuffer` scope is active, every log line (stdout and stderr) is
+* appended to its buffer instead of being written immediately. Parallel spec
+* runs use this so each spec's narration — including logs emitted deep inside
+* the live executor — flushes as one contiguous block, not interleaved.
+*/
+const bufferStore = new AsyncLocalStorage();
+const sinkStore = new AsyncLocalStorage();
+/** True while inside a `withBuffer` scope: progress lines avoid TTY cursor tricks. */
+function isBuffered() {
+	return bufferStore.getStore() !== void 0;
+}
+function emit(text, sink = process.stdout) {
+	const store = bufferStore.getStore();
+	if (store) {
+		store.out.push(text);
+		return;
+	}
+	const activeSink = sinkStore.getStore();
+	if (activeSink) {
+		activeSink.write(text);
+		return;
+	}
+	sink.write(text);
+}
+/**
+* Write raw text to the active `withBuffer` scope, or straight to stdout when
+* none is active. Lets a runner redirect sub-process output (e.g. a child's
+* stdout) into the same buffer as its `log.*` lines so they flush together.
+*/
+function emitRaw(text) {
+	emit(text);
+}
+/**
+* Run `fn` with all its log output captured into a buffer, then flush the
+* buffer in one shot under `label`. Used by parallel runners to keep each
+* spec's output legible. Output is flushed even when `fn` throws.
+*
+* When `buffered` is false, `fn` runs with no buffer so its output streams
+* live — this is the sequential (concurrency 1) path, unchanged from before.
+*/
+async function withBuffer(label, buffered, fn) {
+	if (!buffered) return fn();
+	const store = { out: [] };
+	try {
+		return await bufferStore.run(store, fn);
+	} finally {
+		emit(`\n──── ${label} ────\n${store.out.join("")}`);
+	}
+}
+function header(command, target) {
+	emit(`\nccqa ${command}${target ? ` ${target}` : ""}\n\n`);
+}
+function write(scope, message, sink = process.stdout) {
+	emit(`[${scope}] ${message}\n`, sink);
+}
+function meta(key, value) {
+	write("meta", `${key}: ${value}`);
+}
+function blank() {
+	emit("\n");
+}
+function info(message) {
+	write("info", message);
+}
+function step(type, stepId, detail) {
+	emit(`  ${STEP_ICONS[type]} [${stepId}] ${detail}\n`);
+}
+function bash(command) {
+	emit(`  $ ${command.slice(0, 120)}\n`);
+}
+function error(message) {
+	write("error", message, process.stderr);
+}
+function warn(message) {
+	write("warn", message, process.stderr);
+}
+function hint(message) {
+	emit("\n");
+	write("hint", message);
+}
+function fix(message) {
+	write("fix", message);
+}
+function run(message) {
+	write("run", message);
+}
+/**
+* Render a single-line progress indicator for a step-by-step loop.
+*
+* On a TTY the line is rewritten in place via `\r` so the terminal stays
+* uncluttered. In a non-TTY environment (CI, piped runs) we fall back to
+* a regular `[info]` line every PROGRESS_NONTTY_STRIDE steps to avoid
+* spamming the log with one line per action.
+*
+* Callers MUST call `progressEnd()` when the loop finishes (or aborts) so
+* the carriage-return line gets a final newline; otherwise the next log
+* line lands on the same physical row.
+*/
+const PROGRESS_NONTTY_STRIDE = 5;
+let lastProgressNonTtyEmit = -1;
+function progress(current, total, label) {
+	const text = `[info] ${current + 1}/${total} ${label}`;
+	if (process.stdout.isTTY && !isBuffered()) {
+		process.stdout.write(`\r${text}\x1b[K`);
+		return;
+	}
+	if (current === 0 || current - lastProgressNonTtyEmit >= PROGRESS_NONTTY_STRIDE) {
+		emit(`${text}\n`);
+		lastProgressNonTtyEmit = current;
+	}
+}
+function progressEnd() {
+	if (process.stdout.isTTY && !isBuffered()) process.stdout.write(`\r\x1b[K`);
+	lastProgressNonTtyEmit = -1;
+}
+/**
+* Time a long-running step under the given scope, emitting `started` and
+* `finished in N.Ns` markers. Scope must be a tag the user wants to grep
+* for — typically "run" for vitest and "fix" for diagnose-loop steps.
+*/
+async function timedPhase(label, fn, scope = "fix") {
+	const startedAt = Date.now();
+	write(scope, `${label} started`);
+	try {
+		const result = await fn();
+		write(scope, `${label} finished in ${((Date.now() - startedAt) / 1e3).toFixed(1)}s`);
+		return result;
+	} catch (err) {
+		write(scope, `${label} threw after ${((Date.now() - startedAt) / 1e3).toFixed(1)}s`);
+		throw err;
+	}
+}
+//#endregion
+//#region src/ir/from-agent-browser.ts
+/**
+* Normalization from the agent-browser side of the recorder into the IR.
+* The trace protocol emits one pipe-delimited `AB_ACTION|...` line per
+* browser action (see `src/prompts/trace.ts` and
+* `claude/invoke.ts:extractAbActionFromBashCommand`); `parseAbActionLine`
+* turns each line into a `RecordedAction`.
+*
+* The mapping is a deterministic re-encoding: `to-agent-browser.ts` is its
+* inverse, and the round-trip identity (ab argv → wire → IR → ab argv) is
+* pinned by `roundtrip.test.ts`.
+*/
+/**
+* Semantic locator strategies exposed by `agent-browser find`. Used by the
+* `find_*` wire commands when a target cannot be uniquely picked out by the
+* ALLOWED CSS forms (e.g. repeated `aria-label='1 reply'` rows where only
+* "the last one" is meaningful).
+*
+* `first` / `last` / `nth` are positional helpers whose value carries an
+* inner CSS selector (`nth` additionally needs an index); they normalize to
+* a `css` Locator plus `index`. The remaining strategies read the value as
+* the human-visible text/id and normalize to the matching `Locator.by`.
+*/
+const FIND_LOCATORS = [
+	"role",
+	"text",
+	"label",
+	"placeholder",
+	"alt",
+	"title",
+	"testid",
+	"first",
+	"last",
+	"nth"
+];
+/**
+* Actions reachable via `agent-browser find <locator> ... <action>`. Kept
+* here next to the locator list so all `find` wire knowledge lives in one
+* place — `claude/invoke.ts` imports these instead of redefining its own sets.
+*/
+const FIND_ACTIONS = [
+	"click",
+	"dblclick",
+	"fill",
+	"type",
+	"hover",
+	"focus",
+	"check",
+	"uncheck"
+];
+const css = (value) => ({
+	by: "css",
+	value
+});
+function parseAbActionLine(line) {
+	if (!line.startsWith("AB_ACTION|")) return null;
+	const parts = line.split("|");
+	const command = parts[1];
+	switch (command) {
+		case "cookies_clear": return { action: "cookies_clear" };
+		case "open": return {
+			action: "navigate",
+			value: (parts[2] ?? "").replace(/^["']|["']$/g, "")
+		};
+		case "press": return {
+			action: "press",
+			...opt("value", parts[2])
+		};
+		case "scroll": return {
+			action: "scroll",
+			...opt("direction", parts[2]),
+			...opt("pixels", parts[3])
+		};
+		case "snapshot": return {
+			action: "snapshot",
+			...opt("observation", parts[2])
+		};
+		case "assert": return {
+			action: "assert",
+			assert: parts[2],
+			...parts[3] ? { locator: css(parts[3]) } : {},
+			...parts[4] ? { value: parts[4] } : {},
+			...parts[5] ? { observation: parts[5] } : {}
+		};
+		case "click":
+		case "dblclick":
+		case "check":
+		case "uncheck":
+		case "hover":
+			if (!parts[2]) return null;
+			return {
+				action: command,
+				locator: css(parts[2]),
+				...opt("label", parts[3])
+			};
+		case "wait":
+			if (parts[2] === "--text") {
+				if (!parts[3]) return null;
+				return {
+					action: "wait",
+					locator: {
+						by: "text",
+						value: parts[3]
+					},
+					...opt("label", parts[4])
+				};
+			}
+			if (!parts[2]) return null;
+			return {
+				action: "wait",
+				locator: css(parts[2]),
+				...opt("label", parts[3])
+			};
+		case "fill":
+		case "type":
+		case "select":
+			if (!parts[2]) return null;
+			return {
+				action: command,
+				locator: css(parts[2]),
+				...parts[3] !== void 0 ? { value: parts[3] } : {},
+				...opt("label", parts[4])
+			};
+		case "drag":
+			if (!parts[2] || !parts[3]) return null;
+			return {
+				action: "drag",
+				locator: css(parts[2]),
+				target: css(parts[3]),
+				...opt("label", parts[4])
+			};
+		case "upload": {
+			const selector = parts[2];
+			const files = parts.slice(3).filter((f) => f !== "");
+			if (!selector || files.length === 0) return null;
+			return {
+				action: "upload",
+				locator: css(selector),
+				files
+			};
+		}
+		case "find_click":
+		case "find_dblclick":
+		case "find_hover":
+		case "find_focus":
+		case "find_check":
+		case "find_uncheck": return parseFindAction(command.slice(5), parts, false);
+		case "find_fill":
+		case "find_type": return parseFindAction(command.slice(5), parts, true);
+		case "get_count":
+		case "get_url": return null;
+		default: return null;
+	}
+}
+/**
+* Promote a `CCQA_ASSERT=<marker>` env marker on an agent-browser command
+* into recorded assert action(s). The marker travels on the same channel as
+* the command itself (see `claude/invoke.ts`), so a verification the model
+* performs anyway (`wait --text`, `get count`) becomes a recorded assert
+* without relying on the `AB_ACTION|assert|...` text protocol.
+*
+* `abAction` is the wire line for the marked command (null when the command
+* has no wire form at all). Mapping — anything else returns null and the
+* caller warns and records the command unpromoted:
+*
+* - `wait --text "X"` + `1` (or `text_visible`) → `assert text_visible X`,
+*   REPLACING the wait: the emitted abAssert is itself a timed wait, so
+*   keeping both would wait twice.
+* - `get count "<sel>"` + `element_visible` / `element_not_visible`
+*   → `assert <marker> <sel>` (the probe records nothing by itself).
+* - any command + `url_contains:<substring>` → the command's own action (if
+*   it records one) followed by `assert url_contains <substring>`.
+*/
+function promoteMarkedAssert(abAction, marker) {
+	if (marker.startsWith("url_contains:")) {
+		const substring = marker.slice(13);
+		if (!substring) return null;
+		const assert = {
+			action: "assert",
+			assert: "url_contains",
+			value: substring
+		};
+		const base = abAction === null ? null : parseAbActionLine(abAction);
+		return base === null ? [assert] : [base, assert];
+	}
+	const parts = abAction === null ? [] : abAction.split("|");
+	if (marker === "1" || marker === "text_visible") {
+		if (parts[1] === "wait" && parts[2] === "--text" && parts[3]) return [{
+			action: "assert",
+			assert: "text_visible",
+			value: parts[3]
+		}];
+		return null;
+	}
+	if (marker === "element_visible" || marker === "element_not_visible") {
+		if (parts[1] === "get_count" && parts[2]) return [{
+			action: "assert",
+			assert: marker,
+			locator: css(parts[2])
+		}];
+		return null;
+	}
+	return null;
+}
+/**
+* Common parser for the `find_*` wire family. `<extra>` carries `--name` for
+* `role`, the integer index for `nth`, and is empty otherwise. We accept a
+* literally empty `<extra>` (the LLM emits a placeholder `|` so the
+* positional layout stays stable across locators).
+*/
+function parseFindAction(action, parts, hasFillValue) {
+	const locatorToken = parts[2];
+	const findValue = parts[3];
+	const extra = parts[4] ?? "";
+	const exact = (parts[5] ?? "") === "exact";
+	if (!locatorToken || !FIND_LOCATORS.includes(locatorToken) || !findValue) return null;
+	let locator;
+	let index;
+	if (locatorToken === "first" || locatorToken === "last") {
+		locator = css(findValue);
+		index = locatorToken;
+	} else if (locatorToken === "nth") {
+		const parsed = extra ? Number.parseInt(extra, 10) : NaN;
+		if (Number.isNaN(parsed)) return null;
+		locator = css(findValue);
+		index = parsed;
+	} else if (locatorToken === "role") locator = {
+		by: "role",
+		value: findValue,
+		...extra ? { name: extra } : {},
+		...exact ? { exact: true } : {}
+	};
+	else locator = {
+		by: locatorToken,
+		value: findValue,
+		...exact ? { exact: true } : {}
+	};
+	return {
+		action,
+		locator,
+		...index !== void 0 ? { index } : {},
+		...hasFillValue ? {
+			...parts[6] !== void 0 ? { value: parts[6] } : {},
+			...opt("label", parts[7])
+		} : opt("label", parts[6])
+	};
+}
+/** Include an optional string field only when it is non-empty. */
+function opt(key, value) {
+	return value ? { [key]: value } : {};
+}
+//#endregion
+//#region src/runtime/env-scrub.ts
+/**
+* Build a list of `[envValue, "${VAR}"]` pairs for every `${VAR}` reference
+* mentioned in the spec OR in any of its expanded (block-inlined) steps.
+* Used at trace time to scrub recorded Claude-text outputs so a value the
+* spec author intentionally threaded through `process.env` is preserved as
+* `${VAR}` in `ir.json` rather than baked in as the concrete
+* trace-time value.
+*
+* Why we walk `spec.steps` AND `expanded`:
+*   - `spec.steps` carries the spec's own `instruction` / `expected` + each
+*     include's raw `params` (which may themselves be `${ENV}` refs).
+*   - `expanded` carries the inlined block-internal steps, whose
+*     `instruction` / `expected` may *also* contain `${ENV}` refs that
+*     don't go through include params.
+*
+* Each ref resolves against `overrides` first, then `process.env` —
+* `overrides` carries values the invoker injects into the child process,
+* which beat the parent env there. Only refs that resolve non-empty land in
+* the map — scrubbing against an empty string would corrupt unrelated empty
+* strings in the action stream; the rest are returned via `unresolved` so
+* the caller can warn the user.
+*
+* Longer values sort first so a `${SHORT}` whose value is a substring of a
+* `${LONG}` value doesn't clobber the longer one.
+*
+* `title` is deliberately NOT scanned — it never reaches the recorded action
+* stream.
+*/
+function buildSpecEnvScrub(spec, expanded, overrides = {}) {
+	const refNames = /* @__PURE__ */ new Set();
+	for (const step of spec.steps) if (isIncludeStep(step)) for (const v of Object.values(step.params ?? {})) collect(v, refNames);
+	else collectStepRefs(step, refNames);
+	for (const step of expanded) collectStepRefs(step, refNames);
+	const map = [];
+	const unresolved = [];
+	for (const name of refNames) {
+		const value = overrides[name] ?? process.env[name];
+		if (typeof value === "string" && value.length > 0) map.push([value, "${" + name + "}"]);
+		else unresolved.push(name);
+	}
+	map.sort((a, b) => b[0].length - a[0].length);
+	return {
+		map,
+		unresolved
+	};
+}
+function collect(value, into) {
+	for (const name of iterEnvRefNames(value)) into.add(name);
+}
+function collectStepRefs(step, into) {
+	if (isJudgeBody(step)) {
+		collect(step.judgeByLlm, into);
+		if (step.from !== void 0) collect(step.from, into);
+		return;
+	}
+	collect(step.instruction, into);
+	collect(step.expected, into);
+}
+/** Shorter than this, a value is no secret and matches inside ordinary words. */
+const MIN_PROSE_SCRUB_LENGTH = 4;
+/** Long enough to clear the length bar, still ordinary prose / JSON. */
+const COMMON_PROSE_VALUES = new Set([
+	"true",
+	"false",
+	"null",
+	"none",
+	"undefined"
+]);
+/**
+* Scrub map for model output, built like {@link buildSpecEnvScrub} but
+* without the values that read as ordinary text (`"1"`, `"true"`): prose
+* runs to paragraphs, where replacing every occurrence of such a value
+* costs more meaning than it protects. Record's own scrub keeps them for
+* its single command lines; the live path reuses this one map for its Bash
+* command log too, trading that short-value coverage for not building a
+* second map.
+*/
+function buildProseEnvScrubMap(spec, expanded, overrides = {}) {
+	return buildSpecEnvScrub(spec, expanded, overrides).map.filter(([value]) => value.length >= MIN_PROSE_SCRUB_LENGTH && !COMMON_PROSE_VALUES.has(value.toLowerCase()));
+}
+/**
+* Replace every occurrence of an env value with its `${VAR}` placeholder in
+* `text`. **Caller invariant**: the map must be sorted longest-value-first
+* so a shorter value doesn't shadow a longer one that contains it as a
+* substring. `buildSpecEnvScrub` upholds this; hand-built maps should too.
+*/
+function scrubEnvValues(text, scrubMap) {
+	if (scrubMap.length === 0) return text;
+	let out = text;
+	for (const [value, placeholder] of scrubMap) if (out.includes(value)) out = out.replaceAll(value, placeholder);
+	return out;
+}
+//#endregion
+//#region src/claude/native-binary.ts
+const require = createRequire(import.meta.url);
+/**
+* The agent SDK launches Claude through a native `claude` binary that ships in
+* a per-platform package (`@anthropic-ai/claude-agent-sdk-<platform>-<cpu>`),
+* declared as an *optional* dependency of the SDK. Optional means a consumer's
+* lockfile can omit it without any install-time error — and then every Claude
+* call fails at runtime with a message that never reaches our logs. Resolving
+* the package up front lets us say so once, in a line that names the fix.
+*
+* ccqa's own package.json repeats these packages in `optionalDependencies` for
+* the same reason: a second declaration gives the resolver another chance to
+* record them. Keep that list's version range in step with the SDK's.
+*/
+function nativeBinaryPackage(platform = process.platform, arch = process.arch, musl = isMusl(platform)) {
+	return `@anthropic-ai/claude-agent-sdk-${platform}-${arch === "arm64" ? "arm64" : "x64"}${platform === "linux" && musl ? "-musl" : ""}`;
+}
+/**
+* musl builds (Alpine and friends) need their own binary. Node doesn't expose
+* the libc flavour directly; the absence of `glibcVersionRuntime` in the
+* process report is the usual proxy.
+*/
+function isMusl(platform) {
+	if (platform !== "linux") return false;
+	return !(process.report?.getReport?.())?.header?.glibcVersionRuntime;
+}
+/**
+* Name of the platform package this host needs, or `null` when it resolves.
+* The per-platform packages have no `exports`, so the manifest is reachable.
+*/
+function missingNativeBinaryPackage(resolve = require.resolve) {
+	const pkg = nativeBinaryPackage();
+	try {
+		resolve(`${pkg}/package.json`);
+		return null;
+	} catch {
+		return pkg;
+	}
+}
+/** Advice shown when the binary is absent — the package name plus how to fix it. */
+function missingNativeBinaryMessage(pkg) {
+	return `${pkg} is not installed. The Claude Agent SDK needs it to start Claude on this platform, so every Claude-backed command (run in live mode, drift, diagnose) will fail. It ships as an optional dependency of the SDK, which a lockfile can drop silently: reinstall without omitting optional dependencies, or add it to your project as a direct dependency pinned to the same version as @anthropic-ai/claude-agent-sdk.`;
+}
+//#endregion
+//#region src/claude/cost-tally.ts
+/**
+* Sum every Claude invocation made inside a scope.
+*
+* A command like `record` calls Claude several times — the browser trace, the
+* codegen cleanup, one diagnosis per auto-fix retry — and the caller wants one
+* number for the whole command. Threading a cost out of each of those return
+* types would touch every layer in between, so the tally is scoped instead:
+* `invokeClaudeStreaming` adds to whichever scope is active, and nothing
+* between the two has to know.
+*
+* Scoped rather than module-global because commands run specs concurrently
+* (`drift` uses a pool). Two scopes must not fold into each other.
+*/
+const tallyStore = new AsyncLocalStorage();
+/** Record one invocation against the active scope. No-op outside one. */
+function tallyInvocation(cost) {
+	tallyStore.getStore()?.push(cost);
+}
+/** Run `fn` with a fresh tally. Read the total from inside with `readCostTally`. */
+async function withCostTally(fn) {
+	return tallyStore.run([], fn);
+}
+/**
+* The active scope's total so far, or null outside one.
+*
+* Read rather than pushed at the caller because commands end in
+* `process.exit`, which never reaches a `finally`; whoever opened the scope
+* reads the total on the way out (see `withCostReporting`).
+*
+* Fields stay `null` when no invocation reported them, so a caller can tell
+* "nothing was billed" from "the SDK didn't say" (mock runs, SDK errors).
+*/
+function readCostTally() {
+	const collected = tallyStore.getStore();
+	return collected === void 0 ? null : sum(collected);
+}
+function sum(costs) {
+	const add = (pick) => {
+		const present = costs.map(pick).filter((v) => v !== null);
+		return present.length === 0 ? null : present.reduce((a, b) => a + b, 0);
+	};
+	return {
+		totalCostUsd: add((c) => c.totalCostUsd),
+		durationMs: add((c) => c.durationMs),
+		durationApiMs: add((c) => c.durationApiMs),
+		numTurns: add((c) => c.numTurns),
+		inputTokens: add((c) => c.inputTokens),
+		cacheCreationInputTokens: add((c) => c.cacheCreationInputTokens),
+		cacheReadInputTokens: add((c) => c.cacheReadInputTokens),
+		outputTokens: add((c) => c.outputTokens),
+		models: [...new Set(costs.flatMap((c) => c.models))]
+	};
+}
+//#endregion
+//#region src/claude/invoke.ts
+/** The built-in tools an allow-list names: `Bash(*)` is `Bash`; `mcp__*` are not built-ins. */
+function builtinToolNames(allowedTools) {
+	const names = allowedTools.map((entry) => entry.replace(/\(.*\)$/, "")).filter((name) => !name.startsWith("mcp__"));
+	return [...new Set(names)];
+}
+function resolveModel(explicit) {
+	if (explicit) return explicit;
+	const envModel = process.env["CCQA_MODEL"];
+	return envModel && envModel.length > 0 ? envModel : void 0;
+}
+/**
+* When both credentials are present the OAuth token wins and the API key is
+* dropped. Left to the CLI the API key would win, which makes "switch a CI
+* job to the subscription token" require unwiring the key everywhere; with
+* this rule, adding the one variable is the whole switch, and removing it is
+* the whole rollback. The one place the rule lives — both the resolved view
+* and the env the SDK receives apply it through here.
+*/
+function preferOauthToken(env) {
+	if (env["CLAUDE_CODE_OAUTH_TOKEN"]) delete env["ANTHROPIC_API_KEY"];
+}
+/**
+* Drop endpoint variables that are present but empty, so an empty value never
+* reaches the Claude Code process as an override. "Set to nothing" is how a
+* caller that cannot omit the key says "use the default" — a CI job wiring
+* `ANTHROPIC_BASE_URL` from an unset repository variable, most of all.
+*/
+function withoutEmptyEndpointVars(env) {
+	const out = { ...env };
+	for (const key of ENDPOINT_ENV_KEYS) if (out[key] === "") delete out[key];
+	return out;
+}
+/**
+* The environment actually handed to the Claude Code process: the full process
+* environment with the caller's overrides on top, empty endpoint variables
+* dropped, and — when both credentials survive the merge — the API key removed
+* so the OAuth token wins.
+*
+* That removal MUST happen on the env the SDK receives, not only on the
+* resolved view: left to the CLI the API key would win, silently moving every
+* call from the subscription to metered billing when a CI job wires both
+* (which is exactly what happened before this function existed).
+*/
+function buildInvocationEnv(env) {
+	const merged = withoutEmptyEndpointVars({
+		...process.env,
+		...env
+	});
+	preferOauthToken(merged);
+	merged["CLAUDE_CODE_DISABLE_AUTO_MEMORY"] = "1";
+	return merged;
+}
+let nativeBinaryWarned = false;
+/**
+* Warn once per process when the SDK's per-platform native binary is missing:
+* every Claude call is about to fail, and the opaque per-step errors alone are
+* expensive to trace back to a lockfile that dropped an optional dependency.
+*/
+function warnOnceIfNativeBinaryMissing() {
+	if (nativeBinaryWarned) return;
+	nativeBinaryWarned = true;
+	const missing = missingNativeBinaryPackage();
+	if (missing) warn(missingNativeBinaryMessage(missing));
+}
+/** Whole minutes read best, but the ceiling is set in ms and may be seconds. */
+function formatDuration(ms) {
+	if (ms < 6e4 || ms % 6e4 !== 0) return `${Math.round(ms / 1e3)}s`;
+	const minutes = ms / 6e4;
+	return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+}
+async function invokeClaudeStreaming(options, onEvent) {
+	const { prompt, systemPrompt, allowedTools, disableThinking = false, mcpServers, maxTurns, timeoutMs, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, envScrubMap = [], relaxAbConstraints = false } = options;
+	const resolvedModel = resolveModel(model);
+	const mergedEnv = buildInvocationEnv(env);
+	const abortController = new AbortController();
+	let lastAbToolUseId = null;
+	const claimAbToolUse = (toolUseId) => {
+		if (toolUseId !== lastAbToolUseId) return false;
+		lastAbToolUseId = null;
+		return true;
+	};
+	const sdkOptions = {
+		systemPrompt,
+		maxTurns,
+		allowedTools,
+		tools: builtinToolNames(allowedTools),
+		strictMcpConfig: true,
+		settingSources: [],
+		permissionMode: "bypassPermissions",
+		allowDangerouslySkipPermissions: true,
+		abortController,
+		...resolvedModel ? { model: resolvedModel } : {},
+		...cwd ? { cwd } : {},
+		env: mergedEnv,
+		...mcpServers ? { mcpServers } : {},
+		...disableThinking ? { thinking: { type: "disabled" } } : {},
+		hooks: onAbAction || onAbActionFailed ? {
+			PreToolUse: [{ hooks: [async (input) => {
+				if (input.hook_event_name !== "PreToolUse") return {};
+				if (input.tool_name !== "Bash") return {};
+				const cmd = input.tool_input?.["command"];
+				if (typeof cmd !== "string") return {};
+				if (!relaxAbConstraints) {
+					if (isBlockedAbSubcommand(cmd)) return {
+						decision: "block",
+						reason: "This agent-browser subcommand is not allowed because it cannot be recorded as a structured test action. Use only the standard commands: click, check, fill, select, hover, press, wait, find (with role/text/label/placeholder/alt/title/testid/first/last/nth). Take a fresh snapshot to find the correct selector."
+					};
+					if (hasRefSelector(cmd)) return {
+						decision: "block",
+						reason: "@ref selectors (like @e14) are session-specific and change every run. They cannot be used in generated tests. Use one of the allowed selector formats instead: [aria-label='...'], text=..., [placeholder='...'], or [type='password']. Take a fresh snapshot and find the element's aria-label or visible text. If an allowed selector already clicks the element but nothing happens, the element is clipped by an inner scroll container: `scrollintoview` it (addressed by a CSS selector, not `text=`) and click again — a @ref would not have fixed that either."
+					};
+					const bareTag = findPositionalBareTag(cmd);
+					if (bareTag !== null) return {
+						decision: "block",
+						reason: `\`find ${bareTag.locator}\` with a bare tag selector (\`${bareTag.selector}\`) is rejected: it matches every <${bareTag.selector}> on the page and is non-deterministic on replay. Pass a specific attribute selector instead, e.g. \`find ${bareTag.locator} "[aria-label='...']" ${bareTag.action}\` or \`find ${bareTag.locator} "[data-qa='...']" ${bareTag.action}\`. Take a fresh snapshot to find the right attribute.`
+					};
+					if (hasMultipleAbInvocations(cmd)) return {
+						decision: "block",
+						reason: "Run each `agent-browser` call as its own Bash command. Chaining multiple invocations with &&, ;, |, or || prevents ccqa from recording them as discrete steps and lets failed attempts leak into the trace. Issue one Bash tool call per agent-browser command."
+					};
+					if (hasErrorSuppression(cmd)) return {
+						decision: "block",
+						reason: "Do not suppress errors on `agent-browser` commands. Remove `|| true`, `|| :`, `2>/dev/null`, `; true`, and similar redirects so ccqa can detect failures and roll back unsuccessful attempts. Run the command standalone and let it surface its exit code."
+					};
+				}
+				const assertMarker = relaxAbConstraints ? null : extractCcqaAssertFromBashCommand(cmd);
+				const ab = relaxAbConstraints ? null : extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
+				if ((ab !== null || assertMarker !== null) && onAbAction) {
+					lastAbToolUseId = input.tool_use_id;
+					const stepId = extractCcqaStepFromBashCommand(cmd);
+					onAbAction({
+						...ab !== null ? { abAction: ab } : {},
+						...stepId ? { stepId } : {},
+						...assertMarker !== null ? { assertMarker } : {}
+					});
+				} else lastAbToolUseId = null;
+				return {};
+			}] }],
+			PostToolUse: [{ hooks: [async (input) => {
+				if (input.hook_event_name !== "PostToolUse") return {};
+				if (input.tool_name !== "Bash") return {};
+				if (!isBashToolResponseError(input.tool_response)) return {};
+				if (claimAbToolUse(input.tool_use_id) && onAbActionFailed) onAbActionFailed();
+				return {};
+			}] }],
+			PostToolUseFailure: [{ hooks: [async (input) => {
+				if (input.hook_event_name !== "PostToolUseFailure") return {};
+				if (input.tool_name !== "Bash") return {};
+				if (claimAbToolUse(input.tool_use_id) && onAbActionFailed) onAbActionFailed();
+				return {};
+			}] }]
+		} : void 0
+	};
+	warnOnceIfNativeBinaryMissing();
+	const capTimer = timeoutMs === void 0 ? null : setTimeout(() => abortController.abort(), timeoutMs);
+	capTimer?.unref?.();
+	let result = "";
+	let answered = false;
+	let isError = false;
+	let errorDetail = null;
+	let cost = {
+		totalCostUsd: null,
+		durationMs: null,
+		durationApiMs: null,
+		numTurns: null,
+		inputTokens: null,
+		cacheCreationInputTokens: null,
+		cacheReadInputTokens: null,
+		outputTokens: null,
+		models: []
+	};
+	const q = await buildMessageStream(prompt, sdkOptions);
+	try {
+		for await (const msg of q) {
+			onEvent(msg);
+			if (msg.type === "assistant" && !silenceBashLog) {
+				for (const block of msg.message.content ?? []) if (block.type === "tool_use" && block.name === "Bash") {
+					const cmd = block.input?.["command"];
+					if (typeof cmd === "string") bash(scrubEnvValues(cmd, envScrubMap));
+				}
+			}
+			if (msg.type === "result") {
+				answered = true;
+				isError = msg.is_error ?? false;
+				if (msg.subtype === "success") result = msg.result;
+				else {
+					result = "";
+					errorDetail = `SDK reported ${msg.subtype}`;
+				}
+				cost = extractInvocationCost(msg);
+			}
+		}
+	} catch (err) {
+		isError = true;
+		errorDetail = err instanceof Error ? err.message : String(err);
+		if (!result) result = errorDetail;
+	} finally {
+		if (capTimer) clearTimeout(capTimer);
+	}
+	if (abortController.signal.aborted && timeoutMs !== void 0 && !answered) {
+		isError = true;
+		errorDetail = `stopped after ${formatDuration(timeoutMs)} (host time limit)`;
+		result = errorDetail;
+	}
+	tallyInvocation(cost);
+	return {
+		result,
+		isError,
+		errorDetail,
+		cost
+	};
+}
+/**
+* Pull the cost / usage / turn / duration fields off the SDK `result` message.
+* The SDK's success and error result shapes share these fields, so we read
+* them defensively as `unknown` and coerce — newer SDK versions may rename a
+* field without breaking our extraction.
+*/
+function extractInvocationCost(msg) {
+	const m = msg;
+	const usage = m["usage"];
+	const modelUsage = m["modelUsage"];
+	const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+	const models = modelUsage && typeof modelUsage === "object" ? Object.keys(modelUsage) : [];
+	return {
+		totalCostUsd: pricedForClaude(models) ? num(m["total_cost_usd"]) : null,
+		durationMs: num(m["duration_ms"]),
+		durationApiMs: num(m["duration_api_ms"]),
+		numTurns: num(m["num_turns"]),
+		inputTokens: num(usage?.["input_tokens"]),
+		cacheCreationInputTokens: num(usage?.["cache_creation_input_tokens"]),
+		cacheReadInputTokens: num(usage?.["cache_read_input_tokens"]),
+		outputTokens: num(usage?.["output_tokens"]),
+		models
+	};
+}
+/**
+* The SDK prices an unknown model id at a default Claude rate rather than
+* returning null, so a self-hosted model would report dollars nobody is billed.
+*/
+function pricedForClaude(models) {
+	return models.every((id) => /claude/i.test(id));
+}
+const BLOCKED_AB_SUBCOMMANDS = new Set([
+	"eval",
+	"js",
+	"label",
+	"textbox"
+]);
+/**
+* Shell-aware tokenizer: splits a command string into tokens respecting single/double quotes.
+* e.g. `click "[role='dialog'] button:last-child"` → ["click", "[role='dialog'] button:last-child"]
+*/
+function shellTokenize(s) {
+	const tokens = [];
+	let cur = "";
+	let quote = null;
+	for (let i = 0; i < s.length; i++) {
+		const ch = s[i];
+		if (quote) if (ch === quote) quote = null;
+		else cur += ch;
+		else if (ch === "\"" || ch === "'") quote = ch;
+		else if (ch === " " || ch === "	") {
+			if (cur) {
+				tokens.push(cur);
+				cur = "";
+			}
+		} else cur += ch;
+	}
+	if (cur) tokens.push(cur);
+	return tokens;
+}
+/** Extracts the subcommand from an `agent-browser [flags] <subcommand> [args...]` command string. */
+function extractAbSubcommand(cmd) {
+	const abIdx = cmd.indexOf("agent-browser");
+	if (abIdx === -1) return null;
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim());
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	return parts[i] ?? null;
+}
+/** Returns true if the agent-browser subcommand is blocked (eval/js/find/etc). */
+function isBlockedAbSubcommand(cmd) {
+	const sub = extractAbSubcommand(cmd);
+	return sub !== null && BLOCKED_AB_SUBCOMMANDS.has(sub);
+}
+/**
+* Detects "the Bash tool returned an error" from a SDK PostToolUse hook's
+* `tool_response`. The SDK can shape this two ways depending on how Claude
+* Code reports Bash failures:
+*
+*   - `{ is_error: true, ... }`              — the canonical Bash failure shape
+*   - `{ output, exitCode, killed?, ... }`   — the BashOutput shape; treat
+*                                              non-zero exit / kill as error
+*
+* We accept either. Anything else (including missing fields) is treated as a
+* successful response so we never roll back over an unrelated tool call.
+*/
+function isBashToolResponseError(tool_response) {
+	if (tool_response === null || typeof tool_response !== "object") return false;
+	const r = tool_response;
+	if (r["is_error"] === true) return true;
+	if (typeof r["exitCode"] === "number" && r["exitCode"] !== 0) return true;
+	if (r["killed"] === true) return true;
+	return false;
+}
+/**
+* Detect `agent-browser ... find first|last|nth <bare-tag> <action>`. A bare
+* tag inside a *positional* finder matches every element of that tag on the
+* page, so "the last button" picks a different element whenever the page
+* shape shifts — recorded tests built on top are flaky by construction. The
+* check is narrow on purpose: `find role button --name X` is fine because
+* role + accessible name stays stable.
+*/
+function findPositionalBareTag(cmd) {
+	if (extractAbSubcommand(cmd) !== "find") return null;
+	const abIdx = cmd.indexOf("agent-browser");
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim());
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	const locator = parts[i + 1];
+	if (locator !== "first" && locator !== "last" && locator !== "nth") return null;
+	const innerIdx = locator === "nth" ? i + 3 : i + 2;
+	const inner = parts[innerIdx];
+	const action = parts[innerIdx + 1] ?? "";
+	if (!inner) return null;
+	if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(inner)) return null;
+	return {
+		locator,
+		selector: inner,
+		action
+	};
+}
+/** Returns true if any argument to an agent-browser command uses a @ref selector (e.g. @e14). */
+function hasRefSelector(cmd) {
+	const abIdx = cmd.indexOf("agent-browser");
+	if (abIdx === -1) return false;
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim());
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	i++;
+	for (; i < parts.length; i++) if (/^@/.test(parts[i])) return true;
+	return false;
+}
+/**
+* Split `cmd` into shell statements at unquoted separators (`;`, `|`, `&`,
+* newline; consecutive separator chars like `&&` count once). String
+* literals are honoured so `fill "a;b"` stays a single statement. This is a
+* heuristic split (no subshell grammar), shared by the compound-invocation
+* guard and the CCQA_STEP prefix extraction so both agree on what "one
+* command" means.
+*/
+function splitShellStatements(cmd) {
+	const statements = [];
+	let start = 0;
+	let quote = null;
+	for (let i = 0; i < cmd.length; i++) {
+		const ch = cmd[i];
+		if (quote) {
+			if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			quote = ch;
+			continue;
+		}
+		if (ch === ";" || ch === "|" || ch === "&" || ch === "\n") {
+			statements.push(cmd.slice(start, i));
+			while (i + 1 < cmd.length && (cmd[i + 1] === "|" || cmd[i + 1] === "&" || cmd[i + 1] === ";" || cmd[i + 1] === "\n")) i++;
+			start = i + 1;
+		}
+	}
+	statements.push(cmd.slice(start));
+	return statements;
+}
+/** One leading `KEY=value` env assignment; value may be single/double-quoted. */
+const ENV_ASSIGN_HEAD_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(?:"([^"]*)"|'([^']*)'|(\S*))(?:\s+|$)/;
+/**
+* Split a statement into its leading `KEY=value` env assignments and the
+* command they prefix. An assignment whose value is a command substitution
+* (`$(...)` / backticks) is NOT treated as a prefix — `result=$(agent-browser
+* ... snapshot)` is an assignment statement, not an agent-browser invocation,
+* and must stay invisible to the guards below.
+*/
+function splitLeadingEnvAssignments(statement) {
+	const env = /* @__PURE__ */ new Map();
+	let command = statement.trimStart();
+	for (;;) {
+		const m = ENV_ASSIGN_HEAD_RE.exec(command);
+		if (!m) break;
+		const value = m[2] ?? m[3] ?? m[4] ?? "";
+		if (value.startsWith("$(") || value.startsWith("`")) return {
+			env: /* @__PURE__ */ new Map(),
+			command: statement.trimStart()
+		};
+		env.set(m[1], value);
+		command = command.slice(m[0].length);
+	}
+	return {
+		env,
+		command
+	};
+}
+/** True when `command` starts with `agent-browser` as the command word. */
+function isAgentBrowserHead(command) {
+	if (!command.startsWith("agent-browser")) return false;
+	const after = command[13];
+	return after === void 0 || !/[A-Za-z0-9_\-]/.test(after);
+}
+/** Step ids passed via `CCQA_STEP=<step-id>` must be a plain slug. */
+const STEP_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+* Extract the step id from the `CCQA_STEP=<step-id>` env prefix on the
+* agent-browser invocation in `cmd` (e.g. `CCQA_STEP=step-03 agent-browser
+* --session s click "text=Submit"`). The prefix may sit anywhere in the
+* leading env-assignment run (`FOO=x CCQA_STEP=step-02 agent-browser ...`),
+* and the invocation may be a later statement of a compound command
+* (`cd app && CCQA_STEP=step-01 agent-browser ...`). Returns null when the
+* prefix is absent or its value is not a valid slug — callers then fall back
+* to the STEP_START text protocol.
+*/
+function extractCcqaStepFromBashCommand(cmd) {
+	for (const statement of splitShellStatements(cmd)) {
+		const { env, command } = splitLeadingEnvAssignments(statement);
+		if (!isAgentBrowserHead(command)) continue;
+		const value = env.get("CCQA_STEP");
+		return value !== void 0 && STEP_SLUG_RE.test(value) ? value : null;
+	}
+	return null;
+}
+/**
+* Extract the assert marker from the `CCQA_ASSERT=<marker>` env prefix on
+* the agent-browser invocation in `cmd`, e.g. `CCQA_STEP=step-03
+* CCQA_ASSERT=1 agent-browser --session s wait --text "Submitted" --timeout
+* 3000`. The marker declares that the command verifies a step signal;
+* `promoteMarkedAssert` maps it onto recorded assert action(s). Returns the
+* raw value — semantic validation (which markers combine with which
+* commands) happens at promotion time so mismatches surface as warnings
+* instead of being silently dropped here. Returns null when the prefix is
+* absent or empty.
+*/
+function extractCcqaAssertFromBashCommand(cmd) {
+	for (const statement of splitShellStatements(cmd)) {
+		const { env, command } = splitLeadingEnvAssignments(statement);
+		if (!isAgentBrowserHead(command)) continue;
+		const value = env.get("CCQA_ASSERT");
+		return value !== void 0 && value.length > 0 ? value : null;
+	}
+	return null;
+}
+/**
+* Returns true when `cmd` contains more than one `agent-browser` invocation
+* chained together via shell operators (`&&`, `||`, `;`, `|`, newline). The
+* PreToolUse hook only records ONE AB_ACTION per Bash call, so chained
+* invocations would silently drop every intermediate failure — turning
+* "I tried four selectors before one worked" into a clean-looking trace
+* with five orphaned actions that later fail at replay.
+*
+* Counts statements whose command word is `agent-browser`, skipping any
+* leading env assignments (the trace protocol prefixes every invocation
+* with `CCQA_STEP=<step-id>`). String literals are honoured so
+* `agent-browser fill 'agent-browser'` doesn't false-fire.
+*/
+function hasMultipleAbInvocations(cmd) {
+	let count = 0;
+	for (const statement of splitShellStatements(cmd)) {
+		if (!isAgentBrowserHead(splitLeadingEnvAssignments(statement).command)) continue;
+		count++;
+		if (count > 1) return true;
+	}
+	return false;
+}
+/**
+* Returns true when an `agent-browser` command in `cmd` has its exit
+* status hidden by a shell decorator that would prevent ccqa from rolling
+* back a failed attempt:
+*
+*   - trailing `|| true` / `|| :` / `; true` (force exit 0)
+*   - `2>/dev/null` and friends (drop stderr, sometimes paired with `|| true`)
+*
+* The agent-browser command itself returns exit 1 on selector miss, so
+* once one of these is present the PostToolUse hook sees `is_error=false`
+* and the bad attempt sneaks into ir.json.
+*/
+function hasErrorSuppression(cmd) {
+	if (cmd.indexOf("agent-browser") === -1) return false;
+	if (/\|\|\s*(true|:|\s*$|#)/.test(cmd)) return true;
+	if (/;\s*(true|:)\b/.test(cmd)) return true;
+	if (/2\s*>\s*\/dev\/null/.test(cmd)) return true;
+	if (/&\s*>\s*\/dev\/null/.test(cmd)) return true;
+	return false;
+}
+/**
+* Parse an `agent-browser --session <name> <cmd> [args...]` bash command
+* and return the corresponding AB_ACTION line, or null if not an agent-browser call.
+*/
+function extractAbActionFromBashCommand(cmd) {
+	const subCmd = extractAbSubcommand(cmd);
+	if (!subCmd) return null;
+	const abIdx = cmd.indexOf("agent-browser");
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim()).filter((t) => !/^(2?>|[|&>])/.test(t));
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	const args = parts.slice(i + 1);
+	switch (subCmd) {
+		case "cookies":
+			if (args[0] === "clear") return "AB_ACTION|cookies_clear";
+			return null;
+		case "open": return `AB_ACTION|open|${args[0] ?? ""}`;
+		case "press": return `AB_ACTION|press|${args[0] ?? ""}`;
+		case "scroll": return `AB_ACTION|scroll|${args.join("|")}`;
+		case "click":
+		case "dblclick":
+		case "check":
+		case "uncheck":
+		case "hover":
+		case "wait": return `AB_ACTION|${subCmd}|${args[0] ?? ""}|${args[1] ?? ""}`;
+		case "fill":
+		case "type":
+		case "select": return `AB_ACTION|${subCmd}|${args[0] ?? ""}|${args[1] ?? ""}|${args[2] ?? ""}`;
+		case "drag": return `AB_ACTION|drag|${args[0] ?? ""}|${args[1] ?? ""}|${args[2] ?? ""}`;
+		case "upload": {
+			const sel = args[0] ?? "";
+			const files = args.slice(1);
+			if (!sel || files.length === 0) return null;
+			return `AB_ACTION|upload|${sel}|${files.join("|")}`;
+		}
+		case "snapshot": return null;
+		case "find": return extractFindAbAction(args);
+		default: return null;
+	}
+}
+/**
+* Wire lines for the observation-only probes `get count <sel>` / `get url`.
+* These commands read state without mutating it, so they have no place in
+* the replay sequence and `extractAbActionFromBashCommand` ignores them.
+* They matter only when a `CCQA_ASSERT=<marker>` env prefix declares the
+* probe verifies a step signal — the hook layer then surfaces them via this
+* function so `promoteMarkedAssert` can turn them into recorded asserts.
+* Only consulted when a marker is present; unmarked `get` commands stay
+* unobserved as before.
+*/
+function extractObservationAbAction(cmd) {
+	if (extractAbSubcommand(cmd) !== "get") return null;
+	const abIdx = cmd.indexOf("agent-browser");
+	const parts = shellTokenize(cmd.slice(abIdx + 13).trim()).filter((t) => !/^(2?>|[|&>])/.test(t));
+	let i = 0;
+	while (i < parts.length && parts[i].startsWith("-")) i += 2;
+	const args = parts.slice(i + 1);
+	if (args[0] === "count" && args[1]) return `AB_ACTION|get_count|${args[1]}`;
+	if (args[0] === "url") return "AB_ACTION|get_url";
+	return null;
+}
+const FIND_ACTION_SET = new Set(FIND_ACTIONS);
+const FIND_LOCATOR_SET = new Set(FIND_LOCATORS);
+/**
+* Parse the positional tokens of `agent-browser find <locator> <value> [...]
+* <action> [fillValue]` and produce a canonical
+*   `AB_ACTION|find_<action>|<locator>|<value>|<extra>|<exact>|...|<label>`
+* line. The wire format keeps a fixed positional layout across locators so
+* downstream `parseAbActionLine` in `ir/from-agent-browser.ts` can split on
+* `|` alone:
+*
+*   <extra> is `--name` value for role, integer index for nth, "" otherwise.
+*   <exact> is the literal "exact" if --exact was passed, "" otherwise.
+*
+* Returns null for malformed invocations — the caller treats null as "not a
+* structured action" and the Bash command still runs unobserved.
+*/
+function extractFindAbAction(args) {
+	const locator = args[0];
+	if (!locator || !FIND_LOCATOR_SET.has(locator)) return null;
+	let i = 1;
+	let value = args[i] ?? "";
+	i++;
+	let extra = "";
+	if (locator === "nth") {
+		extra = value;
+		value = args[i] ?? "";
+		i++;
+	}
+	let action = "";
+	let name = "";
+	let exact = "";
+	let fillValue = "";
+	for (; i < args.length; i++) {
+		const tok = args[i];
+		if (tok === "--name") {
+			name = args[i + 1] ?? "";
+			i++;
+		} else if (tok === "--exact") exact = "exact";
+		else if (FIND_ACTION_SET.has(tok)) action = tok;
+		else if (action) fillValue = tok;
+	}
+	if (!action) return null;
+	if (locator === "role") extra = name;
+	const command = `find_${action}`;
+	if (action === "fill" || action === "type") return `AB_ACTION|${command}|${locator}|${value}|${extra}|${exact}|${fillValue}|`;
+	return `AB_ACTION|${command}|${locator}|${value}|${extra}|${exact}|`;
+}
+async function buildMessageStream(prompt, options) {
+	const mockFile = process.env["CCQA_CLAUDE_MOCK_FILE"];
+	if (mockFile) return replayMockMessages(mockFile, options);
+	return query({
+		prompt,
+		options
+	});
+}
+async function* replayMockMessages(path, options) {
+	const raw = await readFile(path, "utf8");
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const msg = JSON.parse(trimmed);
+		await fireMockPreToolUseHooks(msg, options);
+		yield msg;
+	}
+}
+/**
+* The real SDK fires PreToolUse hooks as it executes tool calls; the JSONL
+* replay approximates that by invoking the configured PreToolUse hooks for
+* every Bash tool_use block before yielding its message, so e2e stubs
+* exercise the AB_ACTION recording path (including CCQA_STEP step
+* attribution). Hook decisions are ignored and post-tool hooks are not
+* simulated — the replay runs no tools, so there is nothing to block or fail.
+*/
+async function fireMockPreToolUseHooks(msg, options) {
+	const matchers = options.hooks?.PreToolUse;
+	if (!matchers || msg.type !== "assistant") return;
+	for (const block of msg.message.content ?? []) {
+		if (block.type !== "tool_use" || block.name !== "Bash") continue;
+		const input = {
+			hook_event_name: "PreToolUse",
+			tool_name: "Bash",
+			tool_input: block.input,
+			tool_use_id: block.id,
+			session_id: "mock",
+			transcript_path: "",
+			cwd: process.cwd()
+		};
+		for (const matcher of matchers) for (const hook of matcher.hooks) await hook(input, block.id, { signal: new AbortController().signal });
+	}
+}
+//#endregion
+//#region src/prompts/format.ts
+/**
+* Formatting helpers shared by the Claude prompt builders (diagnose, report,
+* drift). Centralised so the prompts cannot drift apart on mechanics that
+* must stay consistent across commands.
+*/
+/** Prefix every line with its 1-based number, the form fix suggestions cite. */
+function numberLines(script) {
+	return script.split("\n").map((l, i) => `${i + 1}: ${l}`).join("\n");
+}
+/**
+* The "## Output language" prompt section. Empty for "auto" so the prompt
+* stays byte-identical to the no-flag baseline. `fields` names the
+* human-readable JSON fields to translate; `verbatimNames` names the
+* enum-like values that must never be translated.
+*/
+function outputLanguageBlock(outputLanguage, fields, verbatimNames) {
+	if (outputLanguage === "auto") return "";
+	return `## Output language
+
+Write all human-readable fields (${fields}) in **${outputLanguage}** (BCP-47 tag).
+Selectors, file paths, identifiers, ${verbatimNames}, JSON keys, and quoted strings stay verbatim regardless of language.
+
+`;
+}
+/**
+* The `spec`/`generated` surface-axis definitions, plus the "if both are
+* stale, answer spec" tie-break rule. Shared verbatim by the audit prompt
+* (`prompts/drift.ts`) and the run's failure-classification prompt
+* (`report/prompt.ts`): both fill the same wire field (`DriftSurfaceSchema`),
+* so a diverging definition in one would make the two paths disagree on what
+* a spec's own field means.
+*/
+function surfaceDefinitionBlock() {
+	return `- **\`spec\`** — spec.yaml asks about something the source no longer has. It has to be rewritten, and the code regenerated after.
+- **\`generated\`** — the spec still describes the product correctly, but the generated code reaches for a selector or string the source no longer has. Only a regeneration is needed; nobody has to rewrite the spec.
+
+If both are stale, answer \`spec\`: it is the root, and fixing it regenerates the code.`;
+}
+/**
+* "surface is a separate axis from the label" clarifying example, shared for
+* the same reason as {@link surfaceDefinitionBlock}. `labelToken` is the
+* exact text to name the label by (e.g. `"TEST_DRIFT"` or `` "`TEST_DRIFT`" ``)
+* so each caller keeps its own backtick/bold convention.
+*/
+function surfaceAxisAside(labelToken) {
+	return `This is a separate axis from the label. A renamed selector that only the generated code names is ${labelToken} on the \`generated\` surface; a spec whose \`expected\` quotes a string the product renamed is ${labelToken} on the \`spec\` surface.`;
+}
+//#endregion
+//#region src/ir/to-agent-browser.ts
+const lit = (text) => ({
+	text,
+	expandsEnv: false
+});
+const val = (text) => ({
+	text,
+	expandsEnv: true
+});
+/**
+* Render a locator as the selector string a plain agent-browser command
+* accepts. Only `css` (verbatim) and `text` (`text=` engine form) have a
+* plain-selector form; other strategies are reachable via `find` only and
+* fall back to their raw value (callers guard against that case).
+*/
+function locatorToSelector(locator) {
+	return locator.by === "text" ? `text=${locator.value}` : locator.value;
+}
+/**
+* Compact human-readable locator form for logs and LLM-prompt summaries: the
+* raw selector for `css`, `by=value` otherwise. Distinct from
+* `locatorToSelector` (which produces a selector agent-browser can execute) —
+* this one is for display only and never round-trips.
+*/
+function describeLocator(locator) {
+	return locator.by === "css" ? locator.value : `${locator.by}=${locator.value}`;
+}
+/**
+* Canonical agent-browser argv (sans `--session`) for one action. Returns
+* null for actions with no direct argv form: observation-only `snapshot`,
+* `assert` (validation probes / abAssert* helpers live in the consumers),
+* and structurally incomplete actions (e.g. a missing locator).
+*/
+function toAgentBrowserArgs(action) {
+	switch (action.action) {
+		case "cookies_clear": return [lit("cookies"), lit("clear")];
+		case "navigate": return [lit("open"), val(action.value ?? "")];
+		case "press": return [lit("press"), val(action.value ?? "")];
+		case "scroll": return [
+			lit("scroll"),
+			lit(action.direction ?? "down"),
+			...action.pixels ? [lit(action.pixels)] : []
+		];
+		case "select":
+			if (!action.locator) return null;
+			return [
+				lit("select"),
+				val(locatorToSelector(action.locator)),
+				val(action.value ?? "")
+			];
+		case "drag":
+			if (!action.locator || !action.target) return null;
+			return [
+				lit("drag"),
+				val(locatorToSelector(action.locator)),
+				val(locatorToSelector(action.target))
+			];
+		case "upload": {
+			const files = action.files ?? [];
+			if (!action.locator || files.length === 0) return null;
+			return [
+				lit("upload"),
+				val(locatorToSelector(action.locator)),
+				...files.map(val)
+			];
+		}
+		case "wait": {
+			const loc = action.locator;
+			if (!loc) return null;
+			if (loc.by === "text") return [
+				lit("wait"),
+				lit("--text"),
+				val(loc.value)
+			];
+			return [lit("wait"), val(locatorToSelector(loc))];
+		}
+		case "click":
+		case "dblclick":
+		case "check":
+		case "uncheck":
+		case "hover":
+		case "focus":
+		case "fill":
+		case "type": return interactionToArgs(action);
+		case "snapshot":
+		case "assert": return null;
+	}
+}
+/**
+* Element interactions come in two argv shapes: the plain command
+* (`click "<css>"`) when the locator is a raw selector string, and the
+* `find <locator> <value> <action> [input] [--name <n>] [--exact]` form for
+* semantic locators and positional (`index`) picks. `type` is a ccqa-side
+* alias of `fill` in both shapes. Flags MUST follow the action token —
+* putting them before it makes agent-browser fail with "Unknown subaction".
+*/
+function interactionToArgs(action) {
+	const loc = action.locator;
+	if (!loc) return null;
+	const abAction = action.action === "type" ? "fill" : action.action;
+	const takesInput = action.action === "fill" || action.action === "type";
+	if (!(loc.by !== "css" || action.index !== void 0 || action.action === "focus")) {
+		const args = [lit(abAction), val(loc.value)];
+		if (takesInput) args.push(val(action.value ?? ""));
+		return args;
+	}
+	if (!loc.value) return null;
+	const out = [lit("find")];
+	if (action.index !== void 0) {
+		if (loc.by !== "css") return null;
+		if (action.index === "first" || action.index === "last") out.push(lit(action.index));
+		else out.push(lit("nth"), lit(String(action.index)));
+		out.push(val(loc.value));
+	} else {
+		if (loc.by === "css") return null;
+		out.push(lit(loc.by), val(loc.value));
+	}
+	out.push(lit(abAction));
+	if (takesInput) out.push(val(action.value ?? ""));
+	if (loc.by === "role" && loc.name) out.push(lit("--name"), val(loc.name));
+	if (loc.by !== "css" && loc.exact) out.push(lit("--exact"));
+	return out;
+}
+//#endregion
+//#region src/diagnose/prompt.ts
+function buildDiagnosePrompt(input) {
+	const { script, specYaml, actions, failureLog, pageSnapshot, outputLanguage = "auto" } = input;
+	const numbered = numberLines(script);
+	const actionsSummary = actions.map((a, i) => {
+		const parts = [`${i + 1}. ${a.action}`];
+		if (a.assert) parts.push(`assert="${a.assert}"`);
+		if (a.locator) parts.push(`locator="${describeLocator(a.locator)}"`);
+		if (a.index !== void 0) parts.push(`index=${a.index}`);
+		if (a.value) parts.push(`value="${a.value}"`);
+		if (a.observation) parts.push(`→ ${a.observation}`);
+		return parts.join(" ");
+	}).join("\n");
+	return `You are diagnosing a failing E2E test. The test was generated from a recorded trace of the original interaction. Compare the failing run against the original spec and recorded actions to determine WHY the test failed and what the right fix is.
+
+${outputLanguageBlock(outputLanguage, "`reasoning`, `reason`", "code, type names (TIMING_ISSUE, etc.)")}## You have read-only filesystem tools
+
+You can call \`Grep\`, \`Glob\`, and \`Read\` against the current repository before producing the JSON.
+
+For SELECTOR_DRIFT specifically the failure log is usually NOT enough on its own — the runner only reports "selector X not visible". To confirm a rename, search the application source for the *type* of selector that's failing:
+
+- For \`[aria-label='OLD']\` failures: \`Grep\` for \`aria-label=\` (or i18n key \`OLD\`) in the app source. If you find a near-miss like \`aria-label="NEW"\` whose text is a superset/rephrase of the failing label, that is your evidence.
+- For \`[placeholder='OLD']\` failures: \`Grep\` for \`placeholder=\`.
+- For \`[role='OLD']\` or \`[data-testid='OLD']\`: same pattern.
+- For \`text=OLD\` failures: \`Grep\` the source / i18n bundles for \`OLD\`. Locale files (\`*.json\`, \`*.yml\`, \`messages.ts\`, etc.) often hold the canonical strings.
+
+You have **up to 10 tool turns**. Spend them on grep/read; do not loop. Only when you have concrete file:line evidence should you emit SELECTOR_DRIFT — otherwise prefer UNKNOWN with confidence < 0.4 and let the human decide.
+
+Do NOT attempt to write, edit, run shell commands, or hit the network. Only Grep/Glob/Read.
+
+## Diagnosis categories
+
+Pick exactly ONE category. The output JSON must follow the shape for that category.
+
+1. TIMING_ISSUE — element not yet present because the page hasn't loaded / navigated. Fix by inserting or extending sleeps.
+   {
+     "diagnosis": {
+       "type": "TIMING_ISSUE",
+       "fixes": [
+         { "kind": "insert", "line": <1-based>, "seconds": <int>, "reason": "<short>" },
+         { "kind": "increase", "line": <1-based of existing sleep>, "increase_to": <int>, "reason": "<short>" }
+       ]
+     },
+     "confidence": <0.0-1.0>,
+     "reasoning": "<why timing is the cause>"
+   }
+
+2. OVER_ASSERTION — the test is asserting something the spec never required, OR a recorded assertion that is environment-dependent (e.g. a placeholder text that varies). The right fix is to remove those lines from the test.
+   {
+     "diagnosis": {
+       "type": "OVER_ASSERTION",
+       "lines": [<1-based line numbers to remove>],
+       "reason": "<short>"
+     },
+     "confidence": <0.0-1.0>,
+     "reasoning": "<why this assertion isn't required by the spec>"
+   }
+
+3. SELECTOR_DRIFT — the page is healthy but a selector has been renamed/refined since the trace was recorded. The failure log will typically contain a snapshot showing the new selector. ONLY use this when you can name the exact replacement selector.
+   {
+     "diagnosis": {
+       "type": "SELECTOR_DRIFT",
+       "line": <1-based>,
+       "oldSelector": "<exact string in current line>",
+       "newSelector": "<exact replacement>",
+       "reason": "<short>"
+     },
+     "confidence": <0.0-1.0>,
+     "reasoning": "<evidence from failure log>"
+   }
+
+4. DATA_MISSING — the test depends on data (a record, a setup, a logged-in state) that no longer exists. Not auto-fixable; the human must reseed or update the spec.
+   {
+     "diagnosis": { "type": "DATA_MISSING", "reason": "<what is missing>" },
+     "confidence": <0.0-1.0>,
+     "reasoning": "<evidence>"
+   }
+
+5. UNKNOWN — none of the above fit, or evidence is too weak to choose.
+   {
+     "diagnosis": { "type": "UNKNOWN", "reason": "<short>" },
+     "confidence": <0.0-1.0>,
+     "reasoning": "<what you saw and why you can't classify>"
+   }
+
+## Confidence guidance
+
+- 0.9-1.0: failure log directly shows the cause (e.g. "selector X not found, snapshot lists Y" → SELECTOR_DRIFT)
+- 0.7-0.9: strong indirect evidence (e.g. timing pattern after navigation, or assertion text that doesn't appear in spec)
+- 0.4-0.7: plausible classification but multiple categories could explain it
+- < 0.4: prefer UNKNOWN over guessing
+
+## Rules
+
+- Your **final** assistant message must start with \`{\` and end with \`}\` — a single JSON object, nothing before or after. No prose preamble like "Confirmed: ...", no markdown fences, no commentary, no tool calls in the same turn. If you have an analysis sentence, put it in the \`reasoning\` field.
+- Line numbers refer to the numbered test script below (1-based).
+- For SELECTOR_DRIFT, \`oldSelector\` must match a substring of the script at that line; \`newSelector\` must be backed by a concrete file:line you read with Grep/Read (do not invent). Cite the evidence in \`reasoning\`.
+- For OVER_ASSERTION, only include lines that contain assert calls (\`abAssert*\`) or existence-checking waits (\`abWait\`); a recorded \`abWait("[selector]")\` is an implicit existence assertion and a valid removal candidate when the spec never required that element to be present.
+- Cross-check assertions against the spec YAML. If the spec doesn't require the assertion, OVER_ASSERTION is the better diagnosis than SELECTOR_DRIFT.
+
+## Test Spec (spec.yaml)
+${specYaml}
+
+## Recorded Actions (ir.json summary)
+${actionsSummary}
+
+## Test Script (with line numbers)
+${numbered}
+
+## Failure Log
+${failureLog.slice(0, 4e3)}${pageSnapshot ? formatPageSnapshot(pageSnapshot) : ""}`;
+}
+/**
+* Page snapshot captured by ccqa right after the failure (agent-browser
+* accessibility tree). When present, it usually decides SELECTOR_DRIFT vs
+* TIMING_ISSUE: a near-miss aria-label / role / placeholder in the
+* snapshot is direct evidence of a rename, while a tree that doesn't
+* contain the failing locator at all (without a near-miss) points to a
+* still-loading page or genuinely missing element.
+*/
+function formatPageSnapshot(snapshot) {
+	return `
+
+## Page Snapshot (accessibility tree captured right after the failure)
+
+This is the live state of the page when the test failed. Prefer this over your own assumptions:
+
+- If a near-miss of the failing selector appears here (e.g. failing \`[aria-label='A']\` and snapshot contains \`aria-label="A-prime"\`), that is direct evidence of SELECTOR_DRIFT — propose the snapshot's value as \`newSelector\`.
+- If the failing locator is genuinely absent and no near-miss exists, the page may be still loading (TIMING_ISSUE) or the spec is asserting something not on this page (OVER_ASSERTION / DATA_MISSING).
+- If the snapshot looks unrelated to the spec (e.g. error page, login wall), DATA_MISSING is likely.
+
+\`\`\`
+${snapshot}
+\`\`\``;
+}
+//#endregion
+//#region src/diagnose/diagnose.ts
+async function diagnose(input, options = {}) {
+	const { result: raw, isError } = await invokeClaudeStreaming({
+		prompt: buildDiagnosePrompt(input),
+		allowedTools: [
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		maxTurns: 20,
+		model: options.model
+	}, () => {});
+	if (isError) return {
+		result: null,
+		raw: raw ?? "",
+		sdkError: true
+	};
+	if (!raw) return {
+		result: null,
+		raw: "",
+		sdkError: false
+	};
+	const candidates = extractJsonCandidates(raw);
+	for (const candidate of candidates) {
+		let parsed;
+		try {
+			parsed = JSON.parse(candidate);
+		} catch {
+			continue;
+		}
+		const normalised = normaliseResult(parsed);
+		if (normalised) return {
+			result: normalised,
+			raw,
+			sdkError: false
+		};
+	}
+	return {
+		result: {
+			diagnosis: {
+				type: "UNKNOWN",
+				reason: "diagnose returned no parseable diagnosis JSON"
+			},
+			confidence: 0,
+			reasoning: truncate(raw, 1e3)
+		},
+		raw,
+		sdkError: false
+	};
+}
+/**
+* Pull every plausible JSON object out of `raw`. We try, in order:
+*   1. The whole string with code fences stripped (the prompt asks for
+*      JSON-only, so this is the happy path).
+*   2. Each balanced `{...}` block found by scanning the text. The model
+*      sometimes prefixes the JSON with a "Confirmed: ..." sentence or
+*      mentions partial JSON in its tool-using reasoning; we want to
+*      try the *last* well-formed object first because it's most likely
+*      the final answer, then earlier ones as a fallback.
+*
+* The caller `JSON.parse`s each candidate and stops at the first match
+* that normalises to a known DiagnosisResult.
+*/
+function extractJsonCandidates(raw) {
+	const out = [];
+	const stripped = stripFence(raw);
+	if (stripped) out.push(stripped);
+	const blocks = [];
+	let depth = 0;
+	let start = -1;
+	let inString = false;
+	let escaped = false;
+	for (let i = 0; i < raw.length; i++) {
+		const ch = raw[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inString = false;
+			continue;
+		}
+		if (ch === "\"") {
+			inString = true;
+			continue;
+		}
+		if (ch === "{") {
+			if (depth === 0) start = i;
+			depth++;
+		} else if (ch === "}") {
+			depth--;
+			if (depth === 0 && start >= 0) {
+				blocks.push(raw.slice(start, i + 1));
+				start = -1;
+			}
+		}
+	}
+	for (let i = blocks.length - 1; i >= 0; i--) {
+		const block = blocks[i];
+		if (!out.includes(block)) out.push(block);
+	}
+	return out;
+}
+function truncate(s, max) {
+	return s.length <= max ? s : `${s.slice(0, max)}... [truncated, ${s.length - max} more chars]`;
+}
+function stripFence(raw) {
+	return raw.trim().replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
+}
+function normaliseResult(parsed) {
+	if (!isObject(parsed)) return null;
+	const diagnosis = normaliseDiagnosis(parsed["diagnosis"]);
+	if (!diagnosis) return null;
+	return {
+		diagnosis,
+		confidence: typeof parsed["confidence"] === "number" ? clamp(parsed["confidence"], 0, 1) : 0,
+		reasoning: typeof parsed["reasoning"] === "string" ? parsed["reasoning"] : ""
+	};
+}
+function normaliseDiagnosis(raw) {
+	if (!isObject(raw)) return null;
+	switch (raw["type"]) {
+		case "TIMING_ISSUE": {
+			const fixes = normaliseSleepFixes(raw["fixes"]);
+			if (fixes.length === 0) return null;
+			return {
+				type: "TIMING_ISSUE",
+				fixes
+			};
+		}
+		case "OVER_ASSERTION": {
+			const lines = Array.isArray(raw["lines"]) ? raw["lines"].filter((n) => typeof n === "number" && Number.isFinite(n)) : [];
+			if (lines.length === 0) return null;
+			return {
+				type: "OVER_ASSERTION",
+				lines,
+				reason: typeof raw["reason"] === "string" ? raw["reason"] : ""
+			};
+		}
+		case "SELECTOR_DRIFT": {
+			const line = typeof raw["line"] === "number" ? raw["line"] : null;
+			const oldSelector = typeof raw["oldSelector"] === "string" ? raw["oldSelector"] : null;
+			const newSelector = typeof raw["newSelector"] === "string" ? raw["newSelector"] : null;
+			if (line === null || !oldSelector || !newSelector) return null;
+			return {
+				type: "SELECTOR_DRIFT",
+				line,
+				oldSelector,
+				newSelector,
+				reason: typeof raw["reason"] === "string" ? raw["reason"] : ""
+			};
+		}
+		case "DATA_MISSING": return {
+			type: "DATA_MISSING",
+			reason: typeof raw["reason"] === "string" ? raw["reason"] : ""
+		};
+		case "UNKNOWN": return {
+			type: "UNKNOWN",
+			reason: typeof raw["reason"] === "string" ? raw["reason"] : ""
+		};
+		default: return null;
+	}
+}
+function normaliseSleepFixes(raw) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) {
+		if (!isObject(item)) continue;
+		const line = typeof item["line"] === "number" ? item["line"] : null;
+		if (line === null) continue;
+		const reason = typeof item["reason"] === "string" ? item["reason"] : "";
+		if (item["kind"] === "insert") {
+			const seconds = typeof item["seconds"] === "number" ? item["seconds"] : null;
+			if (seconds === null) continue;
+			out.push({
+				kind: "insert",
+				line,
+				seconds,
+				reason
+			});
+		} else if (item["kind"] === "increase") {
+			const increaseTo = typeof item["increase_to"] === "number" ? item["increase_to"] : null;
+			if (increaseTo === null) continue;
+			out.push({
+				kind: "increase",
+				line,
+				increase_to: increaseTo,
+				reason
+			});
+		}
+	}
+	return out;
+}
+function isObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function clamp(n, lo, hi) {
+	if (n < lo) return lo;
+	if (n > hi) return hi;
+	return n;
+}
+//#endregion
+export { bracedRefsToJsExpression as $, progressEnd as A, isExpandedActionStep as B, error as C, info as D, hint as E, withBuffer as F, tryParseTestSpec as G, isJudgeBody as H, CREDENTIAL_ENV_KEYS as I, SessionNameSchema as J, AGENT_BROWSER_TARGET as K, collectIncludedBlockNames as L, step as M, timedPhase as N, meta as O, warn as P, isParamRequired as Q, expandActionSteps as R, emitRaw as S, header as T, parseBlockSpec as U, isExpandedJudgeByLlmStep as V, parseTestSpec as W, TargetIdSchema as X, SpecModeSchema as Y, isIncludeStep as Z, buildSpecEnvScrub as _, truncate as a, promoteMarkedAssert as b, toAgentBrowserArgs as c, surfaceAxisAside as d, envRefsToJsExpression as et, surfaceDefinitionBlock as f, buildProseEnvScrubMap as g, withCostTally as h, isObject as i, run as j, progress as k, numberLines as l, readCostTally as m, diagnose as n, resolveEnvRefs as nt, describeLocator as o, invokeClaudeStreaming as p, DEFAULT_SPEC_MODE as q, extractJsonCandidates as r, locatorToSelector as s, clamp as t, iterEnvRefNames as tt, outputLanguageBlock as u, scrubEnvValues as v, fix as w, blank as x, parseAbActionLine as y, expandSpec as z };