ccqa 1.58.2 → 1.59.0

package/dist/bin/ccqa.mjs

@@ -3143,7 +3143,7 @@ function formatDuration$1(ms) {
 	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, additionalDirectories } = options;
+	const { prompt, systemPrompt, allowedTools, disableThinking = false, effort, bashGuard, mcpServers, maxTurns, timeoutMs, env, model, cwd, onAbAction, onAbActionFailed, beforeAbCommand, silenceBashLog = false, envScrubMap = [], relaxAbConstraints = false, additionalDirectories } = options;
 	const resolvedModel = resolveModel(model);
 	const mergedEnv = buildInvocationEnv(env);
 	const abortController = new AbortController();
@@ -3171,52 +3171,35 @@ async function invokeClaudeStreaming(options, onEvent) {
 		env: mergedEnv,
 		...mcpServers ? { mcpServers } : {},
 		...disableThinking ? { thinking: { type: "disabled" } } : {},
-		hooks: onAbAction || onAbActionFailed ? {
+		...effort ? { effort } : {},
+		hooks: onAbAction || onAbActionFailed || bashGuard || beforeAbCommand ? {
 			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 {};
+				const guarded = bashGuard?.(cmd);
+				if (guarded) return {
+					decision: "block",
+					reason: guarded
+				};
 				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 {
+					const reason = abCommandBlockReason(cmd, envScrubMap);
+					if (reason !== null) 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."
+						reason
 					};
-					const runProducedUrl = findRunProducedOpenUrl(cmd, envScrubMap);
-					if (runProducedUrl !== null) return {
+					const checkpoint = beforeAbCommand?.(extractCcqaStepFromBashCommand(cmd) ?? void 0);
+					if (checkpoint) return {
 						decision: "block",
-						reason: `Do not open ${runProducedUrl} — that address was produced by this run (the id in it belongs to a record this run created), so the generated test would open a record later runs do not have. Reach the page the way a person does: click through from where the run already is. If the spec's instruction really names this exact address, put the id in a profile variable so it survives replay.`
+						reason: checkpoint
 					};
 				}
-				const assertMarker = relaxAbConstraints ? null : extractCcqaAssertFromBashCommand(cmd);
-				const ab = relaxAbConstraints ? null : extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
-				if ((ab !== null || assertMarker !== null) && onAbAction) {
+				const recorded = relaxAbConstraints ? null : abActionEventFromCommand(cmd);
+				if (recorded !== null && onAbAction) {
 					lastAbToolUseId = input.tool_use_id;
-					lastAbAnswerHolds = assertMarker === null ? null : markerHolds(assertMarker, ab);
-					const stepId = extractCcqaStepFromBashCommand(cmd);
-					onAbAction({
-						...ab !== null ? { abAction: ab } : {},
-						...stepId ? { stepId } : {},
-						...assertMarker !== null ? { assertMarker } : {},
-						...hasCcqaSecretPrefix(cmd) ? { secret: true } : {}
-					});
+					lastAbAnswerHolds = recorded.holds;
+					onAbAction(recorded.event);
 				} else lastAbToolUseId = null;
 				return {};
 			}] }],
@@ -3804,6 +3787,45 @@ async function fireMockPreToolUseHooks(msg, options) {
 		for (const matcher of matchers) for (const hook of matcher.hooks) await hook(input, block.id, { signal: new AbortController().signal });
 	}
 }
+/**
+* Why the trace refuses this agent-browser command, or null when it may run.
+* Shared by the Bash hook and the trace's own batch tool, so both enforce the
+* same replayability contract.
+*/
+function abCommandBlockReason(cmd, envScrubMap = []) {
+	if (isBlockedAbSubcommand(cmd)) return "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 "@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 `\`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 "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 "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 runProducedUrl = findRunProducedOpenUrl(cmd, envScrubMap);
+	if (runProducedUrl !== null) return `Do not open ${runProducedUrl} — that address was produced by this run (the id in it belongs to a record this run created), so the generated test would open a record later runs do not have. Reach the page the way a person does: click through from where the run already is. If the spec's instruction really names this exact address, put the id in a profile variable so it survives replay.`;
+	return null;
+}
+/**
+* What recording this command produces, and — for a marked probe — what its
+* output must say for the check to hold. Null when it records nothing.
+*/
+function abActionEventFromCommand(cmd) {
+	const assertMarker = extractCcqaAssertFromBashCommand(cmd);
+	const ab = extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
+	if (ab === null && assertMarker === null) return null;
+	const stepId = extractCcqaStepFromBashCommand(cmd);
+	return {
+		event: {
+			...ab !== null ? { abAction: ab } : {},
+			...stepId ? { stepId } : {},
+			...assertMarker !== null ? { assertMarker } : {},
+			...hasCcqaSecretPrefix(cmd) ? { secret: true } : {}
+		},
+		holds: assertMarker === null ? null : markerHolds(assertMarker, ab)
+	};
+}
+/** Whether a shell line runs agent-browser as a command (env prefixes allowed), not just mentions it. */
+function isAgentBrowserCommand(cmd) {
+	return splitShellStatements(cmd).some((st) => isAgentBrowserHead(splitLeadingEnvAssignments(st).command));
+}
 //#endregion
 //#region src/prompts/format.ts
 /**
@@ -3950,7 +3972,7 @@ function toAgentBrowserArgs(action) {
 		}
 		case "wait": {
 			const loc = action.locator;
-			if (!loc) return null;
+			if (!loc || loc.value.startsWith("--")) return null;
 			if (loc.by === "text") return [
 				lit("wait"),
 				lit("--text"),
@@ -4005,6 +4027,61 @@ function interactionToArgs(action) {
 	if (loc.by !== "css" && loc.exact) out.push(lit("--exact"));
 	return out;
 }
+/**
+* The marked probe that records an assert during a trace — the inverse of
+* `promoteMarkedAssert`, as the trace prompt's Assertion Protocol spells it.
+*/
+function markedAssertArgs(action) {
+	const loc = action.locator;
+	const sel = loc ? [val(locatorToSelector(loc))] : null;
+	switch (action.assert) {
+		case "text_visible": return action.value ? {
+			marker: "1",
+			tokens: [
+				lit("wait"),
+				lit("--text"),
+				val(action.value)
+			]
+		} : null;
+		case "url_contains": return action.value ? {
+			marker: `url_contains:${action.value}`,
+			tokens: [lit("get"), lit("url")]
+		} : null;
+		case "element_visible":
+		case "element_not_visible":
+			if (loc?.by === "role") return loc.name ? {
+				marker: action.assert,
+				tokens: roleProbeTokens(loc.value, loc.name, loc.exact === true)
+			} : null;
+			return sel ? {
+				marker: action.assert,
+				tokens: [
+					lit("get"),
+					lit("count"),
+					...sel
+				]
+			} : null;
+		case "element_enabled":
+		case "element_disabled": return sel ? {
+			marker: action.assert,
+			tokens: [
+				lit("is"),
+				lit("enabled"),
+				...sel
+			]
+		} : null;
+		case "element_checked":
+		case "element_unchecked": return sel ? {
+			marker: action.assert,
+			tokens: [
+				lit("is"),
+				lit("checked"),
+				...sel
+			]
+		} : null;
+		default: return null;
+	}
+}
 //#endregion
 //#region src/diagnose/prompt.ts
 function buildDiagnosePrompt(input) {
@@ -7868,7 +7945,7 @@ function reuseFirstContract(hasDraft, draftInvariant) {
 		"3. **Match the examples.** Write in the same style as the conventions examples: naming, structure, assertion phrasing, import layout. Where you follow an existing file rather than the plain reading of a guideline — a waiting pattern, a locator shape, a teardown structure — say which file, by path, in the comment. \"Following the existing implementation\" without naming it cannot be checked by the next reader, and it is how a pattern that was right once outlives the reason for it."
 	];
 	if (hasDraft) {
-		rules.push("4. **The draft is ground truth.** The mechanical draft below encodes the recorded route. Do not change the meaning of its operation sequence or its assertions — no reordering, dropping, or weakening. You may rewrite locators when the conventions or the sources you read justify a better one.");
+		rules.push("4. **The draft is ground truth for the route, not for the form of its checks.** Keep its operation sequence: no reordering or dropping of the actions the case needs. Its `expect` lines are what the recorder observed on the way, written in one fixed form (`await expect(...)`, one per observation). Which of them the test keeps, and in which form — hard or soft, where the check lives, how the locator is scoped — is decided by the case's expected results and the project's conventions, never by the draft. Where the conventions and the draft disagree, follow the conventions. What an expected result claims must still be checked: never loosen the value it states.");
 		if (draftInvariant) rules.push(`5. ${draftInvariant}`);
 	}
 	return `## Reuse contract\n\n${rules.join("\n")}`;
@@ -7916,6 +7993,8 @@ function buildLlmGenPrompt(input) {
 	sections.push(input.taskInstructions);
 	const steps = input.steps.map(formatStep).join("\n");
 	sections.push(`## Test spec\n\nTitle: ${input.specTitle}\n\nSteps:\n${steps}`);
+	const facts = caseFacts(input);
+	if (facts) sections.push(facts);
 	if (input.draft) sections.push(`## Mechanical draft (recorded ground truth)\n\nPath: ${input.draft.path}\n\n\`\`\`
 ` + input.draft.contents + "\n```");
 	if (input.resources.length > 0) {
@@ -7936,6 +8015,19 @@ These are the project's rules for the code you write, not background reading. Co
 	return sections.join("\n\n") + languageDirective(input.language);
 }
 /**
+* What the case states beyond its steps. Project conventions key rules on
+* these (which checks are the case's, where it may run), and the review that
+* follows already reads them — a rewrite without them can only guess.
+*/
+function caseFacts(input) {
+	const parts = [];
+	if (input.expectations && input.expectations.length > 0) parts.push(`### Expected results\n\nThe case states these for the flow as a whole. They are the checks the test exists for:\n\n${input.expectations.map((e) => `- ${body(e)}`).join("\n")}`);
+	if (input.cleanup && input.cleanup.length > 0) parts.push(`### Cleanup steps\n\n${input.cleanup.map(formatStep).join("\n")}`);
+	if (input.cleanupExpectations && input.cleanupExpectations.length > 0) parts.push(`### Expected results of the cleanup\n\n${input.cleanupExpectations.map((e) => `- ${body(e)}`).join("\n")}`);
+	for (const c of input.context ?? []) parts.push(`### ${c.heading}\n\n${c.body.trim()}`);
+	return parts.length === 0 ? "" : `## About this case\n\n${parts.join("\n\n")}`;
+}
+/**
 * Prompt for one iteration of the verification loop: the generated files
 * failed their run command; ask for corrected files under the same contract.
 */
@@ -8304,7 +8396,7 @@ function weakerTwin(file, source) {
 function decidesNothing(input) {
 	const source = input.files.get(input.testPath);
 	if (source === void 0 || input.caseText.join("").trim().length === 0) return [];
-	if (/\bexpect\(|\bjudgeByLlm\b/.test(source)) return [];
+	if (/\bexpect(?:\.soft)?\(|\bjudgeByLlm\b/.test(source)) return [];
 	return [{
 		file: input.testPath,
 		line: 1,
@@ -8373,7 +8465,7 @@ function containerOfPageText(file, source) {
 */
 function explained(all, i) {
 	let above = i - 1;
-	while (above >= 0 && /\bexpect\(|^\s*$|^\s*\)/.test(all[above] ?? "")) above -= 1;
+	while (above >= 0 && /\bexpect(?:\.soft)?\(|^\s*$|^\s*\)/.test(all[above] ?? "")) above -= 1;
 	return /^\s*\/\//.test(all[above] ?? "");
 }
 /**
@@ -8388,7 +8480,7 @@ function explained(all, i) {
 function unjustifiedFirst(file, source) {
 	const all = lines(source);
 	return all.flatMap((text, i) => {
-		if (!/\bexpect\(/.test(text) || !/\.first\(\)/.test(text)) return [];
+		if (!/\bexpect(?:\.soft)?\(/.test(text) || !/\.first\(\)/.test(text)) return [];
 		if (explained(all, i)) return [];
 		return [{
 			file,
@@ -8463,7 +8555,7 @@ function assertedStrings(text, locators) {
 function unaskedAssertions(file, source, locators, said) {
 	const all = lines(source);
 	return all.flatMap((text, i) => {
-		if (!/\bexpect\(/.test(text)) return [];
+		if (!/\bexpect(?:\.soft)?\(/.test(text)) return [];
 		const strings = assertedStrings(text, locators);
 		if (strings.length === 0 || strings.some((s) => said.includes(s))) return [];
 		if (explained(all, i)) return [];
@@ -14783,6 +14875,10 @@ async function generateWithLlmEngine(req) {
 		specTitle: ctx.spec.title,
 		steps: req.steps,
 		draft: req.draft,
+		expectations: ctx.expectations,
+		cleanup: ctx.cleanup,
+		cleanupExpectations: ctx.cleanupExpectations,
+		context: ctx.context ?? [],
 		...req.draftInvariant ? { draftInvariant: req.draftInvariant } : {},
 		resources: resources.map(toPromptResource),
 		conventionSections: conventions.sections,
@@ -15467,7 +15563,7 @@ function headerPreserveRule(header, titleSuffix) {
 * rejection, which costs a whole round.
 */
 function stepCommentPreserveRule() {
-	return "**Keep every `test.step(...)` block, with its title exactly as the draft wrote it.** Those titles are how the evidence table, the run's per-step screenshots and the review of this test say which assertions belong to which step. A reshaped one parses as no step at all, and every step then reads as deciding nothing. Keep the wording, the numbering and the punctuation, and keep each step's actions inside its own block — a step's call to a page-object method belongs in the block, not outside it. Do not merge, split or reorder the blocks. A test already at this path may have been written by an older ccqa in a different shape: the draft is what this file must look like, not that one.";
+	return "**Keep every `test.step(...)` block, with its title exactly as the draft wrote it.** Those titles are how the evidence table, the run's per-step screenshots and the review of this test say which assertions belong to which step. A reshaped one parses as no step at all, and every step then reads as deciding nothing. Keep the wording, the numbering and the punctuation, and keep each step's actions inside its own block — a step's call to a page-object method belongs in the block, not outside it. Do not merge, split or reorder the blocks. A test already at this path may have been written by an older ccqa in a different shape: the draft's step blocks are what this file must keep, not that one's.";
 }
 /**
 * Told to the rewrite, because the alternative failure is silent: a claim
@@ -24539,1116 +24635,1364 @@ async function readLockBody(lockPath) {
 	}
 }
 //#endregion
-//#region src/prompts/trace.ts
-function generateSessionName() {
-	return `ccqa-trace-${buildRunId()}`;
+//#region src/ir/accessible-name.ts
+/**
+* A recorder reads an accessible name off a snapshot and writes it as the
+* attribute it guessed the name came from. The name can come from a `<label>`
+* or `aria-labelledby` instead, and the attribute's absence is not evidence
+* about the element. See docs/targets.md for the measurement.
+*/
+const NAMING_ATTR = /^\[\s*aria-label\s*=\s*(?:"([^"]*)"|'([^']*)')\s*\]$/;
+/**
+* The name this selector may be after, or null.
+*
+* `aria-label` only. `[name='email']` and `[title='Close']` are attributes that
+* mean what they say, and a zero from one of those is evidence.
+*/
+function nameFromAttributeSelector(selector) {
+	const m = NAMING_ATTR.exec(selector.trim());
+	const name = m?.[1] ?? m?.[2];
+	return name === void 0 || name === "" ? null : name;
 }
 /**
-* Build the trace system prompt. `input.steps` is a flat list with includes
-* already expanded (each step carries id / source / instruction / expected).
-* The spec opens URLs via explicit step instructions (e.g.
-* `instruction: "${APP_URL}/articles を開く"`).
+* The role of the first node in an accessibility snapshot whose name is
+* exactly `name`, or null.
 *
-* In v0.4 every spec is traced from scratch — block contents are inlined
-* into the spec's own step list at expand time, so the prompt has no
-* special "this is a block" mode. The `source` tag on each step still
-* distinguishes spec-native steps from inlined block steps for the
-* `// step:` comments in the eventual codegen output.
+* agent-browser prints one node per line as `<role> "<name>"`. Matched on the
+* whole name, so a tree holding both "Priority" and "Priority *" answers for
+* the one that was asked, and refused when two roles carry it.
 */
-function buildTraceSystemPrompt(input) {
-	const sessionName = input.sessionName ?? generateSessionName();
-	const firstStepId = input.steps[0]?.id ?? "step-01";
-	const callerGuidance = input.instruction ? `## Caller Guidance
-
-The caller provided extra guidance for this recording — for example, a drift
-audit's finding about what a previous recording of this spec got wrong. Treat
-it as advice on what to avoid or verify while recording; the spec's steps
-above remain the contract for what to do.
-
-${input.instruction}
-
-` : "";
-	const stepsText = input.steps.map((step) => [
-		`### ${step.id} [${step.source}]`,
-		`- **Instruction**: ${step.instruction}`,
-		...step.expected ? [`- **Expected**: ${step.expected}`] : []
-	].join("\n")).join("\n\n");
-	const expectationsText = renderExpectations(input.expectations ?? []) + renderCleanupExpectations(input.cleanupExpectations ?? []);
-	const contextText = renderContext(input.context ?? []);
-	const conventionsText = renderConventions(input.conventions ?? []);
-	return `You are an expert QA engineer executing a browser E2E test. Execute each step precisely and record every browser action as a structured log line.
-
-## Session
-
-SESSION NAME: \`${sessionName}\`
-
-Always pass \`--session ${sessionName}\` to every \`agent-browser\` command.
-
-**Always prefix every \`agent-browser\` command with a \`CCQA_STEP=<step-id>\`
-env assignment naming the spec step it executes**, e.g.
-
-\`\`\`bash
-CCQA_STEP=step-03 agent-browser --session ${sessionName} click "text=Submit"
-\`\`\`
-
-This prefix is what ties each recorded action to its step in the generated
-test — a command without it loses its step attribution.
-
-**Anything you do before the first step carries \`CCQA_STEP=${SETUP_STEP_ID}\`.** Signing
-in, opening the application, putting the account where the precondition says it
-starts — those are not step-01, and marking them as step-01 makes the first
-step of the case look like it does all of it. The next \`CCQA_STEP=\` names the
-first step the case actually lists.
-
-Other env assignments may precede it (\`FOO=x CCQA_STEP=step-02 agent-browser ...\`); agent-browser
-itself ignores the variable.
-
-Verification commands additionally carry a \`CCQA_ASSERT=<marker>\` env
-assignment (alongside \`CCQA_STEP\`) that records the check as a test
-assertion — see "Assertion Protocol".
-
-**A command that types into a password field carries \`CCQA_SECRET=1\`** as
-well, e.g.
-
-\`\`\`bash
-CCQA_STEP=step-01 CCQA_SECRET=1 agent-browser --session ${sessionName} find label "Password" fill "\${LOGIN_PASSWORD}"
-\`\`\`
-
-A password field is an \`<input type="password">\` — the snapshot shows its
-value as dots, and nothing else about the page is a password. The prefix is
-what stops the typed value from being written to the recording: a value that
-came from a \`\${VAR}\` is kept as that reference, and one typed literally is
-dropped along with its command.
-
-## Browser Commands
-
-\`\`\`
-CCQA_STEP=<step-id> agent-browser --session SESSION open <url>
-CCQA_STEP=<step-id> agent-browser --session SESSION snapshot
-CCQA_STEP=<step-id> agent-browser --session SESSION click "<selector>"
-CCQA_STEP=<step-id> agent-browser --session SESSION fill "<selector>" "<value>"
-CCQA_STEP=<step-id> agent-browser --session SESSION check "<selector>"
-CCQA_STEP=<step-id> agent-browser --session SESSION uncheck "<selector>"
-CCQA_STEP=<step-id> agent-browser --session SESSION press <Key>
-CCQA_STEP=<step-id> agent-browser --session SESSION select "<selector>" "<value>"
-CCQA_STEP=<step-id> agent-browser --session SESSION hover "<selector>"
-CCQA_STEP=<step-id> agent-browser --session SESSION wait --text "<text>" [--timeout <ms>]
-CCQA_STEP=<step-id> agent-browser --session SESSION wait --load networkidle
-CCQA_STEP=<step-id> agent-browser --session SESSION get count "<selector>"   # element-existence check (returns a number, fast)
-agent-browser --session SESSION cookies clear                                # pre-step preamble — no CCQA_STEP prefix
-CCQA_STEP=<step-id> agent-browser --session SESSION find <locator> <value> <action> [<input>] [--name "<n>"] [--exact]
-CCQA_STEP=<step-id> agent-browser --session SESSION upload "<input[type=file] selector>" <file> [<file> ...]
-# See "Selector Rules" for the full \`find\` subset.
-# IMPORTANT: do NOT use \`wait "<css-selector>"\`. agent-browser ignores --timeout on a
-# CSS-selector wait and blocks for ~150s when the selector never matches, killing the run.
-# Wait for readiness with \`wait --text\`, \`wait --load networkidle\`, or just use \`find\`
-# (which waits internally). To check an element exists, use \`get count "<selector>"\`.
-\`\`\`
-
-## Selector Rules
-
-**ALLOWED selector formats — use ONE of these everywhere a selector appears (click, fill, wait, assert, ...):**
-
-| Format | Use when |
-|--------|----------|
-| \`[aria-label='label']\` | Element **has the \`aria-label\` attribute** — **FIRST CHOICE**. A name the snapshot shows is not proof of one: a name can come from a \`<label>\`, from the element's own text, or from \`aria-labelledby\`, and this selector then matches nothing. |
-| \`text=visible text\` | Unique visible text, no aria-label — for **actions**. Not for a \`get count\` probe: see step 3. |
-| \`[placeholder='text']\` | Input identified by placeholder |
-| \`[type='password']\` | Password inputs only |
-| \`a[href*='pattern']\` | Links where \`text=\` fails — use the URL pattern from the ARIA snapshot |
-| \`[data-testid='...']\`, \`[data-qa='...']\` | Specific attribute selectors when an aria-label is absent |
-
-**FORBIDDEN — these break recorded tests and are rejected by the hook layer:**
-
-- \`@ref\` / \`@e1\` / \`e14\` — reference IDs are session-specific and change every run.
-- **Bare tag selectors**: \`button\`, \`a\`, \`div\`, \`td\`, \`tr\`, \`main a\`, \`table tbody tr:nth-child(N)\`. These match every element of that tag and are non-deterministic on replay. **This includes the inner selector inside \`find first/last/nth\`** — see the \`find\` rules below.
-- \`[role='button']\` or \`[type='checkbox']\` alone — matches too many elements.
-- **Playwright-only pseudo-classes**: \`:has-text()\`, \`:text-is()\`, \`:text-matches()\`, \`:visible\`. agent-browser's CSS engine does not implement them. They do not error — \`get count\` answers \`0\` and \`find\` reports no element — so a test using one fails while looking like the page lost the element. Use \`text=...\` or plain CSS instead.
-- JavaScript execution (\`eval\`, \`js\`) — blocked by the hook layer.
-
-### \`find\` subset (fallback when no ALLOWED CSS uniquely targets the element)
-
-When repeated aria-labels / visible text make ALLOWED selectors ambiguous (e.g. a chat client where every message row has the same "1 reply" button), use one of these — they record as structured actions and replay deterministically:
-
-\`\`\`
-find role <role> <action> [--name "<n>"] [--exact]
-find text|label|placeholder|alt|title "<text>" <action> [--exact]
-find testid "<id>" <action>
-find first|last "<ALLOWED-css>" <action>
-find nth <index> "<ALLOWED-css>" <action>
-\`\`\`
-
-\`<action>\` is one of \`click | dblclick | fill | type | hover | focus | check | uncheck\`. For \`fill\`/\`type\`, the input value follows the action: \`find label "Email" fill "user@example.com"\`.
-
-**Rules for \`find\`:**
-
-1. Try ALLOWED selectors first. Only reach for \`find\` when they demonstrably cannot uniquely target the element.
-2. **The inner selector for \`first/last/nth\` MUST be one of the ALLOWED formats above.** Never pass a bare tag — "the last button" is meaningless on replay.
-3. \`find last\` is reliable only when the layout guarantees "the target is the bottom-most match" (e.g. the most-recently-sent chat message). Be explicit in the AB_ACTION label.
-4. Argument order is \`<value> <action> [flags]\` — flags after the action. Putting \`--name\` / \`--exact\` before the action makes agent-browser fail with "Unknown subaction".
-5. \`--name "<n>"\` is **role-only**. Never pass it to \`find text\`, \`find label\`, etc.
-6. \`--name\` matches by substring. Add \`--exact\` whenever the name you read from the snapshot is the element's whole accessible name — without it a short name such as "Log in" also matches "Log in with Google" and "Log in with SSO", and the recording silently pins the first of them.
-7. \`find\` includes its own wait; do not chain a \`wait\` before it.
-8. **A step that names an element by position gets a positional locator.** "the first row", "the topmost item", "the latest message" identify by \`first\`/\`last\`/\`nth\` on a stable inner selector — never by the title, subject, or body text that record happened to carry. That text is data the environment supplies: pinning it makes the test pass only while that same record stays in that position, and the next run opens a different one.
-9. **A string read off a snapshot row is an accessible name, not a label.** A row like \`textbox "Email"\` says the field's accessible name is "Email" — which \`find role textbox --name "Email" --exact\` matches and \`find label "Email"\` matches only when the page also associates a \`<label>\` with the input. Many forms do not. Record \`find label\` only when you confirmed the association (there is a \`<label for=...>\`, or the input sits inside the label); otherwise use the role form with \`--name\`.
-
-**Examples:**
-
-- ✓ \`find last "[data-testid='reply-link']" click\` — specific attribute + layout-guaranteed last match
-- ✓ \`find role button click --name "Submit"\` — role + accessible name (flags after action)
-- ✓ \`find role button click --name "Log in" --exact\` — short name needs \`--exact\`, or "Log in with SSO" matches too
-- ✗ \`find role button --name "Submit" click\` — wrong order
-- ✗ \`find last "button" click\` — bare tag
-
-### Selector workflow
-
-1. Run \`snapshot\` and read the ARIA tree.
-2. Identify the element; note its exact \`aria-label\` if present.
-3. If the element really carries \`aria-label\` → use \`[aria-label='...']\`. Otherwise → use \`text=...\` **for the action**.
-   For a **\`get count\` probe** neither is safe: \`get count\` takes plain CSS and answers \`0\` for anything else, and an \`aria-label\` selector for a name the element does not carry as that attribute counts \`0\` too — both report an element that is plainly there as missing. Probe with \`[data-testid='...']\`, or with \`find role <role> text --name "<accessible name>" --exact\`, which asks the accessibility tree the snapshot came from.
-4. For links where \`text=\` fails, find the link's URL in the snapshot and use \`a[href*='...']\` with a distinctive substring.
-5. For checkboxes: try \`check "text=Label"\` or \`check "[aria-label='Label']"\`.
-6. If repeated labels make every ALLOWED selector ambiguous → use the \`find\` subset above.
-7. Never guess. If a selector fails, take a fresh snapshot before retrying.
-8. **A click that reports success but changes nothing means the element sits outside the visible part of an inner scroll container** — the event dispatches, the app never reacts, and no error is printed. Run \`scrollintoview\` on the element and click again. Scroll to the element itself, addressed by a CSS selector (\`scrollintoview "button.primary-action"\`); \`scrollintoview "text=…"\` can land on a text node that leaves the control still clipped. Do not read this as a product bug or reach for a \`@ref\` — verify by checking that the DOM changed (e.g. \`get count\` on what the click should have produced).
-
-### Special input types
-
-**contenteditable / RichText editors**: \`fill "[contenteditable='true']" "<text>"\` works on contenteditable elements (chat composers, WYSIWYG bodies) — agent-browser sets the text directly. Use a single \`fill\`; do NOT just \`click\` the field and rely on \`keyboard inserttext\` (that keystroke command is not recorded as a structured action, so the text never makes it into the generated test and the field ends up empty on replay).
-
-**combobox / select with a required marker (\`*\`)**: required form fields often include the marker in their accessible name. If \`find role combobox click --name "<label>"\` misses, prefer \`find label "<label>" click\` or \`click "[aria-label='<label> *']"\`.
-
-**Starting the cleanup**: the undo's first command must be the navigation that puts the browser where the undo can act — the same \`navigate\` you would issue if you arrived with the page freshly opened. Do not begin it from wherever the steps happened to end. The undo exists for the runs that went wrong, and on those the browser is not where the last step left it; a cleanup recorded as "click the menu that is on screen" then fails, and what the case created stays in the environment. Record the navigation even when it changes nothing at recording time.
-
-**Verifying cleanup / deletion**: assert the *absence* of the deleted thing, not the surrounding listing screen's text. Wait for the deletion to settle with \`wait --fn "!document.body.innerText.includes('<unique-label>')"\`, then record the assert with a marked probe: \`CCQA_ASSERT=element_not_visible ... get count "text=<unique-label>"\` (see Assertion Protocol) — never \`wait "<css-selector>" --state hidden\` (blocks the daemon) and never \`wait --text "<navbar label>"\` (passes regardless of the deletion).
-
-**File inputs (\`<input type="file">\`) / OS file-picker dialogs**: do NOT \`click\` the input — that opens the OS picker, which agent-browser cannot drive. Use \`upload "<selector>" <path>\` instead. agent-browser sets the input's files directly via the underlying browser API, no native dialog ever opens. Use an ALLOWED selector to identify the input (\`[aria-label='…']\`, \`[data-testid='…']\`, \`[type='file']\` only when it's unique on the page). File paths must be plain shell args — wrap each in \`"\` for safety. Reference fixtures via \`\${CCQA_FIXTURES_DIR}/<name>\` so the same spec works locally and in CI; conventionally fixtures live under \`.ccqa/fixtures/\` and the env var resolves there. Multi-file inputs accept several positionals: \`upload "[aria-label='Attach']" "\${CCQA_FIXTURES_DIR}/a.pdf" "\${CCQA_FIXTURES_DIR}/b.pdf"\`.
-
-## Test Specification
-
-Title: ${input.title}
-
-Each step's instruction names the URL to open directly (or via \`\${ENV_VAR}\`). Open exactly the URL the step says to open.
-
-## Steps
-
-${stepsText}
-${expectationsText}${contextText}${conventionsText}
-## Execution Workflow
-
-For each step:
-1. Emit \`STEP_START|<step-id>|<short description>\`.
-2. Run \`snapshot\` and identify selectors from the ARIA tree.
-3. Execute the action using an ALLOWED selector (see Selector Rules), prefixing the command with \`CCQA_STEP=<step-id>\` like every agent-browser command in the step.
-4. Emit \`AB_ACTION|...\` for every browser action (see AB_ACTION Protocol).
-5. Run \`snapshot\` again to verify the outcome.
-6. Confirm at least **two independent signals** (URL change, element appearance, text change, ...). This is how *you* decide the step worked and it is safe to continue. It is not what gets recorded.
-7. Record as assertions only the signals the step's own \`expected\` asks about, by putting a \`CCQA_ASSERT=<marker>\` prefix on the verification command itself (see Assertion Protocol). Every assert type has a marker form; a printed \`AB_ACTION|assert|...\` line records nothing.
-8. Emit \`STEP_DONE\`, \`ASSERTION_FAILED\`, or \`STEP_SKIPPED\`.
-
-**Protocol lines are recorded ONLY from your plain assistant text.** Every
-\`STEP_START\` / \`STEP_DONE\` / \`RUN_COMPLETED\` line MUST be printed as normal
-message text between tool calls — never through Bash (\`echo\` etc.) and never
-omitted. Step attribution of browser actions comes from the \`CCQA_STEP\`
-prefix on each command (that prefix is authoritative, not the \`STEP_START\`
-line). **Assertions are recorded only from the \`CCQA_ASSERT\` prefix on
-verification commands** — a command that ran, whose failure rolls the record
-back. A printed \`AB_ACTION|assert|...\` line performs nothing, so nothing
-proves it; it is reported and not recorded.
-
-**After form submission or navigation:** take a fresh snapshot before continuing. If an intermediate screen appears (account selection, role picker, ...), complete it and emit AB_ACTION for each interaction.
-
-## Guardrails
-
-- **Stop after 3 consecutive failures on the same step** — emit \`ASSERTION_FAILED\` and report the blocker.
-- **No workarounds.** If all ALLOWED selectors fail, emit \`ASSERTION_FAILED|...|selector-drift: ...\`. Do NOT fall back to coordinate clicks, mouse moves, or \`Tab\`+\`Enter\` keyboard navigation — they cannot be recorded as reliable test actions.
-- Do NOT retry a selector without taking a fresh snapshot first.
-- Do NOT work around blockers (login walls, missing data, captchas) — stop and report.
-- **Do NOT suppress errors.** Never use \`2>/dev/null\`, \`|| true\`, \`; true\`, or any technique that hides agent-browser failures. Each \`agent-browser\` invocation must be its own standalone Bash call. Chaining multiple agent-browser commands with \`&&\` / \`;\` / \`|\` is rejected by the hook layer.
-- **If \`agent-browser\` is not found, stop immediately.** Do not run \`which\`, \`find\`, \`npm ls\`, \`npm install\`, \`npx\`, \`brew\`, or any other discovery / installation command. Emit one line and terminate: \`ASSERTION_FAILED|step-XX|agent-browser binary not available in PATH\`.
-
-## Source Code Reference
-
-You have \`Read\`, \`Grep\`, and \`Glob\` to inspect the application source code. Use them proactively to find correct selectors — do NOT guess \`a[href*='...']\` patterns.
-
-**When**: before clicking a link (find the \`href\`); before navigating to a new page (understand routing); when an ARIA element exists but no ALLOWED selector matches (find the actual HTML attributes).
-
-**How**: \`Grep\` for UI text / component names / URL patterns → \`Read\` the JSX/TSX to find \`href\`, \`aria-label\`, \`data-testid\`, or class names → build a precise ALLOWED selector.
-
-**Rules**: only READ source files, never modify them. Keep searches focused.
-
-## Waiting for Async Operations
-
-Prefer \`wait\` over polling:
-
-\`\`\`bash
-CCQA_STEP=<step-id> agent-browser --session ${sessionName} wait --text "<completion text>"
-\`\`\`
-
-If polling is required (e.g. waiting for a spinner to disappear):
-
-\`\`\`bash
-for i in $(seq 1 18); do
-  sleep 10
-  result=$(agent-browser --session ${sessionName} snapshot 2>&1)
-  echo "$result" | grep -q "<done indicator>" && break
-done
-CCQA_STEP=<step-id> agent-browser --session ${sessionName} snapshot
-\`\`\`
-
-After waiting, always take a final snapshot. Emit \`AB_ACTION|wait|text=<text>|<label>\`.
-
-## AB_ACTION Protocol
-
-After **every** browser action, emit one line (outside any code block):
-
-\`\`\`
-AB_ACTION|cookies_clear
-AB_ACTION|open|<url>
-AB_ACTION|click|<selector>|<visible label>
-AB_ACTION|dblclick|<selector>|<visible label>
-AB_ACTION|fill|<selector>|<value>|<aria label>
-AB_ACTION|check|<selector>|<visible label>
-AB_ACTION|uncheck|<selector>|<visible label>
-AB_ACTION|press|<Key>
-AB_ACTION|select|<selector>|<value>|<aria label>
-AB_ACTION|hover|<selector>|<visible label>
-AB_ACTION|scroll|<direction>|<pixels>
-AB_ACTION|drag|<source selector>|<target selector>|<source label>
-AB_ACTION|upload|<file-input selector>|<file1>[|<file2>...]
-AB_ACTION|wait|<selector or text>|<label>
-AB_ACTION|snapshot|<key observation, max 100 chars>
-
-# find_* (semantic locator fallback). <extra> = role's --name OR nth's index OR "".
-# <exact> = literal "exact" if --exact was passed, "" otherwise. Keep empty pipe slots.
-AB_ACTION|find_click|<locator>|<value>|<extra>|<exact>|<label>
-AB_ACTION|find_dblclick|<locator>|<value>|<extra>|<exact>|<label>
-AB_ACTION|find_hover|<locator>|<value>|<extra>|<exact>|<label>
-AB_ACTION|find_focus|<locator>|<value>|<extra>|<exact>|<label>
-AB_ACTION|find_check|<locator>|<value>|<extra>|<exact>|<label>
-AB_ACTION|find_uncheck|<locator>|<value>|<extra>|<exact>|<label>
-AB_ACTION|find_fill|<locator>|<value>|<extra>|<exact>|<input>|<label>
-AB_ACTION|find_type|<locator>|<value>|<extra>|<exact>|<input>|<label>
-\`\`\`
-
-Selectors in AB_ACTION must follow Selector Rules. \`find_*\` lines use the locator + value pair instead of a separate selector. Do NOT include literal \`|\` inside any field — replace with a space if necessary.
-
-**CRITICAL — record only successful actions.** The AB_ACTION stream is the canonical replay sequence: every line must be reproducible on a fresh browser session.
-
-- A non-zero exit from agent-browser (selector not found, element not interactable, timeout) → **do NOT emit AB_ACTION** for that attempt. Switch selector and only emit the AB_ACTION for the call that finally succeeded.
-- If you tried several selectors / \`find_*\` locators for the same logical action, emit AB_ACTION for the **last working one only**. Multiple failed attempts in a row will all fail at replay validation and silently delete the step from the generated test.
-- An assertion follows the same rule: mark only the check that verified on the current page in the current snapshot.
-- **Open only a URL the step names.** A step's \`open\` takes the address its own instruction gives — a \`\${VAR}\` plus the literal tail after it. Never open an address the run produced: the id in \`/items/01H8XZ...\` belongs to the record this run created, and opening it next time visits a record that run does not have (or worse, one it does, silently testing the wrong thing). Reach such a page the way a person does — click through from where the run already is.
-
-- **Environment-failure recovery is not part of the test.** If a session times out, a network blip drops you to login, or the app crashes and you re-login / re-navigate / re-fill to recover, do NOT emit AB_ACTION for the recovery operations.
-- If a step ultimately fails after retries: emit \`ASSERTION_FAILED\` and STOP. Do not leave half-recorded actions in the stream.
-
-## Assertion Protocol
-
-Record each signal you verified as an assertion. The **primary mechanism** is
-a \`CCQA_ASSERT=<marker>\` env prefix on the verification command itself — the
-marker rides the same channel as the command, so the assertion is captured
-even if you print no protocol text. The check you were going to run anyway
-becomes the recorded assertion:
-
-\`\`\`bash
-# text_visible — the marked wait IS the assertion (no separate assert line)
-CCQA_STEP=<step-id> CCQA_ASSERT=1 agent-browser --session SESSION wait --text "Submitted" --timeout 3000
-# element_visible / element_not_visible — mark the get-count probe
-CCQA_STEP=<step-id> CCQA_ASSERT=element_visible agent-browser --session SESSION get count "[aria-label='Settings']"
-CCQA_STEP=<step-id> CCQA_ASSERT=element_not_visible agent-browser --session SESSION get count "text=Deleted item"
-# url_contains — the substring rides in the marker; put it on \`get url\`
-CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session SESSION get url
-# element state — mark the \`is\` probe that asks for it
-CCQA_STEP=<step-id> CCQA_ASSERT=element_disabled agent-browser --session SESSION is enabled "#submit"
-CCQA_STEP=<step-id> CCQA_ASSERT=element_checked agent-browser --session SESSION is checked "#opt-in"
-\`\`\`
-
-**Marker semantics:**
-
-| Marker | On command | Records |
-|--------|------------|---------|
-| \`1\` (alias of \`text_visible\`) | \`wait --text "<text>"\` | \`assert text_visible <text>\` — replaces the wait (the recorded assert waits itself) |
-| \`element_visible\` | \`get count "<selector>"\` | \`assert element_visible <selector>\` |
-| \`element_not_visible\` | \`get count "<selector>"\` | \`assert element_not_visible <selector>\` (use \`text=<text>\` as the selector to assert text absence) |
-| \`url_contains:<substring>\` | any command | \`assert url_contains <substring>\` in addition to whatever the command records |
-| \`element_enabled\` / \`element_disabled\` | \`is enabled "<selector>"\` | \`assert <marker> <selector>\` |
-| \`element_checked\` / \`element_unchecked\` | \`is checked "<selector>"\` | \`assert <marker> <selector>\` |
-
-- A marked command that exits non-zero records nothing — fix the check and re-run it.
-- A marker that doesn't match its command (e.g. \`CCQA_ASSERT=1\` on a \`click\`) is ignored with a warning — never do that.
-- \`get count\`, \`get url\` and \`is\` exit 0 regardless of what they print. **Read the output**: if the printed count / URL / \`true\`-\`false\` contradicts the marker, the signal did NOT verify — treat it as a failed verification (emit \`ASSERTION_FAILED\` if the step cannot be confirmed another way).
-- **Assert the thing, not how much of it there is.** A step that says a list, a table or a section is shown is satisfied by the list being there. Do not assert the count it happened to have, and never assert an empty-state message ("no items yet") unless the step's own \`expected\` asks for emptiness — the next run has one more record than this one and the test breaks for a reason nobody chose.
-
-- **Assert what the step asks about, nothing else.** The \`expected\` is the contract; anything else you happened to see on the way is not. A nav item, a heading or a greeting that the step never mentions adds no coverage, differs between recordings of the same spec, and is the first thing to break on replay — so the next recording quietly drops it and the test gets weaker without anyone deciding that.
-
-- **An \`expected\` that labels its parts is recorded down to the \`must:\` lines.** A \`when present:\` line names something the product does not produce on every run, so **nothing that fails on its absence may be recorded for it** — no assert, and no \`wait --text\` either: a recorded wait throws on the next run that legitimately lacks it, which is the same failure an assert would have caused. Look at it with \`snapshot\` or \`get count\` if you want to see it, and record nothing. When the step needs to wait for something asynchronous to arrive, anchor that wait on a \`must:\` signal — waiting on the optional one makes the whole step hinge on it. Every line of a labelled \`expected\` carries a label; text with no labels at all is all \`must:\`.
-
-- **\`url_contains\` is opt-in, not a habit.** The same rule, in the form that gets broken most. Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
-- **When you do assert a URL, the substring may come from ONE place only:** a \`\${VAR}\` URL that *this step's own instruction* opened, written as that \`\${VAR}\` followed by the literal tail after it. If the step opens \`\${APP_URL}/todos\`, assert \`\${APP_URL}/todos\` (or the tail \`/todos\`); the recorder resolves \`\${APP_URL}\` per environment. Never assert on a URL you merely *observed* — login redirects, identity-provider pages, and OAuth callbacks all live on a **different, environment-named origin** than the app, so any substring of them (host, origin, OR path) names the environment.
-- **A leading slash does NOT make a substring safe.** \`/auth-staging\`, \`/env-qa\`, \`/tenant-acme\` look like paths but are environment labels — the first segment of an identity-provider or tenant URL, not an application route. If a substring contains an environment name, a stage token (\`dev\`, \`stg\`, \`prod\`), a tenant/org name, or any fragment of a hostname, it is forbidden even with a leading slash. The only safe path substrings are stable *application* routes off the app's own origin (\`/dashboard\`, \`/todos/new\`), taken from a \`\${VAR}\` you opened — not from a redirect you watched.
-
-**Every assert type has a marker command.** There is no text form: a printed
-\`AB_ACTION|assert|...\` line performs nothing, so nothing proves it, and it is
-reported rather than recorded.
-
-| assertType | The command that records it | Use when |
-|------------|------------------------------|----------|
-| \`text_visible\` | \`CCQA_ASSERT=1 ... wait --text "<text>"\` | stable text appears on the page |
-| \`element_visible\` | \`CCQA_ASSERT=element_visible ... get count "<selector>"\` | element is present |
-| \`element_not_visible\` | \`CCQA_ASSERT=element_not_visible ... get count "<selector>"\` | element is gone — and text absence too, as \`text=<text>\` |
-| \`url_contains\` | \`CCQA_ASSERT=url_contains:<substring> ... get url\` | the URL contains a pattern |
-| \`element_enabled\` / \`element_disabled\` | \`CCQA_ASSERT=<marker> ... is enabled "<selector>"\` | a control is usable, or is not |
-| \`element_checked\` / \`element_unchecked\` | \`CCQA_ASSERT=<marker> ... is checked "<selector>"\` | a checkbox is ticked, or is not |
-
-**Stability rules — CRITICAL. NEVER assert on values that change run-to-run:**
-
-- Timestamps, session IDs, exact numeric counts that vary between runs.
-- **Absolute dates / clock times**: \`12:34:56\`, \`2026-05-20\`, \`2026年5月20日\`, \`5月20日\`. These are scrubbed by post-trace literal-scrub anyway — avoid them at the source.
-- **Relative-time labels** — true only in the moment of the trace, stale by replay:
-  - English: \`just now\`, \`5 minutes ago\`, \`2 hours ago\`, \`yesterday\`, \`last week\`.
-  - Japanese: \`たった今\`, \`3分前\`, \`1時間前\`, \`昨日\`.
-- Dynamic counts like "42 results" → assert on the stable suffix ("results") only.
-- **PREFER**: status text, button labels, URL patterns, element enabled/disabled state.
-
-**No tautological state asserts — CRITICAL for \`element_enabled\` / \`element_disabled\`:**
-
-The selector must identify *which* element by something **other than the state you are asserting**. Selecting the element *by* its state and then asserting that state is a tautology that always passes and verifies nothing.
-
-- ✗ \`element_disabled | button[disabled] |\` — picks an already-disabled button, then "confirms" it is disabled. Passes even if the button the spec cares about is missing or enabled.
-- ✗ \`element_enabled | button:enabled |\`, \`[aria-disabled='true']\`, \`input:disabled\` — same trap.
-- ✓ Name the element by a stable, state-independent selector and assert the state on it: e.g. the "Submit" button is \`find role button --name "Submit"\`; to assert it is disabled, give \`element_disabled\` a selector that targets *that* button (a stable \`id\` / \`data-testid\` / unique class), **not** \`[disabled]\`.
-- If you cannot target the specific element without a state pseudo-class/attribute, **do not emit the enabled/disabled assert** — assert a user-visible consequence instead (e.g. the action it gates does not happen, a "you don't have permission" message is shown), or rely on \`text_visible\` for the label plus \`text_not_visible\` for what an enabled control would have produced.
-
-**Page-context and selector rules:**
-
-- After a navigation, take a **fresh snapshot** before emitting any assertion. Don't assert on text from the previous page.
-- Assertion selectors follow the same Selector Rules as actions — never invent aria-label values; use the exact strings from the current snapshot.
-- When unsure, prefer \`text_visible\` — a \`CCQA_ASSERT=1\` marked \`wait --text\` verifies and records it in one command.
-
-**MUST-VERIFY rule — STRICT (applies to every assert except \`url_contains\`):**
-
-The \`snapshot\` output is the **accessibility tree**, but \`agent-browser\` queries the **real DOM**. They don't always agree. Two known traps:
-
-1. *Selector trap*: a snapshot row like \`textbox "Email address"\` may be reachable via \`[placeholder='...']\` but **not** via \`[aria-label='...']\` if no aria-label attribute is actually set (the browser inferred the label from \`<label for=>\` / placeholder).
-2. *Text trap*: a snapshot row like \`link "Dashboard"\` may come from \`<a><img alt="Dashboard"></a>\` — the visible "text" is an \`alt\` attribute, not a text node. \`text_visible\` (which scans visible text nodes) will NOT find it.
-3. *Input-value trap*: after you \`fill\` an \`<input>\` / \`<textarea>\` / \`[contenteditable]\`, the text you typed lives in the element's **value**, not as a visible text node. **Do NOT assert the typed value with \`text_visible\`** — it will never match. The spec's "the field reflects X" expectation is implicitly confirmed when the form submits successfully and the value shows up on the *result* page (a list row, a detail page). Assert there, not on the input itself.
-
-**Verify the assertion form actually resolves on the live page.** The
-verification and the recorded assertion are the same marked command:
-
-\`\`\`bash
-# text_visible
-CCQA_STEP=<step-id> CCQA_ASSERT=1 agent-browser --session SESSION wait --text "<text>" --timeout 3000
-# element_visible — >=1 printed means present
-CCQA_STEP=<step-id> CCQA_ASSERT=element_visible agent-browser --session SESSION get count "<selector>"
-# element_not_visible — 0 printed means absent (works for text too: "text=<text>")
-CCQA_STEP=<step-id> CCQA_ASSERT=element_not_visible agent-browser --session SESSION get count "<selector>"
-# element state — \`is\` prints true/false and exits 0 either way; read it
-CCQA_STEP=<step-id> CCQA_ASSERT=element_disabled agent-browser --session SESSION is enabled "<selector>"
-CCQA_STEP=<step-id> CCQA_ASSERT=element_checked agent-browser --session SESSION is checked "<selector>"
-\`\`\`
-
-When *no* form verifies — e.g. \`[aria-label='X']\`, \`[placeholder='X']\`, and \`text=X\` all timed out, or the visible text turned out to be an \`alt\` — **drop the assertion entirely**. Fewer real assertions beat invented ones that fail at replay. \`url_contains\` is exempt (it checks the URL string, not the DOM).
-
-## Status Protocol
-
-Emit exactly one status line per step (outside any code block):
-
-\`\`\`
-STEP_START|<step-id>|<short description>
-STEP_DONE|<step-id>|<what was verified>
-ASSERTION_FAILED|<step-id>|<category: app-bug|env-issue|auth-blocked|missing-test-data|selector-drift|agent-misread>: <reason>
-STEP_SKIPPED|<step-id>|<reason>
-RUN_COMPLETED|passed|<summary>
-RUN_COMPLETED|failed|<summary>
-\`\`\`
-
-**\`RUN_COMPLETED\` is what ends the run.** A session that stops without it is
-recorded as FAILED, however many steps went well: nothing else can tell a
-finished route from one you abandoned halfway.
-
-${callerGuidance}## Start
-
-Begin by clearing cookies, then proceed straight to the first step's instruction.
-
-\`\`\`bash
-agent-browser --session ${sessionName} cookies clear
-\`\`\`
-
-(The cookies-clear preamble belongs to no step, so it is the one command
-without a \`CCQA_STEP\` prefix.)
-
-Emit:
-\`\`\`
-AB_ACTION|cookies_clear
-\`\`\`
-
-Then emit \`STEP_START|${firstStepId}|...\` and execute the first step, prefixing
-every one of its agent-browser commands with \`CCQA_STEP=${firstStepId}\`. The first
-step is responsible for opening the initial URL.
-`;
+function roleOfAccessibleName(snapshot, name) {
+	const roles = /* @__PURE__ */ new Set();
+	for (const line of snapshot.split("\n")) {
+		const m = /([A-Za-z]+)\s+"([^"]*)"/.exec(line);
+		if (m && m[2] === name) roles.add(m[1]);
+	}
+	return roles.size === 1 ? [...roles][0] : null;
+}
+//#endregion
+//#region src/runtime/replay-validate.ts
+function isProbe(x) {
+	return x !== null && !Array.isArray(x);
+}
+function runProbe(probe, sessionName) {
+	return probe.kind === "state" ? runStateCheck(probe, sessionName) : runPollCheck(probe, sessionName);
+}
+function runStateCheck(check, sessionName) {
+	let answer = "";
+	const rounds = attemptsFor(ASSERT_TIMEOUT_MS, SELECTOR_POLL_INTERVAL_MS) + 1;
+	for (let round = 0; round < rounds; round++) {
+		const r = spawnAB([
+			"--session",
+			sessionName,
+			"is",
+			check.state,
+			check.selector
+		]);
+		answer = r.status === 0 ? r.stdout.trim() : "";
+		if (answer === String(check.expected)) return {
+			ok: true,
+			reason: ""
+		};
+		if (round + 1 < rounds) sleepSync(SELECTOR_POLL_INTERVAL_MS);
+	}
+	return answer === "true" || answer === "false" ? {
+		ok: false,
+		reason: `expected ${check.state}=${check.expected}, page says ${answer}`
+	} : {
+		ok: false,
+		reason: `is ${check.state} answered ${answer || "nothing"}`
+	};
+}
+const SELECTOR_POLL_INTERVAL_MS = 500;
+/** Poll `get count <selector>` until it matches (>=1) or the timeout elapses. */
+function runPollCheck(check, sessionName) {
+	const present = (selector) => {
+		const r = spawnAB([
+			"--session",
+			sessionName,
+			"get",
+			"count",
+			selector
+		]);
+		return r.status === 0 ? Number.parseInt(r.stdout.trim(), 10) : NaN;
+	};
+	const deadline = Date.now() + check.timeoutMs;
+	const rounds = attemptsFor(check.timeoutMs, SELECTOR_POLL_INTERVAL_MS) + 1;
+	let count = NaN;
+	for (let round = 0;; round++) {
+		count = present(check.selector);
+		if (!Number.isNaN(count) && count > 0) return {
+			ok: true,
+			reason: ""
+		};
+		if (round + 1 >= rounds || Date.now() >= deadline) break;
+		sleepSync(SELECTOR_POLL_INTERVAL_MS);
+	}
+	return {
+		ok: false,
+		reason: `selector not present within ${check.timeoutMs}ms (get count returned ${Number.isNaN(count) ? "error" : count})`
+	};
+}
+/** What the validator records against an action it never replayed. */
+const CASCADE_REASON = "skipped after a preceding action failed";
+/** Whether a drop reason means "not replayed", rather than "replayed and failed". */
+function isCascadeReason(reason) {
+	return reason === CASCADE_REASON;
+}
+const SHORT_TIMEOUT_MS = 5e3;
+const ASSERT_TIMEOUT_MS = 1e4;
+const INTERACTION_POLL_INTERVAL_MS = 250;
+const INTERACTION_ATTEMPTS = attemptsFor(ASSERT_TIMEOUT_MS, INTERACTION_POLL_INTERVAL_MS);
+/** Bounds a poll when `sleepSync` is stubbed and the clock never moves. */
+function attemptsFor(timeoutMs, intervalMs) {
+	return Math.max(1, Math.ceil(timeoutMs / intervalMs));
+}
+/**
+* Convert one recorded action into the `agent-browser` arg list that would
+* exercise it. Interaction commands come from the shared
+* `ir/to-agent-browser.ts` mapping with env refs resolved; `wait` / `assert`
+* get validation-specific handling (poll checks, timeouts, unverifiable
+* skips). Returns `null` for actions that should not be validated (snapshot
+* has no side effect; assert types whose codegen forms aren't directly
+* verifiable here fall through to the caller's `unverifiable` fallback).
+*/
+function actionToAbArgs(action, sessionName, envOverrides = {}) {
+	const base = ["--session", sessionName];
+	const sub = (s) => s === void 0 ? "" : resolveEnvRefs(s, envOverrides);
+	switch (action.action) {
+		case "snapshot": return null;
+		case "assert": return assertToAbArgs(action, sub, sessionName);
+		case "wait": {
+			const loc = action.locator;
+			if (!loc) return null;
+			if (loc.by === "text") return [
+				...base,
+				"wait",
+				"--text",
+				sub(loc.value),
+				"--timeout",
+				String(SHORT_TIMEOUT_MS)
+			];
+			const raw = sub(locatorToSelector(loc));
+			if (!raw) return null;
+			if (/^\d+$/.test(raw)) return null;
+			if (raw.startsWith("--")) return null;
+			if (raw.startsWith("text=")) return [
+				...base,
+				"wait",
+				"--text",
+				raw.slice(5),
+				"--timeout",
+				String(SHORT_TIMEOUT_MS)
+			];
+			return {
+				kind: "poll-present",
+				selector: raw,
+				timeoutMs: SHORT_TIMEOUT_MS
+			};
+		}
+		default: {
+			const tokens = toAgentBrowserArgs(action);
+			if (tokens === null) return null;
+			const resolve = action.action === "navigate" ? (text) => collapseUrlPath(sub(text)) : sub;
+			return [...base, ...tokens.map((t) => resolve(t.text))];
+		}
+	}
+}
+function roleProbe(base, role, name) {
+	return [...base, ...roleProbeTokens(role, name).map((t) => t.text)];
+}
+/**
+* Presence asked the way the locator addresses the element. `null` is
+* unverifiable rather than absent: a count from a selector the engine never
+* parsed is not evidence.
+*/
+function presenceCheck(locator, selector, sub, base) {
+	if (locator?.by === "text") return [
+		...base,
+		"wait",
+		"--text",
+		sub(locator.value),
+		"--timeout",
+		String(ASSERT_TIMEOUT_MS)
+	];
+	if (locator?.by === "role" && locator.name) return roleProbe(base, sub(locator.value), sub(locator.name));
+	if (locator !== void 0 && locator.by !== "css") return null;
+	const named = parseNotation(selector);
+	if (named === "opaque") return null;
+	if (named !== null && named.by === "role" && named.name) return roleProbe(base, sub(named.value), sub(named.name));
+	if (named !== null) return null;
+	return {
+		kind: "poll-present",
+		selector,
+		timeoutMs: ASSERT_TIMEOUT_MS
+	};
+}
+function assertToAbArgs(action, sub, sessionName) {
+	const base = ["--session", sessionName];
+	const val = sub(action.value ?? action.observation);
+	const sel = sub(action.locator ? locatorToSelector(action.locator) : action.observation);
+	switch (action.assert) {
+		case "text_visible":
+			if (!val) return null;
+			return [
+				...base,
+				"wait",
+				"--text",
+				val,
+				"--timeout",
+				String(ASSERT_TIMEOUT_MS)
+			];
+		case "text_not_visible": return null;
+		case "element_visible": return sel ? presenceCheck(action.locator, sel, sub, base) : null;
+		case "element_not_visible": return null;
+		case "url_contains": return null;
+		case "element_enabled":
+		case "element_disabled":
+		case "element_checked":
+		case "element_unchecked":
+			if (!sel || action.locator?.by !== "css") return null;
+			if (parseNotation(sel) !== null || nameFromAttributeSelector(sel) !== null) return null;
+			return {
+				kind: "state",
+				state: action.assert === "element_checked" || action.assert === "element_unchecked" ? "checked" : "enabled",
+				selector: sel,
+				expected: action.assert === "element_enabled" || action.assert === "element_checked"
+			};
+		default: return null;
+	}
 }
-function buildTracePrompt(title) {
-	return `Execute the test for "${title}". Each step's instruction includes the URL or selector context it needs.`;
+const NO_STEP_ID = "__no_step__";
+/**
+* The role a labelled element has when addressing it by label finds nothing.
+*
+* `getByLabel` needs a real association — a `<label for>`, a wrapping label,
+* an `aria-labelledby`. A form that has none still shows the same string as
+* the field's accessible name, which is what the recorder read off the
+* snapshot, so the label it recorded matches nothing while the same text as a
+* role's name matches exactly. Only the actions whose element has one
+* unambiguous role are listed: a labelled `click` may be a button, a link or
+* a checkbox, and guessing there would replace a locator that failed with one
+* that finds the wrong element.
+*/
+const LABEL_FALLBACK_ROLE = {
+	fill: "textbox",
+	type: "textbox",
+	check: "checkbox",
+	uncheck: "checkbox"
+};
+/** Whether agent-browser's failure was "no element", the one the fallback answers. */
+function notFound(result) {
+	return /not\s+found|no\s+element|no\s+such\s+element|none\s+match\s+name/i.test(`${result.stderr} ${result.stdout}`);
+}
+/** Whether this argv navigates — the only action safe to repeat wholesale. */
+function isOpen(argv) {
+	return argv[2] === "open";
+}
+/** A navigation another navigation took away, rather than one that failed. */
+function superseded(result) {
+	return /ERR_ABORTED|navigation (?:was )?(?:interrupted|superseded|cancell?ed)/i.test(`${result.stderr} ${result.stdout}`);
+}
+/** The one line both callers log when the fallback rewrote a locator. */
+function formatPromotion(promotion) {
+	return `locator rewritten to the form that replays: ${promotion}`;
+}
+/** The same action addressed by role + accessible name, or null when there is no such form. */
+function labelFallback(action) {
+	const loc = action.locator;
+	if (!loc || loc.by !== "label") return null;
+	const role = LABEL_FALLBACK_ROLE[action.action];
+	if (role === void 0) return null;
+	return {
+		...action,
+		locator: {
+			by: "role",
+			value: role,
+			name: loc.value,
+			exact: true
+		}
+	};
 }
 /**
-* The case's expectations, plus the one rule that decides where each is
-* recorded. Without the rule a recorder either asserts everything at the end —
-* on a page the flow has already left — or asserts each item at every step it
-* might apply to, which is the over-assertion the selector rules exist to
-* prevent.
+* Spawn one interaction, waiting for its element the way an assertion waits
+* for its text: a recording pauses for a snapshot between opening a page and
+* typing into it, the replay does not, so the replay reaches a field sooner
+* than the recording ever did.
+*
+* Only a "no element" failure waits — anything else repeats identically. When
+* there is an `alternate` form it is tried on every attempt rather than after
+* the wait: a label the page never associates with its input will not start
+* matching, so waiting first spends the budget for nothing.
 */
-function renderExpectations(expectations) {
-	if (expectations.length === 0) return "";
-	return `
-## Expected results
-
-The case states these without saying which step delivers them:
-
-${expectations.map((text) => `- ${text}`).join("\n")}
-
-**Assign each to the step it first becomes true in, and assert it there and nowhere else.** Read the flow to decide: an expectation about what a form did belongs to the step that submitted it, not to a later step that happens to still show it. Assert each one exactly once — a repeat adds no coverage and breaks first. An expectation you cannot place is one you report in \`STEP_DONE\` text as unplaced; never invent a step for it, and never assert it "just in case".
-`;
+function runInteraction(argv, alternate, patience, sessionName) {
+	const started = Date.now();
+	const deadline = started + ASSERT_TIMEOUT_MS;
+	let settled = false;
+	for (let attempt = 0;; attempt++) {
+		let result = spawnAB(argv);
+		if (result.status !== 0 && result.wedged === true) result = spawnAB(argv);
+		const waitedMs = Date.now() - started;
+		if (result.status !== 0 && superseded(result) && !settled && isOpen(argv)) {
+			settled = true;
+			spawnAB([
+				"--session",
+				sessionName,
+				"wait",
+				"--load",
+				"networkidle"
+			]);
+			continue;
+		}
+		if (result.status === 0 || !notFound(result)) return {
+			result,
+			viaAlternate: false,
+			waitedMs
+		};
+		if (alternate !== null) {
+			const alt = spawnAB(alternate);
+			if (alt.status === 0) return {
+				result: alt,
+				viaAlternate: true,
+				waitedMs
+			};
+		}
+		if (patience.spent || attempt + 1 >= INTERACTION_ATTEMPTS || Date.now() >= deadline) {
+			patience.spent = true;
+			return {
+				result,
+				viaAlternate: false,
+				waitedMs: Date.now() - started
+			};
+		}
+		sleepSync(INTERACTION_POLL_INTERVAL_MS);
+	}
 }
 /**
-* What the cleanup must make true. Separate from the case's expectations
-* because its steps are: a deletion is confirmed by the thing being gone,
-* which is only true after the undo has run, and asserting it among the
-* case's own steps would check it while the thing still exists.
+* Say what a `by: "css"` locator that is not CSS actually addresses.
+*
+* `get count` answers 0 for Playwright's notation instead of failing, so a
+* route holding one reads as dead. Rewritten in place, and reported, so the
+* saved route carries the form that replays rather than the one that counts
+* nothing. Notation this cannot convert leaves the locator alone; the assert
+* path then treats it as unverifiable rather than absent.
 */
-function renderCleanupExpectations(expectations) {
-	if (expectations.length === 0) return "";
-	return `
-## Expected results of the cleanup
-
-The case states these about its cleanup steps:
-
-${expectations.map((text) => `- ${text}`).join("\n")}
-
-**Assert each in the cleanup step that makes it true, and nowhere else.** They describe the state after the undo, so a cleanup step is not done when the command returns — it is done when what the case says here holds. Record the check as an assertion the same way a step's own is recorded.
-`;
+function nameNotation(action) {
+	const loc = action.locator;
+	if (action.action !== "assert" || loc?.by !== "css") return null;
+	const named = parseNotation(loc.value);
+	if (named === null || named === "opaque" || named.by !== "text") return null;
+	action.locator = named;
+	return `${loc.value} is not a CSS selector — asked as ${describeLocator(named)}`;
 }
 /**
-* Sections of the case ccqa does not interpret — the precondition, notes the
-* author left. Passed through verbatim: they are written for whoever runs the
-* case, and the recorder is now that reader.
+* An attribute selector that counted nothing, asked of the accessibility tree
+* the name was read from. See docs/targets.md for why the two disagree.
+*
+* The snapshot is read for the role, then `find role` is asked as well: the
+* tree says the name exists somewhere, the probe says the replay can reach it,
+* and only the second is what the route will depend on.
 */
-function renderContext(context) {
-	if (context.length === 0) return "";
-	return `
-## About this case
-
-${context.map((s) => `### ${s.heading}\n\n${s.body}`).join("\n\n")}
-`;
+function askTheAccessibilityTree(action, sub, sessionName) {
+	if (action.action !== "assert" || action.locator?.by !== "css") return null;
+	const name = nameFromAttributeSelector(action.locator.value);
+	if (name === null) return null;
+	const snapshot = spawnAB([
+		"--session",
+		sessionName,
+		"snapshot"
+	]);
+	if (snapshot.status !== 0) return null;
+	const role = roleOfAccessibleName(snapshot.stdout, sub(name));
+	if (role === null) return null;
+	if (spawnAB(roleProbe(["--session", sessionName], role, sub(name))).status !== 0) return null;
+	const promoted = `${action.locator.value} names an element rather than an attribute — confirmed as role=${role}`;
+	action.locator = {
+		by: "role",
+		value: role,
+		name,
+		exact: true
+	};
+	return {
+		skipped: false,
+		ok: true,
+		reason: "",
+		promoted
+	};
+}
+/**
+* Replay one recorded action against the validation session. Element-presence
+* checks go through `runPollCheck` (which uses `get count`, never the blocking
+* `wait <selector>`); everything else spawns the agent-browser argv.
+*/
+function runValidationAction(action, sessionName, envOverrides = {}, patience) {
+	const named = nameNotation(action);
+	const withName = (outcome) => named === null || !outcome.ok ? outcome : {
+		...outcome,
+		promoted: outcome.promoted ?? named
+	};
+	const built = actionToAbArgs(action, sessionName, envOverrides);
+	if (built === null) return {
+		skipped: true,
+		ok: false,
+		reason: ""
+	};
+	if (isProbe(built)) {
+		const { ok, reason } = runProbe(built, sessionName);
+		if (ok) return withName({
+			skipped: false,
+			ok,
+			reason
+		});
+		const resolve = (v) => v === void 0 ? "" : resolveEnvRefs(v, envOverrides);
+		return askTheAccessibilityTree(action, resolve, sessionName) ?? {
+			skipped: false,
+			ok,
+			reason
+		};
+	}
+	const fallback = labelFallback(action);
+	const alternate = fallback === null ? null : actionToAbArgs(fallback, sessionName, envOverrides);
+	const { result, viaAlternate, waitedMs } = runInteraction(built, alternate !== null && !isProbe(alternate) ? alternate : null, patience, sessionName);
+	if (viaAlternate) {
+		const promoted = `${action.locator.by}=${action.locator.value} → role=${fallback.locator.value} name="${action.locator.value}"`;
+		action.locator = fallback.locator;
+		return {
+			skipped: false,
+			ok: true,
+			reason: "",
+			promoted
+		};
+	}
+	if (result.status === 0) return withName({
+		skipped: false,
+		ok: true,
+		reason: ""
+	});
+	return {
+		skipped: false,
+		ok: false,
+		reason: `${(result.stderr.trim() || result.stdout.trim() || `agent-browser exit ${result.status ?? "?"}`).slice(0, 200)}${notFound(result) ? ` (waited ${waitedMs}ms)` : ""}`
+	};
 }
 /**
-* The project's own recording guidance. Where the case says what to do, this
-* says how this project is driven — which account signs in, what has to be
-* true before the first step. Prose, verbatim: it is written for whoever runs
-* the case, and this is now that reader.
+* Replay actions in order against a live session and stop at the first that
+* fails. Unlike `validateActions` there is no cascade or rescue: the caller
+* hands what is left to someone who can look at the page. A wait this cannot
+* reproduce still settles the page, since the next action may depend on it;
+* a check it cannot run is returned as `unchecked`, never as passed.
 */
-function renderConventions(conventions) {
-	if (conventions.length === 0) return "";
-	return `
-## How this project is driven
-
-${conventions.map((c) => `### ${c.heading}\n\n${c.body}`).join("\n\n")}
-`;
+function replayUntilFailure(actions, opts) {
+	const patience = { spent: false };
+	const passed = [];
+	const unchecked = [];
+	for (const action of actions) {
+		const outcome = runValidationAction(action, opts.sessionName, opts.envOverrides, patience);
+		if (outcome.skipped && action.action === "wait") spawnAB([
+			"--session",
+			opts.sessionName,
+			"wait",
+			"--load",
+			"networkidle"
+		]);
+		else if (outcome.skipped && action.action === "assert") {
+			unchecked.push(action);
+			continue;
+		} else if (outcome.skipped) return {
+			passed,
+			unchecked,
+			failed: {
+				action,
+				reason: "the recording does not say how to replay it"
+			}
+		};
+		else if (!outcome.ok) return {
+			passed,
+			unchecked,
+			failed: {
+				action,
+				reason: outcome.reason
+			}
+		};
+		passed.push(action);
+	}
+	return {
+		passed,
+		unchecked
+	};
 }
-//#endregion
-//#region src/ir/accessible-name.ts
-/**
-* A recorder reads an accessible name off a snapshot and writes it as the
-* attribute it guessed the name came from. The name can come from a `<label>`
-* or `aria-labelledby` instead, and the attribute's absence is not evidence
-* about the element. See docs/targets.md for the measurement.
-*/
-const NAMING_ATTR = /^\[\s*aria-label\s*=\s*(?:"([^"]*)"|'([^']*)')\s*\]$/;
-/**
-* The name this selector may be after, or null.
-*
-* `aria-label` only. `[name='email']` and `[title='Close']` are attributes that
-* mean what they say, and a zero from one of those is evidence.
-*/
-function nameFromAttributeSelector(selector) {
-	const m = NAMING_ATTR.exec(selector.trim());
-	const name = m?.[1] ?? m?.[2];
-	return name === void 0 || name === "" ? null : name;
+function validateActions(actions, opts) {
+	const kept = [];
+	const dropped = [];
+	const promoted = [];
+	const patience = { spent: false };
+	let skipFromStepId = null;
+	for (let i = 0; i < actions.length; i++) {
+		const action = actions[i];
+		opts.onProgress?.(i, actions.length, action);
+		const stepId = action.stepId ?? NO_STEP_ID;
+		if (skipFromStepId !== null && skipFromStepId !== stepId) skipFromStepId = null;
+		if (skipFromStepId !== null && isPassiveAction(action.action)) {
+			dropped.push({
+				index: i,
+				action,
+				reason: CASCADE_REASON
+			});
+			continue;
+		}
+		const outcome = runValidationAction(action, opts.sessionName, opts.envOverrides, patience);
+		if (outcome.promoted) promoted.push(outcome.promoted);
+		if (outcome.skipped) {
+			kept.push(action);
+			continue;
+		}
+		if (outcome.ok) {
+			kept.push(action);
+			if (skipFromStepId !== null && !isPassiveAction(action.action)) skipFromStepId = null;
+			continue;
+		}
+		dropped.push({
+			index: i,
+			action,
+			reason: outcome.reason
+		});
+		if (!isPassiveAction(action.action)) skipFromStepId = stepId;
+	}
+	const afterRescue = rescueLostSteps(actions, kept, dropped, opts, patience);
+	promoted.push(...afterRescue.promoted ?? []);
+	return {
+		...splitByMode(actions, afterRescue, opts.mode ?? "lenient"),
+		promoted
+	};
 }
 /**
-* The role of the first node in an accessibility snapshot whose name is
-* exactly `name`, or null.
-*
-* agent-browser prints one node per line as `<role> "<name>"`. Matched on the
-* whole name, so a tree holding both "Priority" and "Priority *" answers for
-* the one that was asked, and refused when two roles carry it.
+* Translate the internal `{ kept, dropped }` result of the rescue pass
+* into the public-facing shape. In strict mode the caller sees the same
+* shape as before (kept/dropped); in lenient mode the still-failed
+* actions move to `unstable` with `replayUnstable: true` tagged on, so
+* codegen can warn about them while still emitting the line.
 */
-function roleOfAccessibleName(snapshot, name) {
-	const roles = /* @__PURE__ */ new Set();
-	for (const line of snapshot.split("\n")) {
-		const m = /([A-Za-z]+)\s+"([^"]*)"/.exec(line);
-		if (m && m[2] === name) roles.add(m[1]);
+function splitByMode(originalActions, result, mode) {
+	if (mode === "strict") return {
+		kept: result.kept,
+		unstable: [],
+		dropped: result.dropped,
+		rescuedSteps: result.rescuedSteps
+	};
+	const droppedByIndex = new Map(result.dropped.map((d) => [d.index, d]));
+	const keptSet = new Set(result.kept);
+	const finalKept = [];
+	const unstable = [];
+	for (let i = 0; i < originalActions.length; i++) {
+		const action = originalActions[i];
+		if (keptSet.has(action)) {
+			finalKept.push(action);
+			continue;
+		}
+		const drop = droppedByIndex.get(i);
+		if (drop) {
+			action.replayUnstable = true;
+			action.replayReason = drop.reason;
+			unstable.push(action);
+		}
 	}
-	return roles.size === 1 ? [...roles][0] : null;
-}
-//#endregion
-//#region src/runtime/replay-validate.ts
-function isProbe(x) {
-	return x !== null && !Array.isArray(x);
-}
-function runProbe(probe, sessionName) {
-	return probe.kind === "state" ? runStateCheck(probe, sessionName) : runPollCheck(probe, sessionName);
+	return {
+		kept: finalKept,
+		unstable,
+		dropped: [],
+		rescuedSteps: result.rescuedSteps
+	};
 }
-function runStateCheck(check, sessionName) {
-	let answer = "";
-	const rounds = attemptsFor(ASSERT_TIMEOUT_MS, SELECTOR_POLL_INTERVAL_MS) + 1;
-	for (let round = 0; round < rounds; round++) {
-		const r = spawnAB([
-			"--session",
-			sessionName,
-			"is",
-			check.state,
-			check.selector
-		]);
-		answer = r.status === 0 ? r.stdout.trim() : "";
-		if (answer === String(check.expected)) return {
-			ok: true,
-			reason: ""
-		};
-		if (round + 1 < rounds) sleepSync(SELECTOR_POLL_INTERVAL_MS);
+function rescueLostSteps(actions, kept, dropped, opts, patience) {
+	const stepsWithSurvivors = /* @__PURE__ */ new Set();
+	for (const a of kept) if (a.stepId) stepsWithSurvivors.add(a.stepId);
+	const lostStepDrops = /* @__PURE__ */ new Map();
+	for (const d of dropped) {
+		const id = d.action.stepId;
+		if (!id || stepsWithSurvivors.has(id)) continue;
+		const list = lostStepDrops.get(id) ?? [];
+		list.push(d);
+		lostStepDrops.set(id, list);
 	}
-	return answer === "true" || answer === "false" ? {
-		ok: false,
-		reason: `expected ${check.state}=${check.expected}, page says ${answer}`
-	} : {
-		ok: false,
-		reason: `is ${check.state} answered ${answer || "nothing"}`
+	if (lostStepDrops.size === 0) return {
+		kept,
+		dropped
 	};
-}
-const SELECTOR_POLL_INTERVAL_MS = 500;
-/** Poll `get count <selector>` until it matches (>=1) or the timeout elapses. */
-function runPollCheck(check, sessionName) {
-	const present = (selector) => {
-		const r = spawnAB([
-			"--session",
-			sessionName,
-			"get",
-			"count",
-			selector
-		]);
-		return r.status === 0 ? Number.parseInt(r.stdout.trim(), 10) : NaN;
+	const promoted = [];
+	const rescuedIndices = /* @__PURE__ */ new Set();
+	const rescuedSteps = [];
+	const strict = (opts.mode ?? "lenient") === "strict";
+	for (const [stepId, drops] of lostStepDrops.entries()) {
+		const replayed = [];
+		const unverifiable = [];
+		let stillFailing = false;
+		for (const d of drops) {
+			const outcome = runValidationAction(d.action, opts.sessionName, opts.envOverrides, patience);
+			if (outcome.promoted) promoted.push(outcome.promoted);
+			if (outcome.skipped) {
+				unverifiable.push(d.index);
+				continue;
+			}
+			if (outcome.ok) {
+				replayed.push(d.index);
+				continue;
+			}
+			stillFailing = true;
+			if (strict && isCascadeReason(d.reason)) d.reason = outcome.reason;
+		}
+		if (replayed.length === 0) continue;
+		for (const i of replayed) rescuedIndices.add(i);
+		if (!stillFailing) for (const i of unverifiable) rescuedIndices.add(i);
+		rescuedSteps.push(stepId);
+	}
+	if (rescuedIndices.size === 0) return {
+		kept,
+		dropped,
+		promoted
 	};
-	const deadline = Date.now() + check.timeoutMs;
-	const rounds = attemptsFor(check.timeoutMs, SELECTOR_POLL_INTERVAL_MS) + 1;
-	let count = NaN;
-	for (let round = 0;; round++) {
-		count = present(check.selector);
-		if (!Number.isNaN(count) && count > 0) return {
-			ok: true,
-			reason: ""
-		};
-		if (round + 1 >= rounds || Date.now() >= deadline) break;
-		sleepSync(SELECTOR_POLL_INTERVAL_MS);
+	const keptSet = new Set(kept);
+	const newKept = [];
+	for (let i = 0; i < actions.length; i++) {
+		const action = actions[i];
+		if (rescuedIndices.has(i) || keptSet.has(action)) newKept.push(action);
 	}
 	return {
-		ok: false,
-		reason: `selector not present within ${check.timeoutMs}ms (get count returned ${Number.isNaN(count) ? "error" : count})`
+		kept: newKept,
+		dropped: dropped.filter((d) => !rescuedIndices.has(d.index)),
+		rescuedSteps,
+		promoted
 	};
 }
-/** What the validator records against an action it never replayed. */
-const CASCADE_REASON = "skipped after a preceding action failed";
-/** Whether a drop reason means "not replayed", rather than "replayed and failed". */
-function isCascadeReason(reason) {
-	return reason === CASCADE_REASON;
-}
-const SHORT_TIMEOUT_MS = 5e3;
-const ASSERT_TIMEOUT_MS = 1e4;
-const INTERACTION_POLL_INTERVAL_MS = 250;
-const INTERACTION_ATTEMPTS = attemptsFor(ASSERT_TIMEOUT_MS, INTERACTION_POLL_INTERVAL_MS);
-/** Bounds a poll when `sleepSync` is stubbed and the clock never moves. */
-function attemptsFor(timeoutMs, intervalMs) {
-	return Math.max(1, Math.ceil(timeoutMs / intervalMs));
-}
 /**
-* Convert one recorded action into the `agent-browser` arg list that would
-* exercise it. Interaction commands come from the shared
-* `ir/to-agent-browser.ts` mapping with env refs resolved; `wait` / `assert`
-* get validation-specific handling (poll checks, timeouts, unverifiable
-* skips). Returns `null` for actions that should not be validated (snapshot
-* has no side effect; assert types whose codegen forms aren't directly
-* verifiable here fall through to the caller's `unverifiable` fallback).
+* Passive (read-only) actions whose only effect is observation. When a
+* preceding action fails, dropping these too is the right move because
+* they were trying to observe state the failed action would have set up.
 */
-function actionToAbArgs(action, sessionName, envOverrides = {}) {
-	const base = ["--session", sessionName];
-	const sub = (s) => s === void 0 ? "" : resolveEnvRefs(s, envOverrides);
-	switch (action.action) {
-		case "snapshot": return null;
-		case "assert": return assertToAbArgs(action, sub, sessionName);
-		case "wait": {
-			const loc = action.locator;
-			if (!loc) return null;
-			if (loc.by === "text") return [
-				...base,
-				"wait",
-				"--text",
-				sub(loc.value),
-				"--timeout",
-				String(SHORT_TIMEOUT_MS)
-			];
-			const raw = sub(locatorToSelector(loc));
-			if (!raw) return null;
-			if (/^\d+$/.test(raw)) return null;
-			if (raw.startsWith("--")) return null;
-			if (raw.startsWith("text=")) return [
-				...base,
-				"wait",
-				"--text",
-				raw.slice(5),
-				"--timeout",
-				String(SHORT_TIMEOUT_MS)
-			];
-			return {
-				kind: "poll-present",
-				selector: raw,
-				timeoutMs: SHORT_TIMEOUT_MS
-			};
-		}
-		default: {
-			const tokens = toAgentBrowserArgs(action);
-			if (tokens === null) return null;
-			const resolve = action.action === "navigate" ? (text) => collapseUrlPath(sub(text)) : sub;
-			return [...base, ...tokens.map((t) => resolve(t.text))];
-		}
-	}
-}
-function roleProbe(base, role, name) {
-	return [...base, ...roleProbeTokens(role, name).map((t) => t.text)];
+function isPassiveAction(action) {
+	return action === "snapshot" || action === "wait" || action === "assert";
 }
+//#endregion
+//#region src/prompts/previous-recording.ts
 /**
-* Presence asked the way the locator addresses the element. `null` is
-* unverifiable rather than absent: a count from a selector the engine never
-* parsed is not evidence.
+* The previous recording as the commands that perform it, for the trace prompt:
+* a re-record is usually one moved screen in an otherwise intact route.
 */
-function presenceCheck(locator, selector, sub, base) {
-	if (locator?.by === "text") return [
-		...base,
-		"wait",
-		"--text",
-		sub(locator.value),
-		"--timeout",
-		String(ASSERT_TIMEOUT_MS)
-	];
-	if (locator?.by === "role" && locator.name) return roleProbe(base, sub(locator.value), sub(locator.name));
-	if (locator !== void 0 && locator.by !== "css") return null;
-	const named = parseNotation(selector);
-	if (named === "opaque") return null;
-	if (named !== null && named.by === "role" && named.name) return roleProbe(base, sub(named.value), sub(named.name));
-	if (named !== null) return null;
-	return {
-		kind: "poll-present",
-		selector,
-		timeoutMs: ASSERT_TIMEOUT_MS
-	};
+function renderPreviousRecording(actions, sessionName, currentStepIds) {
+	const current = new Set([SETUP_STEP_ID, ...currentStepIds]);
+	const brokenStep = actions.find(failedToReplay)?.stepId;
+	const byStep = /* @__PURE__ */ new Map();
+	for (const action of actions) {
+		if (action.stepId === void 0 || !current.has(action.stepId)) continue;
+		const command = previousCommand(action, sessionName, action.stepId === brokenStep);
+		if (command === null) continue;
+		const lines = byStep.get(action.stepId) ?? [];
+		lines.push(command);
+		byStep.set(action.stepId, lines);
+	}
+	if (byStep.size === 0) return "";
+	return `
+## Previous recording
+
+This case was recorded before. Below is what that recording did, step by step,
+as the commands that perform it. The application may have moved since, and the
+steps above may have been edited: **the steps above are the contract, this is a
+map.**
+
+For a step listed here, this replaces the snapshot-first routine of the
+Execution Workflow:
+
+1. While a step's previous commands still do what its instruction and
+   \`Expected\` say, call the \`replay_step\` tool with the step id instead of
+   running them yourself. It runs and records them in this session, checks
+   included, and stops at the first that fails. Do not snapshot first.
+2. When it reports they all ran, emit \`STEP_DONE\` and go to the next step
+   without a confirming snapshot.
+3. When it reports a failure, the commands before it are recorded and the
+   page is where they left it: finish that step with the Execution Workflow —
+   snapshot, find what works, record it — without re-running what was
+   recorded. A step whose instruction or \`Expected\` asks for something these
+   commands do not do skips \`replay_step\` and uses the Execution Workflow
+   from the start. The next step goes back to \`replay_step\`.
+4. A step you record yourself takes its assertions from its current
+   \`Expected\`: keep a previous check only while it verifies what
+   \`Expected\` says now. A step whose \`Expected\` has changed is one to
+   record yourself, since \`replay_step\` records the previous checks as
+   they are.
+5. A command marked \`# did not replay last time\` is where the previous
+   recording's own validation found the route broken: expect that step to
+   need the Execution Workflow, and do not keep a form that only half works.
+
+A step with no section here is recorded the usual way.
+
+${[...byStep].map(([stepId, lines]) => `### ${stepId}\n\n\`\`\`bash\n${lines.join("\n")}\n\`\`\``).join("\n\n")}
+`;
 }
-function assertToAbArgs(action, sub, sessionName) {
-	const base = ["--session", sessionName];
-	const val = sub(action.value ?? action.observation);
-	const sel = sub(action.locator ? locatorToSelector(action.locator) : action.observation);
-	switch (action.assert) {
-		case "text_visible":
-			if (!val) return null;
-			return [
-				...base,
-				"wait",
-				"--text",
-				val,
-				"--timeout",
-				String(ASSERT_TIMEOUT_MS)
-			];
-		case "text_not_visible": return null;
-		case "element_visible": return sel ? presenceCheck(action.locator, sel, sub, base) : null;
-		case "element_not_visible": return null;
-		case "url_contains": return null;
-		case "element_enabled":
-		case "element_disabled":
-		case "element_checked":
-		case "element_unchecked":
-			if (!sel || action.locator?.by !== "css") return null;
-			if (parseNotation(sel) !== null || nameFromAttributeSelector(sel) !== null) return null;
-			return {
-				kind: "state",
-				state: action.assert === "element_checked" || action.assert === "element_unchecked" ? "checked" : "enabled",
-				selector: sel,
-				expected: action.assert === "element_enabled" || action.assert === "element_checked"
-			};
-		default: return null;
-	}
+function previousCommand(action, sessionName, inBrokenStep) {
+	if (action.action === "wait" && action.locator?.by !== "text") return null;
+	const marked = action.action === "assert" ? markedAssertArgs(action) : null;
+	const tokens = marked?.tokens ?? (action.action === "assert" ? null : toAgentBrowserArgs(action));
+	if (tokens === null) return null;
+	const line = [
+		`CCQA_STEP=${action.stepId}`,
+		...marked ? [`CCQA_ASSERT=${shellWord(marked.marker)}`] : [],
+		...action.secret ? ["CCQA_SECRET=1"] : [],
+		"agent-browser",
+		"--session",
+		sessionName,
+		renderTokens(tokens)
+	].join(" ");
+	return inBrokenStep && failedToReplay(action) ? `${line}   # did not replay last time` : line;
 }
-const NO_STEP_ID = "__no_step__";
-/**
-* The role a labelled element has when addressing it by label finds nothing.
-*
-* `getByLabel` needs a real association — a `<label for>`, a wrapping label,
-* an `aria-labelledby`. A form that has none still shows the same string as
-* the field's accessible name, which is what the recorder read off the
-* snapshot, so the label it recorded matches nothing while the same text as a
-* role's name matches exactly. Only the actions whose element has one
-* unambiguous role are listed: a labelled `click` may be a button, a link or
-* a checkbox, and guessing there would replace a locator that failed with one
-* that finds the wrong element.
-*/
-const LABEL_FALLBACK_ROLE = {
-	fill: "textbox",
-	type: "textbox",
-	check: "checkbox",
-	uncheck: "checkbox"
-};
-/** Whether agent-browser's failure was "no element", the one the fallback answers. */
-function notFound(result) {
-	return /not\s+found|no\s+element|no\s+such\s+element/i.test(`${result.stderr} ${result.stdout}`);
+/** Failed on its own, rather than skipped behind an earlier failure. */
+function failedToReplay(action) {
+	return action.replayUnstable === true && !isCascadeReason(action.replayReason);
 }
-/** Whether this argv navigates — the only action safe to repeat wholesale. */
-function isOpen(argv) {
-	return argv[2] === "open";
+function renderTokens(tokens) {
+	return tokens.map((t) => t.expandsEnv ? quote(t.text) : t.text).join(" ");
 }
-/** A navigation another navigation took away, rather than one that failed. */
-function superseded(result) {
-	return /ERR_ABORTED|navigation (?:was )?(?:interrupted|superseded|cancell?ed)/i.test(`${result.stderr} ${result.stdout}`);
+/** Double-quoted with `${VAR}` refs left live, as the recording keeps them; any other `$` is literal text. */
+function quote(s) {
+	return `"${s.replace(/(["\\`])|\$(?!\{[A-Za-z_]\w*\})/g, (m, c) => `\\${c ?? m}`)}"`;
 }
-/** The one line both callers log when the fallback rewrote a locator. */
-function formatPromotion(promotion) {
-	return `locator rewritten to the form that replays: ${promotion}`;
+function shellWord(s) {
+	return /^[\w:/.,=-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+//#endregion
+//#region src/prompts/trace.ts
+function generateSessionName() {
+	return `ccqa-trace-${buildRunId()}`;
+}
+/**
+* Build the trace system prompt. `input.steps` is a flat list with includes
+* already expanded (each step carries id / source / instruction / expected).
+* The spec opens URLs via explicit step instructions (e.g.
+* `instruction: "${APP_URL}/articles を開く"`).
+*
+* In v0.4 every spec is traced from scratch — block contents are inlined
+* into the spec's own step list at expand time, so the prompt has no
+* special "this is a block" mode. The `source` tag on each step still
+* distinguishes spec-native steps from inlined block steps for the
+* `// step:` comments in the eventual codegen output.
+*/
+function buildTraceSystemPrompt(input) {
+	const sessionName = input.sessionName ?? generateSessionName();
+	const firstStepId = input.steps[0]?.id ?? "step-01";
+	const callerGuidance = input.instruction ? `## Caller Guidance
+
+The caller provided extra guidance for this recording — for example, a drift
+audit's finding about what a previous recording of this spec got wrong. Treat
+it as advice on what to avoid or verify while recording; the spec's steps
+above remain the contract for what to do.
+
+${input.instruction}
+
+` : "";
+	const stepsText = input.steps.map((step) => [
+		`### ${step.id} [${step.source}]`,
+		`- **Instruction**: ${step.instruction}`,
+		...step.expected ? [`- **Expected**: ${step.expected}`] : []
+	].join("\n")).join("\n\n");
+	const expectationsText = renderExpectations(input.expectations ?? []) + renderCleanupExpectations(input.cleanupExpectations ?? []);
+	const contextText = renderContext(input.context ?? []);
+	const conventionsText = renderConventions(input.conventions ?? []);
+	const previousText = renderPreviousRecording(input.previousRecording ?? [], sessionName, input.steps.map((s) => s.id));
+	return `You are an expert QA engineer executing a browser E2E test. Execute each step precisely and record every browser action as a structured log line.
+
+## Session
+
+SESSION NAME: \`${sessionName}\`
+
+Always pass \`--session ${sessionName}\` to every \`agent-browser\` command.
+
+**Always prefix every \`agent-browser\` command with a \`CCQA_STEP=<step-id>\`
+env assignment naming the spec step it executes**, e.g.
+
+\`\`\`bash
+CCQA_STEP=step-03 agent-browser --session ${sessionName} click "text=Submit"
+\`\`\`
+
+This prefix is what ties each recorded action to its step in the generated
+test — a command without it loses its step attribution.
+
+**Anything you do before the first step carries \`CCQA_STEP=${SETUP_STEP_ID}\`.** Signing
+in, opening the application, putting the account where the precondition says it
+starts — those are not step-01, and marking them as step-01 makes the first
+step of the case look like it does all of it. The next \`CCQA_STEP=\` names the
+first step the case actually lists.
+
+Other env assignments may precede it (\`FOO=x CCQA_STEP=step-02 agent-browser ...\`); agent-browser
+itself ignores the variable.
+
+Verification commands additionally carry a \`CCQA_ASSERT=<marker>\` env
+assignment (alongside \`CCQA_STEP\`) that records the check as a test
+assertion — see "Assertion Protocol".
+
+**A command that types into a password field carries \`CCQA_SECRET=1\`** as
+well, e.g.
+
+\`\`\`bash
+CCQA_STEP=step-01 CCQA_SECRET=1 agent-browser --session ${sessionName} find label "Password" fill "\${LOGIN_PASSWORD}"
+\`\`\`
+
+A password field is an \`<input type="password">\` — the snapshot shows its
+value as dots, and nothing else about the page is a password. The prefix is
+what stops the typed value from being written to the recording: a value that
+came from a \`\${VAR}\` is kept as that reference, and one typed literally is
+dropped along with its command.
+
+## Browser Commands
+
+\`\`\`
+CCQA_STEP=<step-id> agent-browser --session SESSION open <url>
+CCQA_STEP=<step-id> agent-browser --session SESSION snapshot -i -c          # interactive elements only — the default for finding controls
+CCQA_STEP=<step-id> agent-browser --session SESSION snapshot -c -s "<css>"  # the page's text, scoped to one region
+CCQA_STEP=<step-id> agent-browser --session SESSION click "<selector>"
+CCQA_STEP=<step-id> agent-browser --session SESSION fill "<selector>" "<value>"
+CCQA_STEP=<step-id> agent-browser --session SESSION check "<selector>"
+CCQA_STEP=<step-id> agent-browser --session SESSION uncheck "<selector>"
+CCQA_STEP=<step-id> agent-browser --session SESSION press <Key>
+CCQA_STEP=<step-id> agent-browser --session SESSION select "<selector>" "<value>"
+CCQA_STEP=<step-id> agent-browser --session SESSION hover "<selector>"
+CCQA_STEP=<step-id> agent-browser --session SESSION wait --text "<text>" [--timeout <ms>]
+CCQA_STEP=<step-id> agent-browser --session SESSION wait --load networkidle
+CCQA_STEP=<step-id> agent-browser --session SESSION get count "<selector>"   # element-existence check (returns a number, fast)
+agent-browser --session SESSION cookies clear                                # pre-step preamble — no CCQA_STEP prefix
+CCQA_STEP=<step-id> agent-browser --session SESSION find <locator> <value> <action> [<input>] [--name "<n>"] [--exact]
+CCQA_STEP=<step-id> agent-browser --session SESSION upload "<input[type=file] selector>" <file> [<file> ...]
+# See "Selector Rules" for the full \`find\` subset.
+# IMPORTANT: do NOT use \`wait "<css-selector>"\`. agent-browser ignores --timeout on a
+# CSS-selector wait and blocks for ~150s when the selector never matches, killing the run.
+# Wait for readiness with \`wait --text\`, \`wait --load networkidle\`, or just use \`find\`
+# (which waits internally). To check an element exists, use \`get count "<selector>"\`.
+\`\`\`
+
+## Selector Rules
+
+**ALLOWED selector formats — use ONE of these everywhere a selector appears (click, fill, wait, assert, ...):**
+
+| Format | Use when |
+|--------|----------|
+| \`[aria-label='label']\` | Element **has the \`aria-label\` attribute** — **FIRST CHOICE**. A name the snapshot shows is not proof of one: a name can come from a \`<label>\`, from the element's own text, or from \`aria-labelledby\`, and this selector then matches nothing. |
+| \`text=visible text\` | Unique visible text, no aria-label — for **actions**. Not for a \`get count\` probe: see step 3. |
+| \`[placeholder='text']\` | Input identified by placeholder |
+| \`[type='password']\` | Password inputs only |
+| \`a[href*='pattern']\` | Links where \`text=\` fails — use the URL pattern from the ARIA snapshot |
+| \`[data-testid='...']\`, \`[data-qa='...']\` | Specific attribute selectors when an aria-label is absent |
+
+**FORBIDDEN — these break recorded tests and are rejected by the hook layer:**
+
+- \`@ref\` / \`@e1\` / \`e14\` — reference IDs are session-specific and change every run.
+- **Bare tag selectors**: \`button\`, \`a\`, \`div\`, \`td\`, \`tr\`, \`main a\`, \`table tbody tr:nth-child(N)\`. These match every element of that tag and are non-deterministic on replay. **This includes the inner selector inside \`find first/last/nth\`** — see the \`find\` rules below.
+- \`[role='button']\` or \`[type='checkbox']\` alone — matches too many elements.
+- **Playwright-only pseudo-classes**: \`:has-text()\`, \`:text-is()\`, \`:text-matches()\`, \`:visible\`. agent-browser's CSS engine does not implement them. They do not error — \`get count\` answers \`0\` and \`find\` reports no element — so a test using one fails while looking like the page lost the element. Use \`text=...\` or plain CSS instead.
+- JavaScript execution (\`eval\`, \`js\`) — blocked by the hook layer.
+
+### \`find\` subset (fallback when no ALLOWED CSS uniquely targets the element)
+
+When repeated aria-labels / visible text make ALLOWED selectors ambiguous (e.g. a chat client where every message row has the same "1 reply" button), use one of these — they record as structured actions and replay deterministically:
+
+\`\`\`
+find role <role> <action> [--name "<n>"] [--exact]
+find text|label|placeholder|alt|title "<text>" <action> [--exact]
+find testid "<id>" <action>
+find first|last "<ALLOWED-css>" <action>
+find nth <index> "<ALLOWED-css>" <action>
+\`\`\`
+
+\`<action>\` is one of \`click | dblclick | fill | type | hover | focus | check | uncheck\`. For \`fill\`/\`type\`, the input value follows the action: \`find label "Email" fill "user@example.com"\`.
+
+**Rules for \`find\`:**
+
+1. Try ALLOWED selectors first. Only reach for \`find\` when they demonstrably cannot uniquely target the element.
+2. **The inner selector for \`first/last/nth\` MUST be one of the ALLOWED formats above.** Never pass a bare tag — "the last button" is meaningless on replay.
+3. \`find last\` is reliable only when the layout guarantees "the target is the bottom-most match" (e.g. the most-recently-sent chat message). Be explicit in the AB_ACTION label.
+4. Argument order is \`<value> <action> [flags]\` — flags after the action. Putting \`--name\` / \`--exact\` before the action makes agent-browser fail with "Unknown subaction".
+5. \`--name "<n>"\` is **role-only**. Never pass it to \`find text\`, \`find label\`, etc.
+6. \`--name\` matches by substring. Add \`--exact\` whenever the name you read from the snapshot is the element's whole accessible name — without it a short name such as "Log in" also matches "Log in with Google" and "Log in with SSO", and the recording silently pins the first of them.
+7. \`find\` includes its own wait; do not chain a \`wait\` before it.
+8. **A step that names an element by position gets a positional locator.** "the first row", "the topmost item", "the latest message" identify by \`first\`/\`last\`/\`nth\` on a stable inner selector — never by the title, subject, or body text that record happened to carry. That text is data the environment supplies: pinning it makes the test pass only while that same record stays in that position, and the next run opens a different one.
+9. **A string read off a snapshot row is an accessible name, not a label.** A row like \`textbox "Email"\` says the field's accessible name is "Email" — which \`find role textbox --name "Email" --exact\` matches and \`find label "Email"\` matches only when the page also associates a \`<label>\` with the input. Many forms do not. Record \`find label\` only when you confirmed the association (there is a \`<label for=...>\`, or the input sits inside the label); otherwise use the role form with \`--name\`.
+
+**Examples:**
+
+- ✓ \`find last "[data-testid='reply-link']" click\` — specific attribute + layout-guaranteed last match
+- ✓ \`find role button click --name "Submit"\` — role + accessible name (flags after action)
+- ✓ \`find role button click --name "Log in" --exact\` — short name needs \`--exact\`, or "Log in with SSO" matches too
+- ✗ \`find role button --name "Submit" click\` — wrong order
+- ✗ \`find last "button" click\` — bare tag
+
+### Selector workflow
+
+1. Run \`snapshot\` and read the ARIA tree.
+2. Identify the element; note its exact \`aria-label\` if present.
+3. If the element really carries \`aria-label\` → use \`[aria-label='...']\`. Otherwise → use \`text=...\` **for the action**.
+   For a **\`get count\` probe** neither is safe: \`get count\` takes plain CSS and answers \`0\` for anything else, and an \`aria-label\` selector for a name the element does not carry as that attribute counts \`0\` too — both report an element that is plainly there as missing. Probe with \`[data-testid='...']\`, or with \`find role <role> text --name "<accessible name>" --exact\`, which asks the accessibility tree the snapshot came from.
+4. For links where \`text=\` fails, find the link's URL in the snapshot and use \`a[href*='...']\` with a distinctive substring.
+5. For checkboxes: try \`check "text=Label"\` or \`check "[aria-label='Label']"\`.
+6. If repeated labels make every ALLOWED selector ambiguous → use the \`find\` subset above.
+7. Never guess. If a selector fails, take a fresh snapshot before retrying.
+8. **A click that reports success but changes nothing means the element sits outside the visible part of an inner scroll container** — the event dispatches, the app never reacts, and no error is printed. Run \`scrollintoview\` on the element and click again. Scroll to the element itself, addressed by a CSS selector (\`scrollintoview "button.primary-action"\`); \`scrollintoview "text=…"\` can land on a text node that leaves the control still clipped. Do not read this as a product bug or reach for a \`@ref\` — verify by checking that the DOM changed (e.g. \`get count\` on what the click should have produced).
+
+### Special input types
+
+**contenteditable / RichText editors**: \`fill "[contenteditable='true']" "<text>"\` works on contenteditable elements (chat composers, WYSIWYG bodies) — agent-browser sets the text directly. Use a single \`fill\`; do NOT just \`click\` the field and rely on \`keyboard inserttext\` (that keystroke command is not recorded as a structured action, so the text never makes it into the generated test and the field ends up empty on replay).
+
+**combobox / select with a required marker (\`*\`)**: required form fields often include the marker in their accessible name. If \`find role combobox click --name "<label>"\` misses, prefer \`find label "<label>" click\` or \`click "[aria-label='<label> *']"\`.
+
+**Starting the cleanup**: the undo's first command must be the navigation that puts the browser where the undo can act — the same \`navigate\` you would issue if you arrived with the page freshly opened. Do not begin it from wherever the steps happened to end. The undo exists for the runs that went wrong, and on those the browser is not where the last step left it; a cleanup recorded as "click the menu that is on screen" then fails, and what the case created stays in the environment. Record the navigation even when it changes nothing at recording time.
+
+**Verifying cleanup / deletion**: assert the *absence* of the deleted thing, not the surrounding listing screen's text. Wait for the deletion to settle with \`wait --fn "!document.body.innerText.includes('<unique-label>')"\`, then record the assert with a marked probe: \`CCQA_ASSERT=element_not_visible ... get count "text=<unique-label>"\` (see Assertion Protocol) — never \`wait "<css-selector>" --state hidden\` (blocks the daemon) and never \`wait --text "<navbar label>"\` (passes regardless of the deletion).
+
+**File inputs (\`<input type="file">\`) / OS file-picker dialogs**: do NOT \`click\` the input — that opens the OS picker, which agent-browser cannot drive. Use \`upload "<selector>" <path>\` instead. agent-browser sets the input's files directly via the underlying browser API, no native dialog ever opens. Use an ALLOWED selector to identify the input (\`[aria-label='…']\`, \`[data-testid='…']\`, \`[type='file']\` only when it's unique on the page). File paths must be plain shell args — wrap each in \`"\` for safety. Reference fixtures via \`\${CCQA_FIXTURES_DIR}/<name>\` so the same spec works locally and in CI; conventionally fixtures live under \`.ccqa/fixtures/\` and the env var resolves there. Multi-file inputs accept several positionals: \`upload "[aria-label='Attach']" "\${CCQA_FIXTURES_DIR}/a.pdf" "\${CCQA_FIXTURES_DIR}/b.pdf"\`.
+
+## Test Specification
+
+Title: ${input.title}
+
+Each step's instruction names the URL to open directly (or via \`\${ENV_VAR}\`). Open exactly the URL the step says to open.
+
+## Steps
+
+${stepsText}
+${expectationsText}${contextText}${conventionsText}${previousText}
+## Execution Workflow
+
+For each step:
+1. Emit \`STEP_START|<step-id>|<short description>\`.
+2. Run \`snapshot -i -c\` and identify selectors from the ARIA tree. A full \`snapshot\` is large; when you need the page's text, scope it with \`snapshot -c -s "<css>"\`.
+3. Execute the step's actions using ALLOWED selectors (see Selector Rules), prefixing each command with \`CCQA_STEP=<step-id>\` like every agent-browser command in the step. **Batch them:** put every command you can already write — the actions, their waits, the \`CCQA_ASSERT\` checks, and a closing \`snapshot -i -c\` when you need to see the result — into one \`run_commands\` call. Each turn costs far more than a command; use a single Bash call only when you must see one answer before you can write the next command.
+4. Emit \`AB_ACTION|...\` for every browser action (see AB_ACTION Protocol).
+5. Verify the outcome from the batch's output. When a batch stops at a failure, everything before it is recorded: look at the page and continue from there.
+6. Confirm at least **two independent signals** (URL change, element appearance, text change, ...). This is how *you* decide the step worked and it is safe to continue. It is not what gets recorded.
+7. Record as assertions only the signals the step's own \`expected\` asks about, by putting a \`CCQA_ASSERT=<marker>\` prefix on the verification command itself (see Assertion Protocol). Every assert type has a marker form; a printed \`AB_ACTION|assert|...\` line records nothing.
+8. Emit \`STEP_DONE\`, \`ASSERTION_FAILED\`, or \`STEP_SKIPPED\`.
+
+**Protocol lines are recorded ONLY from your plain assistant text.** Every
+\`STEP_START\` / \`STEP_DONE\` / \`RUN_COMPLETED\` line MUST be printed as normal
+message text between tool calls — never through Bash (\`echo\` etc.) and never
+omitted. Step attribution of browser actions comes from the \`CCQA_STEP\`
+prefix on each command (that prefix is authoritative, not the \`STEP_START\`
+line). **Assertions are recorded only from the \`CCQA_ASSERT\` prefix on
+verification commands** — a command that ran, whose failure rolls the record
+back. A printed \`AB_ACTION|assert|...\` line performs nothing, so nothing
+proves it; it is reported and not recorded.
+
+**After form submission or navigation:** take a fresh snapshot before continuing. If an intermediate screen appears (account selection, role picker, ...), complete it and emit AB_ACTION for each interaction.
+
+## Guardrails
+
+- **Stop after 3 consecutive failures on the same step** — emit \`ASSERTION_FAILED\` and report the blocker.
+- **Stay on a flow you have started.** Once a step is inside something whose state lives on the page — a conversation, a multi-step dialog, a form not yet saved — do not navigate away to investigate; that state does not come back. Look things up in the source with Read, Grep and Glob instead.
+- **Clean up before you stop.** When you end the run with \`ASSERTION_FAILED\` after the case has created something, still perform its cleanup steps, then emit \`RUN_COMPLETED|failed\`. What a failed recording leaves behind breaks the next run of every case that lists the same things.
+- **The step must match the application.** When what a step asks for is not there, or the application does it in another place or order, do not bend the recording to fit: emit \`ASSERTION_FAILED|<step-id>|spec-mismatch: <what the application does instead> — suggested step: <the instruction / expected rewritten to match>\`. Read the source to ground the suggestion. A recording that works around the step hides the mismatch; the report gets the spec fixed. Redoing an earlier step's work to make this one possible — going back to refill or resubmit what an earlier step already did — is such a workaround.
+- **No workarounds.** If all ALLOWED selectors fail, emit \`ASSERTION_FAILED|...|selector-drift: ...\`. Do NOT fall back to coordinate clicks, mouse moves, or \`Tab\`+\`Enter\` keyboard navigation — they cannot be recorded as reliable test actions.
+- Do NOT retry a selector without taking a fresh snapshot first.
+- Do NOT work around blockers (login walls, missing data, captchas) — stop and report.
+- **Do NOT suppress errors.** Never use \`2>/dev/null\`, \`|| true\`, \`; true\`, or any technique that hides agent-browser failures. Each \`agent-browser\` invocation must be its own standalone Bash call. Chaining multiple agent-browser commands with \`&&\` / \`;\` / \`|\` is rejected by the hook layer.
+- **If \`agent-browser\` is not found, stop immediately.** Do not run \`which\`, \`find\`, \`npm ls\`, \`npm install\`, \`npx\`, \`brew\`, or any other discovery / installation command. Emit one line and terminate: \`ASSERTION_FAILED|step-XX|agent-browser binary not available in PATH\`.
+
+## Source Code Reference
+
+You have \`Read\`, \`Grep\`, and \`Glob\` to inspect the application source code. Use them proactively to find correct selectors — do NOT guess \`a[href*='...']\` patterns.
+
+**When**: before clicking a link (find the \`href\`); before navigating to a new page (understand routing); when an ARIA element exists but no ALLOWED selector matches (find the actual HTML attributes).
+
+**How**: \`Grep\` for UI text / component names / URL patterns → \`Read\` the JSX/TSX to find \`href\`, \`aria-label\`, \`data-testid\`, or class names → build a precise ALLOWED selector.
+
+**Rules**: only READ source files, never modify them. Keep searches focused.
+
+## Waiting for Async Operations
+
+Prefer \`wait\` over polling:
+
+\`\`\`bash
+CCQA_STEP=<step-id> agent-browser --session ${sessionName} wait --text "<completion text>"
+\`\`\`
+
+If polling is required (e.g. waiting for a spinner to disappear):
+
+\`\`\`bash
+for i in $(seq 1 18); do
+  sleep 10
+  result=$(agent-browser --session ${sessionName} snapshot 2>&1)
+  echo "$result" | grep -q "<done indicator>" && break
+done
+CCQA_STEP=<step-id> agent-browser --session ${sessionName} snapshot
+\`\`\`
+
+After waiting, always take a final snapshot. Emit \`AB_ACTION|wait|text=<text>|<label>\`.
+
+## AB_ACTION Protocol
+
+After **every** browser action, emit one line (outside any code block):
+
+\`\`\`
+AB_ACTION|cookies_clear
+AB_ACTION|open|<url>
+AB_ACTION|click|<selector>|<visible label>
+AB_ACTION|dblclick|<selector>|<visible label>
+AB_ACTION|fill|<selector>|<value>|<aria label>
+AB_ACTION|check|<selector>|<visible label>
+AB_ACTION|uncheck|<selector>|<visible label>
+AB_ACTION|press|<Key>
+AB_ACTION|select|<selector>|<value>|<aria label>
+AB_ACTION|hover|<selector>|<visible label>
+AB_ACTION|scroll|<direction>|<pixels>
+AB_ACTION|drag|<source selector>|<target selector>|<source label>
+AB_ACTION|upload|<file-input selector>|<file1>[|<file2>...]
+AB_ACTION|wait|<selector or text>|<label>
+AB_ACTION|snapshot|<key observation, max 100 chars>
+
+# find_* (semantic locator fallback). <extra> = role's --name OR nth's index OR "".
+# <exact> = literal "exact" if --exact was passed, "" otherwise. Keep empty pipe slots.
+AB_ACTION|find_click|<locator>|<value>|<extra>|<exact>|<label>
+AB_ACTION|find_dblclick|<locator>|<value>|<extra>|<exact>|<label>
+AB_ACTION|find_hover|<locator>|<value>|<extra>|<exact>|<label>
+AB_ACTION|find_focus|<locator>|<value>|<extra>|<exact>|<label>
+AB_ACTION|find_check|<locator>|<value>|<extra>|<exact>|<label>
+AB_ACTION|find_uncheck|<locator>|<value>|<extra>|<exact>|<label>
+AB_ACTION|find_fill|<locator>|<value>|<extra>|<exact>|<input>|<label>
+AB_ACTION|find_type|<locator>|<value>|<extra>|<exact>|<input>|<label>
+\`\`\`
+
+Selectors in AB_ACTION must follow Selector Rules. \`find_*\` lines use the locator + value pair instead of a separate selector. Do NOT include literal \`|\` inside any field — replace with a space if necessary.
+
+**CRITICAL — record only successful actions.** The AB_ACTION stream is the canonical replay sequence: every line must be reproducible on a fresh browser session.
+
+- A non-zero exit from agent-browser (selector not found, element not interactable, timeout) → **do NOT emit AB_ACTION** for that attempt. Switch selector and only emit the AB_ACTION for the call that finally succeeded.
+- If you tried several selectors / \`find_*\` locators for the same logical action, emit AB_ACTION for the **last working one only**. Multiple failed attempts in a row will all fail at replay validation and silently delete the step from the generated test.
+- An assertion follows the same rule: mark only the check that verified on the current page in the current snapshot.
+- **Open only a URL the step names.** A step's \`open\` takes the address its own instruction gives — a \`\${VAR}\` plus the literal tail after it. Never open an address the run produced: the id in \`/items/01H8XZ...\` belongs to the record this run created, and opening it next time visits a record that run does not have (or worse, one it does, silently testing the wrong thing). Reach such a page the way a person does — click through from where the run already is.
+
+- **Environment-failure recovery is not part of the test.** If a session times out, a network blip drops you to login, or the app crashes and you re-login / re-navigate / re-fill to recover, do NOT emit AB_ACTION for the recovery operations.
+- If a step ultimately fails after retries: emit \`ASSERTION_FAILED\` and STOP. Do not leave half-recorded actions in the stream.
+
+## Assertion Protocol
+
+Record each signal you verified as an assertion. The **primary mechanism** is
+a \`CCQA_ASSERT=<marker>\` env prefix on the verification command itself — the
+marker rides the same channel as the command, so the assertion is captured
+even if you print no protocol text. The check you were going to run anyway
+becomes the recorded assertion:
+
+\`\`\`bash
+# text_visible — the marked wait IS the assertion (no separate assert line)
+CCQA_STEP=<step-id> CCQA_ASSERT=1 agent-browser --session SESSION wait --text "Submitted" --timeout 3000
+# element_visible / element_not_visible — mark the get-count probe
+CCQA_STEP=<step-id> CCQA_ASSERT=element_visible agent-browser --session SESSION get count "[aria-label='Settings']"
+CCQA_STEP=<step-id> CCQA_ASSERT=element_not_visible agent-browser --session SESSION get count "text=Deleted item"
+# url_contains — the substring rides in the marker; put it on \`get url\`
+CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session SESSION get url
+# element state — mark the \`is\` probe that asks for it
+CCQA_STEP=<step-id> CCQA_ASSERT=element_disabled agent-browser --session SESSION is enabled "#submit"
+CCQA_STEP=<step-id> CCQA_ASSERT=element_checked agent-browser --session SESSION is checked "#opt-in"
+\`\`\`
+
+**Marker semantics:**
+
+| Marker | On command | Records |
+|--------|------------|---------|
+| \`1\` (alias of \`text_visible\`) | \`wait --text "<text>"\` | \`assert text_visible <text>\` — replaces the wait (the recorded assert waits itself) |
+| \`element_visible\` | \`get count "<selector>"\` | \`assert element_visible <selector>\` |
+| \`element_not_visible\` | \`get count "<selector>"\` | \`assert element_not_visible <selector>\` (use \`text=<text>\` as the selector to assert text absence) |
+| \`url_contains:<substring>\` | any command | \`assert url_contains <substring>\` in addition to whatever the command records |
+| \`element_enabled\` / \`element_disabled\` | \`is enabled "<selector>"\` | \`assert <marker> <selector>\` |
+| \`element_checked\` / \`element_unchecked\` | \`is checked "<selector>"\` | \`assert <marker> <selector>\` |
+
+- A marked command that exits non-zero records nothing — fix the check and re-run it.
+- A marker that doesn't match its command (e.g. \`CCQA_ASSERT=1\` on a \`click\`) is ignored with a warning — never do that.
+- \`get count\`, \`get url\` and \`is\` exit 0 regardless of what they print. **Read the output**: if the printed count / URL / \`true\`-\`false\` contradicts the marker, the signal did NOT verify — treat it as a failed verification (emit \`ASSERTION_FAILED\` if the step cannot be confirmed another way).
+- **Assert the thing, not how much of it there is.** A step that says a list, a table or a section is shown is satisfied by the list being there. Do not assert the count it happened to have, and never assert an empty-state message ("no items yet") unless the step's own \`expected\` asks for emptiness — the next run has one more record than this one and the test breaks for a reason nobody chose.
+
+- **Assert what the step asks about, nothing else.** The \`expected\` is the contract; anything else you happened to see on the way is not. A nav item, a heading or a greeting that the step never mentions adds no coverage, differs between recordings of the same spec, and is the first thing to break on replay — so the next recording quietly drops it and the test gets weaker without anyone deciding that.
+
+- **An \`expected\` that labels its parts is recorded down to the \`must:\` lines.** A \`when present:\` line names something the product does not produce on every run, so **nothing that fails on its absence may be recorded for it** — no assert, and no \`wait --text\` either: a recorded wait throws on the next run that legitimately lacks it, which is the same failure an assert would have caused. Look at it with \`snapshot\` or \`get count\` if you want to see it, and record nothing. When the step needs to wait for something asynchronous to arrive, anchor that wait on a \`must:\` signal — waiting on the optional one makes the whole step hinge on it. Every line of a labelled \`expected\` carries a label; text with no labels at all is all \`must:\`.
+
+- **\`url_contains\` is opt-in, not a habit.** The same rule, in the form that gets broken most. Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
+- **When you do assert a URL, the substring may come from ONE place only:** a \`\${VAR}\` URL that *this step's own instruction* opened, written as that \`\${VAR}\` followed by the literal tail after it. If the step opens \`\${APP_URL}/todos\`, assert \`\${APP_URL}/todos\` (or the tail \`/todos\`); the recorder resolves \`\${APP_URL}\` per environment. Never assert on a URL you merely *observed* — login redirects, identity-provider pages, and OAuth callbacks all live on a **different, environment-named origin** than the app, so any substring of them (host, origin, OR path) names the environment.
+- **A leading slash does NOT make a substring safe.** \`/auth-staging\`, \`/env-qa\`, \`/tenant-acme\` look like paths but are environment labels — the first segment of an identity-provider or tenant URL, not an application route. If a substring contains an environment name, a stage token (\`dev\`, \`stg\`, \`prod\`), a tenant/org name, or any fragment of a hostname, it is forbidden even with a leading slash. The only safe path substrings are stable *application* routes off the app's own origin (\`/dashboard\`, \`/todos/new\`), taken from a \`\${VAR}\` you opened — not from a redirect you watched.
+
+**Every assert type has a marker command.** There is no text form: a printed
+\`AB_ACTION|assert|...\` line performs nothing, so nothing proves it, and it is
+reported rather than recorded.
+
+| assertType | The command that records it | Use when |
+|------------|------------------------------|----------|
+| \`text_visible\` | \`CCQA_ASSERT=1 ... wait --text "<text>"\` | stable text appears on the page |
+| \`element_visible\` | \`CCQA_ASSERT=element_visible ... get count "<selector>"\` | element is present |
+| \`element_not_visible\` | \`CCQA_ASSERT=element_not_visible ... get count "<selector>"\` | element is gone — and text absence too, as \`text=<text>\` |
+| \`url_contains\` | \`CCQA_ASSERT=url_contains:<substring> ... get url\` | the URL contains a pattern |
+| \`element_enabled\` / \`element_disabled\` | \`CCQA_ASSERT=<marker> ... is enabled "<selector>"\` | a control is usable, or is not |
+| \`element_checked\` / \`element_unchecked\` | \`CCQA_ASSERT=<marker> ... is checked "<selector>"\` | a checkbox is ticked, or is not |
+
+**Stability rules — CRITICAL. NEVER assert on values that change run-to-run:**
+
+- Timestamps, session IDs, exact numeric counts that vary between runs.
+- **Absolute dates / clock times**: \`12:34:56\`, \`2026-05-20\`, \`2026年5月20日\`, \`5月20日\`. These are scrubbed by post-trace literal-scrub anyway — avoid them at the source.
+- **Relative-time labels** — true only in the moment of the trace, stale by replay:
+  - English: \`just now\`, \`5 minutes ago\`, \`2 hours ago\`, \`yesterday\`, \`last week\`.
+  - Japanese: \`たった今\`, \`3分前\`, \`1時間前\`, \`昨日\`.
+- Dynamic counts like "42 results" → assert on the stable suffix ("results") only.
+- **PREFER**: status text, button labels, URL patterns, element enabled/disabled state.
+
+**No tautological state asserts — CRITICAL for \`element_enabled\` / \`element_disabled\`:**
+
+The selector must identify *which* element by something **other than the state you are asserting**. Selecting the element *by* its state and then asserting that state is a tautology that always passes and verifies nothing.
+
+- ✗ \`element_disabled | button[disabled] |\` — picks an already-disabled button, then "confirms" it is disabled. Passes even if the button the spec cares about is missing or enabled.
+- ✗ \`element_enabled | button:enabled |\`, \`[aria-disabled='true']\`, \`input:disabled\` — same trap.
+- ✓ Name the element by a stable, state-independent selector and assert the state on it: e.g. the "Submit" button is \`find role button --name "Submit"\`; to assert it is disabled, give \`element_disabled\` a selector that targets *that* button (a stable \`id\` / \`data-testid\` / unique class), **not** \`[disabled]\`.
+- If you cannot target the specific element without a state pseudo-class/attribute, **do not emit the enabled/disabled assert** — assert a user-visible consequence instead (e.g. the action it gates does not happen, a "you don't have permission" message is shown), or rely on \`text_visible\` for the label plus \`text_not_visible\` for what an enabled control would have produced.
+
+**Page-context and selector rules:**
+
+- After a navigation, take a **fresh snapshot** before emitting any assertion. Don't assert on text from the previous page.
+- Assertion selectors follow the same Selector Rules as actions — never invent aria-label values; use the exact strings from the current snapshot.
+- When unsure, prefer \`text_visible\` — a \`CCQA_ASSERT=1\` marked \`wait --text\` verifies and records it in one command.
+
+**MUST-VERIFY rule — STRICT (applies to every assert except \`url_contains\`):**
+
+The \`snapshot\` output is the **accessibility tree**, but \`agent-browser\` queries the **real DOM**. They don't always agree. Two known traps:
+
+1. *Selector trap*: a snapshot row like \`textbox "Email address"\` may be reachable via \`[placeholder='...']\` but **not** via \`[aria-label='...']\` if no aria-label attribute is actually set (the browser inferred the label from \`<label for=>\` / placeholder).
+2. *Text trap*: a snapshot row like \`link "Dashboard"\` may come from \`<a><img alt="Dashboard"></a>\` — the visible "text" is an \`alt\` attribute, not a text node. \`text_visible\` (which scans visible text nodes) will NOT find it.
+3. *Input-value trap*: after you \`fill\` an \`<input>\` / \`<textarea>\` / \`[contenteditable]\`, the text you typed lives in the element's **value**, not as a visible text node. **Do NOT assert the typed value with \`text_visible\`** — it will never match. The spec's "the field reflects X" expectation is implicitly confirmed when the form submits successfully and the value shows up on the *result* page (a list row, a detail page). Assert there, not on the input itself.
+
+**Verify the assertion form actually resolves on the live page.** The
+verification and the recorded assertion are the same marked command:
+
+\`\`\`bash
+# text_visible
+CCQA_STEP=<step-id> CCQA_ASSERT=1 agent-browser --session SESSION wait --text "<text>" --timeout 3000
+# element_visible — >=1 printed means present
+CCQA_STEP=<step-id> CCQA_ASSERT=element_visible agent-browser --session SESSION get count "<selector>"
+# element_not_visible — 0 printed means absent (works for text too: "text=<text>")
+CCQA_STEP=<step-id> CCQA_ASSERT=element_not_visible agent-browser --session SESSION get count "<selector>"
+# element state — \`is\` prints true/false and exits 0 either way; read it
+CCQA_STEP=<step-id> CCQA_ASSERT=element_disabled agent-browser --session SESSION is enabled "<selector>"
+CCQA_STEP=<step-id> CCQA_ASSERT=element_checked agent-browser --session SESSION is checked "<selector>"
+\`\`\`
+
+When *no* form verifies — e.g. \`[aria-label='X']\`, \`[placeholder='X']\`, and \`text=X\` all timed out, or the visible text turned out to be an \`alt\` — **drop the assertion entirely**. Fewer real assertions beat invented ones that fail at replay. \`url_contains\` is exempt (it checks the URL string, not the DOM).
+
+## Status Protocol
+
+Emit exactly one status line per step (outside any code block):
+
+\`\`\`
+STEP_START|<step-id>|<short description>
+STEP_DONE|<step-id>|<what was verified>
+ASSERTION_FAILED|<step-id>|<category: spec-mismatch|app-bug|env-issue|auth-blocked|missing-test-data|selector-drift|agent-misread>: <reason>
+STEP_SKIPPED|<step-id>|<reason>
+RUN_COMPLETED|passed|<summary>
+RUN_COMPLETED|failed|<summary>
+\`\`\`
+
+**\`RUN_COMPLETED\` is what ends the run.** A session that stops without it is
+recorded as FAILED, however many steps went well: nothing else can tell a
+finished route from one you abandoned halfway.
+
+${callerGuidance}## Start
+
+Begin by clearing cookies, then proceed straight to the first step's instruction.
+
+\`\`\`bash
+agent-browser --session ${sessionName} cookies clear
+\`\`\`
+
+(The cookies-clear preamble belongs to no step, so it is the one command
+without a \`CCQA_STEP\` prefix.)
+
+Emit:
+\`\`\`
+AB_ACTION|cookies_clear
+\`\`\`
+
+Then emit \`STEP_START|${firstStepId}|...\` and execute the first step, prefixing
+every one of its agent-browser commands with \`CCQA_STEP=${firstStepId}\`. The first
+step is responsible for opening the initial URL.
+`;
 }
-/** The same action addressed by role + accessible name, or null when there is no such form. */
-function labelFallback(action) {
-	const loc = action.locator;
-	if (!loc || loc.by !== "label") return null;
-	const role = LABEL_FALLBACK_ROLE[action.action];
-	if (role === void 0) return null;
-	return {
-		...action,
-		locator: {
-			by: "role",
-			value: role,
-			name: loc.value,
-			exact: true
-		}
-	};
+function buildTracePrompt(title) {
+	return `Execute the test for "${title}". Each step's instruction includes the URL or selector context it needs.`;
 }
 /**
-* Spawn one interaction, waiting for its element the way an assertion waits
-* for its text: a recording pauses for a snapshot between opening a page and
-* typing into it, the replay does not, so the replay reaches a field sooner
-* than the recording ever did.
-*
-* Only a "no element" failure waits — anything else repeats identically. When
-* there is an `alternate` form it is tried on every attempt rather than after
-* the wait: a label the page never associates with its input will not start
-* matching, so waiting first spends the budget for nothing.
+* The case's expectations, plus the one rule that decides where each is
+* recorded. Without the rule a recorder either asserts everything at the end —
+* on a page the flow has already left — or asserts each item at every step it
+* might apply to, which is the over-assertion the selector rules exist to
+* prevent.
 */
-function runInteraction(argv, alternate, patience, sessionName) {
-	const started = Date.now();
-	const deadline = started + ASSERT_TIMEOUT_MS;
-	let settled = false;
-	for (let attempt = 0;; attempt++) {
-		let result = spawnAB(argv);
-		if (result.status !== 0 && result.wedged === true) result = spawnAB(argv);
-		const waitedMs = Date.now() - started;
-		if (result.status !== 0 && superseded(result) && !settled && isOpen(argv)) {
-			settled = true;
-			spawnAB([
-				"--session",
-				sessionName,
-				"wait",
-				"--load",
-				"networkidle"
-			]);
-			continue;
-		}
-		if (result.status === 0 || !notFound(result)) return {
-			result,
-			viaAlternate: false,
-			waitedMs
-		};
-		if (alternate !== null) {
-			const alt = spawnAB(alternate);
-			if (alt.status === 0) return {
-				result: alt,
-				viaAlternate: true,
-				waitedMs
-			};
-		}
-		if (patience.spent || attempt + 1 >= INTERACTION_ATTEMPTS || Date.now() >= deadline) {
-			patience.spent = true;
-			return {
-				result,
-				viaAlternate: false,
-				waitedMs: Date.now() - started
-			};
-		}
-		sleepSync(INTERACTION_POLL_INTERVAL_MS);
-	}
+function renderExpectations(expectations) {
+	if (expectations.length === 0) return "";
+	return `
+## Expected results
+
+The case states these without saying which step delivers them:
+
+${expectations.map((text) => `- ${text}`).join("\n")}
+
+**Assign each to the step it first becomes true in, and assert it there and nowhere else.** Read the flow to decide: an expectation about what a form did belongs to the step that submitted it, not to a later step that happens to still show it. Assert each one exactly once — a repeat adds no coverage and breaks first. An expectation you cannot place is one you report in \`STEP_DONE\` text as unplaced; never invent a step for it, and never assert it "just in case".
+`;
 }
 /**
-* Say what a `by: "css"` locator that is not CSS actually addresses.
-*
-* `get count` answers 0 for Playwright's notation instead of failing, so a
-* route holding one reads as dead. Rewritten in place, and reported, so the
-* saved route carries the form that replays rather than the one that counts
-* nothing. Notation this cannot convert leaves the locator alone; the assert
-* path then treats it as unverifiable rather than absent.
+* What the cleanup must make true. Separate from the case's expectations
+* because its steps are: a deletion is confirmed by the thing being gone,
+* which is only true after the undo has run, and asserting it among the
+* case's own steps would check it while the thing still exists.
 */
-function nameNotation(action) {
-	const loc = action.locator;
-	if (action.action !== "assert" || loc?.by !== "css") return null;
-	const named = parseNotation(loc.value);
-	if (named === null || named === "opaque" || named.by !== "text") return null;
-	action.locator = named;
-	return `${loc.value} is not a CSS selector — asked as ${describeLocator(named)}`;
+function renderCleanupExpectations(expectations) {
+	if (expectations.length === 0) return "";
+	return `
+## Expected results of the cleanup
+
+The case states these about its cleanup steps:
+
+${expectations.map((text) => `- ${text}`).join("\n")}
+
+**Assert each in the cleanup step that makes it true, and nowhere else.** They describe the state after the undo, so a cleanup step is not done when the command returns — it is done when what the case says here holds. Record the check as an assertion the same way a step's own is recorded.
+`;
 }
 /**
-* An attribute selector that counted nothing, asked of the accessibility tree
-* the name was read from. See docs/targets.md for why the two disagree.
-*
-* The snapshot is read for the role, then `find role` is asked as well: the
-* tree says the name exists somewhere, the probe says the replay can reach it,
-* and only the second is what the route will depend on.
-*/
-function askTheAccessibilityTree(action, sub, sessionName) {
-	if (action.action !== "assert" || action.locator?.by !== "css") return null;
-	const name = nameFromAttributeSelector(action.locator.value);
-	if (name === null) return null;
-	const snapshot = spawnAB([
-		"--session",
-		sessionName,
-		"snapshot"
-	]);
-	if (snapshot.status !== 0) return null;
-	const role = roleOfAccessibleName(snapshot.stdout, sub(name));
-	if (role === null) return null;
-	if (spawnAB(roleProbe(["--session", sessionName], role, sub(name))).status !== 0) return null;
-	const promoted = `${action.locator.value} names an element rather than an attribute — confirmed as role=${role}`;
-	action.locator = {
-		by: "role",
-		value: role,
-		name,
-		exact: true
-	};
-	return {
-		skipped: false,
-		ok: true,
-		reason: "",
-		promoted
-	};
+* Sections of the case ccqa does not interpret — the precondition, notes the
+* author left. Passed through verbatim: they are written for whoever runs the
+* case, and the recorder is now that reader.
+*/
+function renderContext(context) {
+	if (context.length === 0) return "";
+	return `
+## About this case
+
+${context.map((s) => `### ${s.heading}\n\n${s.body}`).join("\n\n")}
+`;
 }
 /**
-* Replay one recorded action against the validation session. Element-presence
-* checks go through `runPollCheck` (which uses `get count`, never the blocking
-* `wait <selector>`); everything else spawns the agent-browser argv.
+* The project's own recording guidance. Where the case says what to do, this
+* says how this project is driven — which account signs in, what has to be
+* true before the first step. Prose, verbatim: it is written for whoever runs
+* the case, and this is now that reader.
 */
-function runValidationAction(action, sessionName, envOverrides = {}, patience) {
-	const named = nameNotation(action);
-	const withName = (outcome) => named === null || !outcome.ok ? outcome : {
-		...outcome,
-		promoted: outcome.promoted ?? named
-	};
-	const built = actionToAbArgs(action, sessionName, envOverrides);
-	if (built === null) return {
-		skipped: true,
-		ok: false,
-		reason: ""
-	};
-	if (isProbe(built)) {
-		const { ok, reason } = runProbe(built, sessionName);
-		if (ok) return withName({
-			skipped: false,
-			ok,
-			reason
-		});
-		const resolve = (v) => v === void 0 ? "" : resolveEnvRefs(v, envOverrides);
-		return askTheAccessibilityTree(action, resolve, sessionName) ?? {
-			skipped: false,
-			ok,
-			reason
-		};
-	}
-	const fallback = labelFallback(action);
-	const alternate = fallback === null ? null : actionToAbArgs(fallback, sessionName, envOverrides);
-	const { result, viaAlternate, waitedMs } = runInteraction(built, alternate !== null && !isProbe(alternate) ? alternate : null, patience, sessionName);
-	if (viaAlternate) {
-		const promoted = `${action.locator.by}=${action.locator.value} → role=${fallback.locator.value} name="${action.locator.value}"`;
-		action.locator = fallback.locator;
-		return {
-			skipped: false,
-			ok: true,
-			reason: "",
-			promoted
-		};
-	}
-	if (result.status === 0) return withName({
-		skipped: false,
-		ok: true,
-		reason: ""
-	});
-	return {
-		skipped: false,
-		ok: false,
-		reason: `${(result.stderr.trim() || result.stdout.trim() || `agent-browser exit ${result.status ?? "?"}`).slice(0, 200)}${notFound(result) ? ` (waited ${waitedMs}ms)` : ""}`
-	};
-}
-function validateActions(actions, opts) {
-	const kept = [];
-	const dropped = [];
-	const promoted = [];
-	const patience = { spent: false };
-	let skipFromStepId = null;
-	for (let i = 0; i < actions.length; i++) {
-		const action = actions[i];
-		opts.onProgress?.(i, actions.length, action);
-		const stepId = action.stepId ?? NO_STEP_ID;
-		if (skipFromStepId !== null && skipFromStepId !== stepId) skipFromStepId = null;
-		if (skipFromStepId !== null && isPassiveAction(action.action)) {
-			dropped.push({
-				index: i,
-				action,
-				reason: CASCADE_REASON
-			});
-			continue;
-		}
-		const outcome = runValidationAction(action, opts.sessionName, opts.envOverrides, patience);
-		if (outcome.promoted) promoted.push(outcome.promoted);
-		if (outcome.skipped) {
-			kept.push(action);
-			continue;
-		}
-		if (outcome.ok) {
-			kept.push(action);
-			if (skipFromStepId !== null && !isPassiveAction(action.action)) skipFromStepId = null;
-			continue;
-		}
-		dropped.push({
-			index: i,
-			action,
-			reason: outcome.reason
-		});
-		if (!isPassiveAction(action.action)) skipFromStepId = stepId;
-	}
-	const afterRescue = rescueLostSteps(actions, kept, dropped, opts, patience);
-	promoted.push(...afterRescue.promoted ?? []);
-	return {
-		...splitByMode(actions, afterRescue, opts.mode ?? "lenient"),
-		promoted
-	};
+function renderConventions(conventions) {
+	if (conventions.length === 0) return "";
+	return `
+## How this project is driven
+
+${conventions.map((c) => `### ${c.heading}\n\n${c.body}`).join("\n\n")}
+`;
 }
+//#endregion
+//#region src/cli/trace-tools.ts
+const TRACE_TOOLS_SERVER = "ccqa";
+/** A wedged command must not hold the whole trace; agent-browser's own waits are far shorter. */
+const COMMAND_TIMEOUT_MS = 12e4;
+/** Enough of a snapshot or a `get` answer to act on, without flooding the turn. */
+const OUTPUT_CAP = 6e3;
 /**
-* Translate the internal `{ kept, dropped }` result of the rescue pass
-* into the public-facing shape. In strict mode the caller sees the same
-* shape as before (kept/dropped); in lenient mode the still-failed
-* actions move to `unstable` with `replayUnstable: true` tagged on, so
-* codegen can warn about them while still emitting the line.
+* The trace's own tools. Both exist to cut round trips: one turn per browser
+* command is what made a re-record cost hundreds of turns.
+*
+* - `run_commands` runs a batch the recorder wrote, recording each that passes.
+* - `replay_step` runs one step's previous commands.
 */
-function splitByMode(originalActions, result, mode) {
-	if (mode === "strict") return {
-		kept: result.kept,
-		unstable: [],
-		dropped: result.dropped,
-		rescuedSteps: result.rescuedSteps
-	};
-	const droppedByIndex = new Map(result.dropped.map((d) => [d.index, d]));
-	const keptSet = new Set(result.kept);
-	const finalKept = [];
-	const unstable = [];
-	for (let i = 0; i < originalActions.length; i++) {
-		const action = originalActions[i];
-		if (keptSet.has(action)) {
-			finalKept.push(action);
-			continue;
-		}
-		const drop = droppedByIndex.get(i);
-		if (drop) {
-			action.replayUnstable = true;
-			action.replayReason = drop.reason;
-			unstable.push(action);
-		}
-	}
+function buildTraceTools(input) {
+	const offersReplay = input.previous.length > 0;
 	return {
-		kept: finalKept,
-		unstable,
-		dropped: [],
-		rescuedSteps: result.rescuedSteps
+		server: createSdkMcpServer({
+			name: TRACE_TOOLS_SERVER,
+			version: "1.0.0",
+			tools: [tool("run_commands", "Run several agent-browser commands in order, each written exactly as you would run it in Bash (with its CCQA_STEP / CCQA_ASSERT / CCQA_SECRET prefixes). Each that succeeds is recorded; the batch stops at the first that fails. Returns each command's outcome and the output of the last one.", { commands: z.array(z.string()).min(1).describe("agent-browser command lines, one per entry") }, async ({ commands }) => ({ content: [{
+				type: "text",
+				text: await runCommands(commands, input)
+			}] })), ...offersReplay ? [tool("replay_step", "Run one step's previous-recording commands in this browser session and record those that pass. Stops at the first that fails.", { step: z.string().describe("The step id, e.g. step-03") }, async ({ step }) => ({ content: [{
+				type: "text",
+				text: replayStep(step, input)
+			}] }))] : []]
+		}),
+		allowedTools: ["run_commands", ...offersReplay ? ["replay_step"] : []].map((t) => `mcp__${TRACE_TOOLS_SERVER}__${t}`)
 	};
 }
-function rescueLostSteps(actions, kept, dropped, opts, patience) {
-	const stepsWithSurvivors = /* @__PURE__ */ new Set();
-	for (const a of kept) if (a.stepId) stepsWithSurvivors.add(a.stepId);
-	const lostStepDrops = /* @__PURE__ */ new Map();
-	for (const d of dropped) {
-		const id = d.action.stepId;
-		if (!id || stepsWithSurvivors.has(id)) continue;
-		const list = lostStepDrops.get(id) ?? [];
-		list.push(d);
-		lostStepDrops.set(id, list);
-	}
-	if (lostStepDrops.size === 0) return {
-		kept,
-		dropped
-	};
-	const promoted = [];
-	const rescuedIndices = /* @__PURE__ */ new Set();
-	const rescuedSteps = [];
-	const strict = (opts.mode ?? "lenient") === "strict";
-	for (const [stepId, drops] of lostStepDrops.entries()) {
-		const replayed = [];
-		const unverifiable = [];
-		let stillFailing = false;
-		for (const d of drops) {
-			const outcome = runValidationAction(d.action, opts.sessionName, opts.envOverrides, patience);
-			if (outcome.promoted) promoted.push(outcome.promoted);
-			if (outcome.skipped) {
-				unverifiable.push(d.index);
-				continue;
-			}
-			if (outcome.ok) {
-				replayed.push(d.index);
-				continue;
-			}
-			stillFailing = true;
-			if (strict && isCascadeReason(d.reason)) d.reason = outcome.reason;
+async function runCommands(commands, input) {
+	const report = [];
+	for (const [i, cmd] of commands.entries()) {
+		const stop = (why) => [
+			...report,
+			`✗ ${cmd}\n${why}`,
+			...i + 1 < commands.length ? [`The ${commands.length - i - 1} command(s) after it were not run.`] : []
+		].join("\n");
+		if (!isAgentBrowserCommand(cmd)) return stop("Only agent-browser commands can be batched; run anything else with Bash.");
+		const blocked = abCommandBlockReason(cmd, input.envScrubMap);
+		if (blocked !== null) return stop(blocked);
+		const recorded = abActionEventFromCommand(cmd);
+		const checkpoint = input.beforeAbCommand(extractCcqaStepFromBashCommand(cmd) ?? void 0);
+		if (checkpoint) return stop(checkpoint);
+		info(`$ ${scrubEnvValues(cmd, input.envScrubMap)}`);
+		const result = await runShell(cmd, {
+			...process.env,
+			...input.env
+		});
+		const out = result.stdout.trim();
+		if (!(result.status === 0 && (recorded?.holds ? recorded.holds(out) : true))) {
+			const detail = (result.stderr || out || `exit ${result.status ?? "timeout"}`).trim().slice(0, 600);
+			return stop(result.status === 0 ? `The check did not hold; the page answered: ${out.slice(0, 300)}` : detail);
 		}
-		if (replayed.length === 0) continue;
-		for (const i of replayed) rescuedIndices.add(i);
-		if (!stillFailing) for (const i of unverifiable) rescuedIndices.add(i);
-		rescuedSteps.push(stepId);
-	}
-	if (rescuedIndices.size === 0) return {
-		kept,
-		dropped,
-		promoted
-	};
-	const keptSet = new Set(kept);
-	const newKept = [];
-	for (let i = 0; i < actions.length; i++) {
-		const action = actions[i];
-		if (rescuedIndices.has(i) || keptSet.has(action)) newKept.push(action);
+		if (recorded) input.onAbAction(recorded.event);
+		const last = i === commands.length - 1;
+		report.push(`✓ ${cmd}${out && (last || out.length < 200) ? `\n${cap(out)}` : ""}`);
 	}
-	return {
-		kept: newKept,
-		dropped: dropped.filter((d) => !rescuedIndices.has(d.index)),
-		rescuedSteps,
-		promoted
-	};
+	return report.join("\n");
 }
 /**
-* Passive (read-only) actions whose only effect is observation. When a
-* preceding action fails, dropping these too is the right move because
-* they were trying to observe state the failed action would have set up.
+* Async, so the trace's deadline and signal teardown still run while a batch
+* does. Settles on `exit` too: a daemon the command started may hold the pipes open.
 */
-function isPassiveAction(action) {
-	return action === "snapshot" || action === "wait" || action === "assert";
+function runShell(cmd, env) {
+	return new Promise((resolve) => {
+		const child = spawn("bash", ["-c", cmd], {
+			env,
+			timeout: COMMAND_TIMEOUT_MS
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.setEncoding("utf8").on("data", (d) => stdout += d);
+		child.stderr.setEncoding("utf8").on("data", (d) => stderr += d);
+		const done = (status, err) => resolve({
+			status,
+			stdout,
+			stderr: stderr || (err ?? "")
+		});
+		child.on("error", (e) => done(null, e.message));
+		child.on("close", (status) => done(status));
+		child.on("exit", (status) => setTimeout(() => done(status), 1e3).unref());
+	});
+}
+function cap(out) {
+	return out.length <= OUTPUT_CAP ? out : `${out.slice(0, OUTPUT_CAP)}\n… (${out.length - OUTPUT_CAP} more characters; scope it with snapshot -s <selector>)`;
+}
+function replayStep(step, input) {
+	const actions = input.previous.filter((a) => a.stepId === step && a.action !== "snapshot").map(({ replayUnstable: _u, replayReason: _r, ...a }) => a);
+	if (actions.length === 0) return `No previous commands for ${step}. Record it with the Execution Workflow.`;
+	const { passed, unchecked, failed } = replayUntilFailure(actions, {
+		sessionName: input.sessionName,
+		envOverrides: { CCQA_RUN_ID: input.env["CCQA_RUN_ID"] ?? input.sessionName }
+	});
+	input.onReplayed(step, passed);
+	info(`replay_step ${step}: ${passed.length}/${actions.length} replayed${failed ? "" : " — all passed"}`);
+	const notRun = unchecked.length === 0 ? "" : `\nThese checks could not be run here and were not recorded — perform the ones Expected still asks for yourself:\n` + unchecked.map((a) => `- ${describeStepAction(a)}`).join("\n");
+	if (!failed) {
+		const next = unchecked.length === 0 ? " Emit STEP_DONE and go on." : "";
+		return `${passed.length} of ${actions.length} previous command(s) of ${step} ran and are recorded, its checks included.${next}${notRun}`;
+	}
+	return `${passed.length} of ${actions.length} previous command(s) of ${step} ran and are recorded. The next one failed: ${describeStepAction(failed.action)} — ${failed.reason}\nThe page is where the recorded commands left it. Finish ${step} with the Execution Workflow (snapshot first); do not re-run the recorded commands.${notRun}`;
 }
 //#endregion
 //#region src/cli/trace.ts
+/** The recorder's Bash runs agent-browser only: source is read with Read/Grep/Glob. */
+function traceBashGuard(cmd) {
+	if (isAgentBrowserCommand(cmd)) return null;
+	return "Bash here runs agent-browser commands only. Read, search and list the source with the Read, Grep and Glob tools; wait for the page with agent-browser wait, not sleep.";
+}
+/** Browser commands in one step between spec-mismatch checkpoints (see `beforeAbCommand`). */
+const STEP_CHECKPOINT = 20;
 /**
 * Step ids (in spec order) whose kept actions include no assertion. A step
 * with none produced a test that performs the step but verifies nothing
@@ -25686,6 +26030,11 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	}
 	const conventions = await loadConventions(opts.cwd ?? process.cwd(), { guides: opts.conventions ?? [] });
 	for (const w of conventions.warnings) warn(w);
+	const caseRef = testCase.ref;
+	const previous = await tryGetRecording(caseRef);
+	const previousActions = previous ? [...previous.actions, ...previous.cleanup ?? []] : [];
+	if (previousActions.length > 0) meta("previous", opts.freshIr ? "ignored (--fresh-ir)" : `${previousActions.length} action(s) offered as a map`);
+	const offersMap = !opts.freshIr && previousActions.length > 0;
 	const baseSystemPrompt = buildTraceSystemPrompt({
 		title: testCase.title,
 		steps,
@@ -25697,7 +26046,8 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		...testCase.expectations.length > 0 ? { expectations: testCase.expectations } : {},
 		...testCase.cleanupExpectations.length > 0 ? { cleanupExpectations: testCase.cleanupExpectations } : {},
 		...testCase.context.length > 0 ? { context: testCase.context } : {},
-		...opts.instruction ? { instruction: opts.instruction } : {}
+		...opts.instruction ? { instruction: opts.instruction } : {},
+		...offersMap ? { previousRecording: previousActions } : {}
 	});
 	const promptBundle = await loadPromptBundle(opts.hubContext ?? null, "record", opts.cwd ?? process.cwd());
 	if (promptBundle !== null) meta("prompt", promptBundle.loaded.join(" + "));
@@ -25718,40 +26068,71 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		} : action;
 	};
 	let lastCommandPushCount = 0;
+	const onAbAction = ({ abAction, stepId, assertMarker, secret }) => {
+		const stepForCommand = stepTracker.fromCommand(stepId);
+		const line = abAction === void 0 ? null : scrubEnvValues(abAction, envScrubMap);
+		let recorded = null;
+		if (assertMarker !== void 0) {
+			recorded = promoteMarkedAssert(line, scrubEnvValues(assertMarker, envScrubMap));
+			if (recorded === null) warn(`CCQA_ASSERT=${assertMarker} does not match a promotable command (wait --text / get count / url_contains:<substring>) — recording the command without an assert`);
+		}
+		if (recorded === null) {
+			const parsed = line === null ? null : parseAbActionLine(line);
+			recorded = parsed === null ? [] : [parsed];
+		}
+		let pushed = 0;
+		for (const action of recorded) {
+			const stamped = withStepId(action, stepForCommand);
+			if (stamped) {
+				traceActions.push(secret ? {
+					...stamped,
+					secret: true
+				} : stamped);
+				pushed += 1;
+			}
+		}
+		lastCommandPushCount = pushed;
+	};
+	const commandsByStep = /* @__PURE__ */ new Map();
+	const beforeAbCommand = (stepId) => {
+		if (stepId === void 0) return null;
+		const n = (commandsByStep.get(stepId) ?? 0) + 1;
+		commandsByStep.set(stepId, n);
+		if (n % STEP_CHECKPOINT !== 0) return null;
+		return `${stepId} has taken ${n - 1} browser commands. If the application does not do what this step says — the control is somewhere else, things happen in a different order, the result never appears — stop working around it and report it: ASSERTION_FAILED|${stepId}|spec-mismatch: <what the application does instead> — suggested step: <the instruction / expected rewritten to match>. If the step does match and you are close, run this command again to continue.`;
+	};
+	const invokeBase = agentBrowserInvokeBase({
+		sessionName,
+		runId: sessionName
+	});
+	const traceTools = buildTraceTools({
+		previous: offersMap ? previousActions : [],
+		sessionName,
+		env: invokeBase.env ?? {},
+		envScrubMap,
+		onReplayed: (stepId, passed) => {
+			stepTracker.fromCommand(stepId);
+			for (const action of passed) traceActions.push({
+				...action,
+				stepId
+			});
+			lastCommandPushCount = 0;
+		},
+		onAbAction,
+		beforeAbCommand
+	});
 	const { isError, errorDetail } = await invokeClaudeStreaming({
 		prompt,
 		systemPrompt,
-		...agentBrowserInvokeBase({
-			sessionName,
-			runId: sessionName
-		}),
+		...invokeBase,
+		allowedTools: [...invokeBase.allowedTools, ...traceTools.allowedTools],
+		mcpServers: { [TRACE_TOOLS_SERVER]: traceTools.server },
 		model,
 		envScrubMap,
-		onAbAction: ({ abAction, stepId, assertMarker, secret }) => {
-			const stepForCommand = stepTracker.fromCommand(stepId);
-			const line = abAction === void 0 ? null : scrubEnvValues(abAction, envScrubMap);
-			let recorded = null;
-			if (assertMarker !== void 0) {
-				recorded = promoteMarkedAssert(line, scrubEnvValues(assertMarker, envScrubMap));
-				if (recorded === null) warn(`CCQA_ASSERT=${assertMarker} does not match a promotable command (wait --text / get count / url_contains:<substring>) — recording the command without an assert`);
-			}
-			if (recorded === null) {
-				const parsed = line === null ? null : parseAbActionLine(line);
-				recorded = parsed === null ? [] : [parsed];
-			}
-			let pushed = 0;
-			for (const action of recorded) {
-				const stamped = withStepId(action, stepForCommand);
-				if (stamped) {
-					traceActions.push(secret ? {
-						...stamped,
-						secret: true
-					} : stamped);
-					pushed += 1;
-				}
-			}
-			lastCommandPushCount = pushed;
-		},
+		onAbAction,
+		beforeAbCommand,
+		effort: "low",
+		bashGuard: traceBashGuard,
 		onAbActionFailed: () => {
 			if (lastCommandPushCount > 0) traceActions.splice(-lastCommandPushCount);
 			lastCommandPushCount = 0;
@@ -25786,10 +26167,10 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	});
 	const overallStatus = failureReason === null ? "passed" : "failed";
 	const dedupedActions = dedupAndReport(scrubAndReport(traceActions));
+	const validationStart = Date.now();
 	const validatedActions = overallStatus === "passed" || opts.validateFailedTrace === true ? validateAndReport(dedupedActions, validationMode, { CCQA_RUN_ID: sessionName }, opts.teardown) : dedupedActions;
+	if (validatedActions !== dedupedActions) meta("validation time", `${((Date.now() - validationStart) / 1e3).toFixed(1)}s`);
 	opts.teardown?.closeTracked(sessionName) ?? closeSession(sessionName);
-	const caseRef = testCase.ref;
-	const previous = overallStatus === "passed" ? await tryGetRecording(caseRef) : null;
 	let recordingPath;
 	const cleanupIds = new Set(testCase.cleanup.map((s) => s.id));
 	const routeActions = validatedActions.filter((a) => !cleanupIds.has(a.stepId ?? ""));
@@ -25828,7 +26209,10 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 */
 function traceFailureReason(lines, session) {
 	const assertionFailed = lines.find((l) => l.type === "ASSERTION_FAILED");
-	if (assertionFailed) return `${assertionFailed.stepId || "(unnamed step)"} reported ASSERTION_FAILED`;
+	if (assertionFailed) {
+		const detail = assertionFailed.detail.trim();
+		return `${assertionFailed.stepId || "(unnamed step)"} reported ASSERTION_FAILED${detail ? `: ${detail}` : ""}`;
+	}
 	if (session.isError) return `the Claude session ended in an error: ${session.errorDetail ?? "no detail reported"}`;
 	const completed = lines.filter((l) => l.type === "RUN_COMPLETED").at(-1);
 	if (completed === void 0) return "the session ended without a RUN_COMPLETED line — the model stopped before it reported an outcome";
@@ -26481,6 +26865,7 @@ async function runGenerateLocked(resolved, opts, cwd) {
 		cleanup: testCase.cleanup,
 		expectations: testCase.expectations,
 		cleanupExpectations: testCase.cleanupExpectations,
+		...testCase.context.length > 0 ? { context: testCase.context } : {},
 		fields: testCase.fields,
 		cwd,
 		testPath,
@@ -26655,7 +27040,7 @@ const VALIDATION_MODES = ["lenient", "strict"];
 const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<case>", "The case to record: a spec id ('<feature>/<spec>'), or — for a target with a `cases` module — a case id or the path of its source file").description("Record a test from a case: run agent-browser to collect actions (trace), then compile them into runnable code via the case's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for playwright and for a target the project defines. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--instruction <text>", "Extra guidance for the recording agent — e.g. the drift audit's finding when re-recording a drifted spec.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
-}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--timeout <seconds>", "Abort the recording after this many seconds, wherever it is (trace, generate, auto-fix): reap the browser session, seal the open hub run (--report-to-hub) with a 'timed out' note, and exit 124. Prefer this over wrapping the command in an external `timeout`, whose SIGTERM may never reach this process.", parseTimeoutSeconds).option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--timeout <seconds>", "Abort the recording after this many seconds, wherever it is (trace, generate, auto-fix): reap the browser session, seal the open hub run (--report-to-hub) with a 'timed out' note, and exit 124. Prefer this over wrapping the command in an external `timeout`, whose SIGTERM may never reach this process.", parseTimeoutSeconds).option("--fresh-ir", "Record from scratch. By default an existing ir.json is shown to the recorder as a map of the route, so steps that still work are not rediscovered.").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("record", () => runRecord(specPath, opts));
 }));
 async function runRecord(caseArgument, opts) {
@@ -26767,6 +27152,7 @@ async function runRecord(caseArgument, opts) {
 				...config.sessionState ? { sessionState: config.sessionState } : {},
 				...resolved.targetConfig.conventions.operate.length > 0 ? { conventions: resolved.targetConfig.conventions.operate } : {},
 				...opts.instruction ? { instruction: opts.instruction } : {},
+				...opts.freshIr ? { freshIr: true } : {},
 				onStep: (stepId) => {
 					tracingStep = stepId;
 				}