ccqa 1.60.0 → 1.60.2

package/dist/bin/ccqa.mjs

@@ -1612,13 +1612,14 @@ async function stampGeneratedTest(ref, testPathAbs) {
 	};
 	return writeRecording(ref, found.recording);
 }
-function buildRecording(actions, cleanup = []) {
+function buildRecording(actions, cleanup = [], stepDigests) {
 	const origin = actions.find((a) => a.action === "navigate")?.value;
 	return {
 		recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		...origin ? { origin } : {},
 		actions,
-		...cleanup.length > 0 ? { cleanup } : {}
+		...cleanup.length > 0 ? { cleanup } : {},
+		...stepDigests ? { stepDigests } : {}
 	};
 }
 /**
@@ -1634,9 +1635,9 @@ function parseRecording(content, path) {
 	return recording;
 }
 const LEGACY_RECORDING_FILES = ["actions.json", "route.md"];
-async function saveRecording(ref, actions, cleanup = []) {
+async function saveRecording(ref, actions, cleanup = [], stepDigests) {
 	await mkdir(ref.dir, { recursive: true });
-	const recording = buildRecording(actions, cleanup);
+	const recording = buildRecording(actions, cleanup, stepDigests);
 	const recordingPath = await writeRecording(ref, recording);
 	await Promise.all([...LEGACY_RECORDING_FILES, FAILED_RECORDING_FILE].map((f) => unlink(join(ref.dir, f)).catch(() => {})));
 	return {
@@ -1649,10 +1650,10 @@ async function saveRecording(ref, actions, cleanup = []) {
 *
 * One directory, not one per attempt: a project whose tests belong to its own
 * runner never calls `ccqa run`, so this stands in for the run report the
-* evidence table reads — and what stands in for it is the attempt that passed,
-* which there is only ever one of. `ccqa generate` clears it before each
-* attempt and removes it when none passed, because screenshots of a failing
-* run are a debugging aid and this table presents them as the case working.
+* evidence table reads — and what stands in for it is the attempt that passed
+* last, the version generation keeps. `ccqa generate` replaces it only on a
+* pass and removes it when none passed, because screenshots of a failing run
+* are a debugging aid and this table presents them as the case working.
 */
 function caseRunDir(ref) {
 	return join(ref.dir, EVIDENCE_DIR);
@@ -6313,6 +6314,54 @@ function subcommand(args) {
 */
 function spawnAB(args, opts) {
 	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	const result = spawnABRetrying(args, timeoutMs);
+	if (result.status === 0) return result;
+	const session = args[0] === "--session" ? args.slice(0, 2) : [];
+	return scrollCoveredIntoView(session, args.slice(session.length), result) ? spawnABRetrying(args, timeoutMs) : result;
+}
+const COVERED_PATTERN = /Element '(.+?)' is covered by /;
+/**
+* When agent-browser refused `command` because another element (a sticky
+* footer, a banner) covers the target's click point, scroll the target to the
+* centre and say whether the command is worth running again. The refusal comes
+* before any input is dispatched, so running it again cannot act twice.
+*/
+function scrollCoveredIntoView(session, command, failed) {
+	const covered = COVERED_PATTERN.exec(`${failed.stdout}\n${failed.stderr}`)?.[1];
+	if (covered === void 0) return false;
+	const scroll = command[0] === "find" ? scrollToFound(command, session) : ["scrollintoview", covered];
+	return scroll !== null && spawnABOnce([...session, ...scroll], PROCESS_HARD_TIMEOUT_MS).status === 0;
+}
+/** The `find` forms whose element can be addressed again; the rest stay refused. */
+function scrollToFound(find, session) {
+	const [, by = "", value = ""] = find;
+	switch (by) {
+		case "testid": return ["scrollintoview", `[data-testid=${JSON.stringify(value)}]`];
+		case "first": return scrollToNth(value, "0");
+		case "last": return scrollToNth(value, "els.length - 1");
+		case "nth": return scrollToNth(find[3] ?? "", String(Number(value)));
+		case "role": return scrollToRole(find, session);
+		default: return null;
+	}
+}
+function scrollToNth(css, index) {
+	return ["eval", `{ const els = document.querySelectorAll(${JSON.stringify(css)}); els[${index}]?.scrollIntoView({ block: "center" }); }`];
+}
+/** The snapshot's ref for the element `find role` matches: same role, name by `--exact` or case-insensitive substring. */
+function scrollToRole(find, session) {
+	const role = (find[2] ?? "").toLowerCase();
+	const flag = find.indexOf("--name");
+	const name = flag === -1 ? null : find[flag + 1] ?? "";
+	const named = (label) => name === null || (find.includes("--exact") ? label === name : label.toLowerCase().includes(name.toLowerCase()));
+	const snapshot = spawnABOnce([
+		...session,
+		"snapshot",
+		"-i"
+	], PROCESS_HARD_TIMEOUT_MS);
+	for (const [, r, label = "", ref] of snapshot.stdout.matchAll(/^\s*- (\S+)(?: "(.*)")?.*\bref=(e\d+)/gm)) if (r.toLowerCase() === role && named(label)) return ["scrollintoview", `@${ref}`];
+	return null;
+}
+function spawnABRetrying(args, timeoutMs) {
 	let result = spawnABOnce(args, timeoutMs);
 	let elapsed = 0;
 	let attempt = 0;
@@ -6486,7 +6535,7 @@ function parseStepComment(line) {
 * every step then reads as deciding nothing and every rewrite is rejected.
 */
 function stepLines(source) {
-	return source.replace(STEP_CALL, (call) => call.replace(/\s*\n\s*/g, " ")).split("\n");
+	return source.replace(STEP_CALL, (call) => "\n".repeat(call.split("\n").length - 1) + call.replace(/\s*\n\s*/g, " ")).split("\n");
 }
 /**
 * The step id a `test.step` title names — the block form only.
@@ -8289,6 +8338,31 @@ function exportedNames(source) {
 }
 //#endregion
 //#region src/targets/emitted-review.ts
+/**
+* A mechanical read of the code a generation just wrote, before it is called
+* done.
+*
+* The fix loop already runs the project's own test command and checks, so
+* what reaches review is code that compiles, lints and passes. None of that
+* answers whether it is code a reviewer would take: an assertion scoped to
+* nothing passes, a locator named for a row that matches page-wide text
+* passes, a test that checks five things the case never asked about passes.
+* Those are what this reads for, and its findings go back through the same
+* fix loop rather than to a human.
+*
+* Every rule here was calibrated against a large hand-written suite: a rule
+* that fires on code people wrote and reviewed is a rule that is wrong,
+* however reasonable it sounds. Two candidates died that way —
+* "a locator named `…Row` must use `getByRole("row")`" fired across a
+* sizable share of the hand-written page objects, because that suite names
+* elements for what they look like rather than for their ARIA role, and
+* "never `.first()` in an assertion" fired on deliberate uses that each
+* carried the comment their own guidelines ask for. A third died against
+* ccqa's own output: the step comment a generated test opens each step with
+* looked like narration, and is what the evidence table reads back to say
+* which assertion belongs to which step. Keep that bar for anything added
+* here.
+*/
 function reviewEmittedFiles(input) {
 	const locators = collectLocators(input.files);
 	const said = input.caseText.join("\n");
@@ -8297,7 +8371,7 @@ function reviewEmittedFiles(input) {
 		...containerOfPageText(file, source),
 		...unjustifiedFirst(file, source),
 		...describeEcho(file, source),
-		...unaskedAssertions(file, source, locators, said),
+		...unaskedAssertions(file, source, locators, said, input.blockSteps),
 		...weakerTwin(file, source),
 		...unreached(file, source, input)
 	])];
@@ -8552,9 +8626,26 @@ function assertedStrings(text, locators) {
 * precondition broke rather than four steps later, is worth doing and is
 * written down when it is.
 */
-function unaskedAssertions(file, source, locators, said) {
+function unaskedAssertions(file, source, locators, said, blockSteps = /* @__PURE__ */ new Set()) {
 	const all = lines(source);
+	const boundaries = stepLines(source);
+	let step = null;
+	let depth = null;
 	return all.flatMap((text, i) => {
+		const opened = parseStepComment(boundaries[i] ?? "");
+		if (opened !== null) {
+			step = opened;
+			depth = boundaries[i].includes("test.step(") ? 0 : null;
+		}
+		if (depth !== null) {
+			const before = depth;
+			depth += (text.match(/\{/g)?.length ?? 0) - (text.match(/\}/g)?.length ?? 0);
+			if (before > 0 && depth <= 0) {
+				step = null;
+				depth = null;
+			}
+		}
+		if (step !== null && blockSteps.has(step)) return [];
 		if (!/\bexpect(?:\.soft)?\(/.test(text)) return [];
 		const strings = assertedStrings(text, locators);
 		if (strings.length === 0 || strings.some((s) => said.includes(s))) return [];
@@ -14964,12 +15055,14 @@ async function finalizeAndVerify(p) {
 		review
 	};
 }
+const FINDINGS_LEFT_OPEN = "generated with review findings still open — the files are kept and the findings are recorded against the case, but nothing acted on them";
 /**
 * The runCommand verification loop. One round asks the project's own commands,
-* then the review, then the run — and a round is over when all three are
-* clean. On anything else the output goes to Claude for a corrected set and
+* then the review and the run together — and a round is over when all three
+* are clean. On anything else the output goes to Claude for a corrected set and
 * the next round asks all three again: a fix written for a failing run can
-* break a rule the round before it cleared.
+* break a rule the round before it cleared, and one written for a finding can
+* break the run.
 *
 * `fix.mode` mirrors the agent-browser target's fix UX (which only ever
 * prompts inside its own fix loop, never for the first write):
@@ -14981,8 +15074,9 @@ async function finalizeAndVerify(p) {
 *     verify decides pass/fail.
 *
 * Exhaustion (or a declined / skipped fix) keeps the files on disk and reports
-* `passed: false`. Targets without a runCommand are generate-only here and
-* pass trivially.
+* `passed: false` — unless an earlier round's files passed their run: those
+* are put back and the generate passes with the findings open. Targets without
+* a runCommand are generate-only here and pass trivially.
 */
 async function runVerificationLoop(p, state) {
 	const runCommand = p.ctx.targetConfig.runCommand;
@@ -15012,33 +15106,61 @@ async function runVerificationLoop(p, state) {
 	const askReviewer = maxRetries > 0;
 	let reviewerGone = false;
 	if (!askReviewer && p.reading) info("no fix round could act on a review — the reviewer is not asked; the mechanical read still runs");
+	let passing = null;
+	const original = /* @__PURE__ */ new Map();
+	const settle = async (attempt) => {
+		if (passing === null) {
+			await clearCaseRun(p.ctx.ref);
+			return finish(false);
+		}
+		if (passing.attempt !== attempt) {
+			await restoreFiles(state, passing.files, original);
+			review = passing.review;
+			warn("the final round did not pass — restored the files of the last round that did");
+		}
+		warn(FINDINGS_LEFT_OPEN);
+		return finish(true);
+	};
+	if (captures) await clearCaseRun(p.ctx.ref);
 	for (let attempt = 0;; attempt++) {
 		let failing = await runCheckCommands(p.ctx);
 		let asked = [];
 		if (failing === null) {
 			await refreshFromDisk(state);
-			const [reading, mechanical] = await Promise.all([readingOfEmitted(p, state, askReviewer && !reviewerGone), reviewOfEmitted(p.ctx, state, p.writeRoots)]);
+			const questions = [
+				readingOfEmitted(p, state, askReviewer && !reviewerGone),
+				reviewOfEmitted(p.ctx, state, p.writeRoots),
+				verifyRun(p, state, runCommand, attempt, captures)
+			];
+			const [reading, mechanical, run] = await Promise.all(questions).catch(async (err) => {
+				await Promise.allSettled(questions);
+				await clearCaseRun(p.ctx.ref);
+				throw err;
+			});
 			review = reading;
-			if (review?.reviewerFailed) reviewerGone = true;
-			const unchecked = uncheckedSteps(review, spent);
-			const violations = guideViolations(review, spent);
+			if (run.exitCode === 0) passing = {
+				files: new Map(state),
+				review,
+				attempt
+			};
+			const heard = review?.reviewerFailed ? void 0 : review;
+			if (review && !heard) reviewerGone = true;
+			const unchecked = uncheckedSteps(heard, spent);
+			const violations = guideViolations(heard, spent);
 			const reads = allReadings(mechanical, unchecked, violations);
-			if (reads !== null && attempt < maxRetries) {
-				asked = [...unchecked?.asked ?? [], ...violations?.asked ?? []];
-				failing = reads;
-			} else {
-				if (reads !== null) warn("generated with review findings still open — the files are kept and the findings are recorded against the case, but nothing acted on them");
-				const run = await verifyRun(p, state, runCommand, attempt, captures);
-				if (run.exitCode === 0) return finish(true);
-				failing = run;
+			asked = [...unchecked?.asked ?? [], ...violations?.asked ?? []];
+			if (run.exitCode !== 0) failing = reads === null ? run : allReadings(run, reads) ?? run;
+			else if (reads !== null && attempt < maxRetries) failing = reads;
+			else {
+				if (reads !== null) warn(FINDINGS_LEFT_OPEN);
+				return finish(true);
 			}
 		}
 		const outputTail = scrubEnvValues(tail(failing.output), outputScrub);
 		if (attempt >= maxRetries) {
-			warn(`verification still failing after ${maxRetries} fix attempt(s) — generated files kept`);
+			warn(`verification still failing after ${maxRetries} fix attempt(s)`);
 			logOutputTail(outputTail, warn);
-			await clearCaseRun(p.ctx.ref);
-			return finish(false);
+			return settle(attempt);
 		}
 		fix(`verification failed (exit ${failing.exitCode}) — requesting a fix (${attempt + 1}/${maxRetries})`);
 		logOutputTail(outputTail, fix);
@@ -15076,9 +15198,12 @@ async function runVerificationLoop(p, state) {
 			continue;
 		}
 		if (p.ctx.fix.mode === "interactive" && !await confirmFixWrite(output.files, p.ctx.cwd)) {
-			info("fix not applied (declined) — keeping current files");
-			await clearCaseRun(p.ctx.ref);
-			return finish(false);
+			info("fix not applied (declined)");
+			return settle(attempt);
+		}
+		for (const f of output.files) {
+			const rel = relative(p.ctx.cwd, resolve(p.ctx.cwd, f.path));
+			if (!state.has(rel) && !original.has(rel)) original.set(rel, await readFile(resolve(p.ctx.cwd, f.path), "utf8").catch(() => null));
 		}
 		await writeGeneratedFiles(p.ctx.cwd, output.files, state);
 		review = void 0;
@@ -15086,17 +15211,12 @@ async function runVerificationLoop(p, state) {
 }
 /**
 * One verification run of the files as they are now, in the shape the fix loop
-* consumes. The round's last question and its most expensive: it is asked only
-* of files the project's own commands and the review have already cleared.
+* consumes. Asked only of files the project's own commands have cleared.
 */
 async function verifyRun(p, state, runCommand, attempt, captures) {
 	const testFiles = [...state.entries()].filter(([, f]) => f.kind === "test").map(([rel]) => rel);
 	const artifactsDir = await mkdtemp(join(tmpdir(), "ccqa-verify-artifacts-"));
-	const evidenceDir = captures ? caseRunDir(p.ctx.ref) : null;
-	if (evidenceDir) {
-		await clearCaseRun(p.ctx.ref);
-		await mkdir(evidenceDir, { recursive: true });
-	}
+	const evidenceDir = captures ? await mkdtemp(join(tmpdir(), "ccqa-verify-evidence-")) : null;
 	let command = substituteArtifactsDir(substituteRunCommandFiles(runCommand, testFiles), artifactsDir);
 	let traceUnavailable;
 	if (evidenceDir) {
@@ -15120,6 +15240,8 @@ async function verifyRun(p, state, runCommand, attempt, captures) {
 				warn: (message) => warn(`${p.ctx.ref.id}: ${message}`)
 			});
 			if (unavailable) warn(unavailable);
+			await clearCaseRun(p.ctx.ref);
+			await cp(evidenceDir, caseRunDir(p.ctx.ref), { recursive: true });
 		}
 		return {
 			...result,
@@ -15130,6 +15252,10 @@ async function verifyRun(p, state, runCommand, attempt, captures) {
 			recursive: true,
 			force: true
 		});
+		if (evidenceDir) await rm(evidenceDir, {
+			recursive: true,
+			force: true
+		});
 	}
 }
 /**
@@ -15150,6 +15276,10 @@ async function runCheckCommands(ctx) {
 	}
 	return null;
 }
+function blockStepIds(ctx) {
+	const included = new Set(collectIncludedBlockNames(ctx.spec));
+	return new Set(ctx.steps.filter((s) => included.has(s.source)).map((s) => s.id));
+}
 /**
 * The mechanical read of what this attempt wrote, shaped like a failed check
 * so the fix loop carries it the same way.
@@ -15167,6 +15297,7 @@ async function reviewOfEmitted(ctx, state, writeRoots) {
 			...ctx.expectations,
 			...ctx.cleanupExpectations
 		],
+		blockSteps: blockStepIds(ctx),
 		testPath: ctx.testPath
 	});
 	if (findings.length === 0) return null;
@@ -15212,6 +15343,23 @@ async function refreshFromDisk(state) {
 	}
 }
 /**
+* Put the files back as `to` holds them. A path written after `to` was taken
+* goes back to what it held before the loop wrote it, or away if it was new.
+*/
+async function restoreFiles(state, to, original) {
+	for (const [rel, f] of state) {
+		if (to.has(rel)) continue;
+		const was = original.get(rel) ?? null;
+		if (was === null) await rm(f.abs, { force: true });
+		else await writeFile(f.abs, was, "utf8");
+	}
+	state.clear();
+	for (const [rel, f] of to) {
+		await writeFile(f.abs, f.contents, "utf8");
+		state.set(rel, f);
+	}
+}
+/**
 * The reading's findings, shaped like a failed check so the fix loop carries
 * them the same way — or null when there is nothing to act on.
 *
@@ -15224,9 +15372,8 @@ async function refreshFromDisk(state) {
 *
 * What the round asks for is verified like any other rewrite, and that can
 * end red: an assertion strengthened to check what the case claims may simply
-* not hold. The generate then reports failed — on the test run, not on this —
-* and the files are kept. That is the honest outcome, and the alternative
-* (restoring what passed weakly) would hide a case the product does not meet.
+* not hold. The loop then goes back to the last version that passed, and the
+* finding stays open on the record rather than hidden.
 *
 * A review that could not be obtained is not acted on either: spending a round
 * answering a question nobody asked is worse than leaving it unanswered. Nor
@@ -15372,7 +15519,7 @@ function allReadings(...reports) {
 	const found = reports.filter((r) => r !== null);
 	if (found.length === 0) return null;
 	return {
-		exitCode: 1,
+		exitCode: found[0].exitCode,
 		command: found.map((r) => r.command).join(" + "),
 		output: found.map((r) => `${r.command}\n\n${r.output}`).join("\n\n")
 	};
@@ -25286,12 +25433,11 @@ function isPassiveAction(action) {
 * 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 renderPreviousRecording(actions, sessionName, currentStepIds) {
-	const current = new Set([SETUP_STEP_ID, ...currentStepIds]);
+function renderPreviousRecording(actions, sessionName, replayable) {
 	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;
+		if (action.stepId === void 0 || !replayable.has(action.stepId)) continue;
 		const command = previousCommand(action, sessionName, action.stepId === brokenStep);
 		if (command === null) continue;
 		const lines = byStep.get(action.stepId) ?? [];
@@ -25303,9 +25449,9 @@ function renderPreviousRecording(actions, sessionName, currentStepIds) {
 ## 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.**
+as the commands that perform it, for the steps whose text has not changed since.
+The application may have moved since: **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:
@@ -25319,19 +25465,16 @@ Execution Workflow:
 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
+   recorded. The next step goes back to \`replay_step\`.
+4. A step you finish 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.
+   \`Expected\` says now.
 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.
+A step with no section here — new, or edited since that recording — is
+recorded the usual way.
 
 ${[...byStep].map(([stepId, lines]) => `### ${stepId}\n\n\`\`\`bash\n${lines.join("\n")}\n\`\`\``).join("\n\n")}
 `;
@@ -25404,7 +25547,7 @@ ${input.instruction}
 	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));
+	const previousText = input.previousRecording ? renderPreviousRecording(input.previousRecording.actions, sessionName, input.previousRecording.replayable) : "";
 	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
@@ -25541,6 +25684,7 @@ find nth <index> "<ALLOWED-css>" <action>
 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).
+9. **A click refused with \`is covered by\`** (a sticky footer or banner over the element) is not a product bug: \`run_commands\` scrolls the element to the centre and clicks again, so send it there.
 
 ### Special input types
 
@@ -25890,6 +26034,39 @@ ${conventions.map((c) => `### ${c.heading}\n\n${c.body}`).join("\n\n")}
 `;
 }
 //#endregion
+//#region src/ir/step-digests.ts
+/**
+* What each step was asked to do when it was recorded, by step id. Case-level
+* checks land on whichever step the recorder chose, so they are part of every
+* step's; setup has no text of its own and stands for the case's context.
+*/
+function stepDigests(testCase) {
+	return {
+		[SETUP_STEP_ID]: digest(testCase.context),
+		...Object.fromEntries(testCase.steps.filter(isExpandedActionStep).map((s) => [s.id, digest([
+			s.instruction,
+			s.expected,
+			testCase.expectations
+		])])),
+		...Object.fromEntries(testCase.cleanup.map((s) => [s.id, digest([
+			s.instruction,
+			s.expected,
+			testCase.cleanupExpectations
+		])]))
+	};
+}
+/**
+* The steps whose previous commands may be replayed: those still asked to do
+* what they were then. An edited, added or renumbered step, or any step of a
+* recording without digests, would replay what the old step asked.
+*/
+function unchangedSteps(previous, current) {
+	return new Set(Object.keys(current).filter((id) => previous?.[id] !== void 0 && previous[id] === current[id]));
+}
+function digest(value) {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}
+//#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. */
@@ -25935,10 +26112,12 @@ async function runCommands(commands, input) {
 		const checkpoint = input.beforeAbCommand(extractCcqaStepFromBashCommand(cmd) ?? void 0);
 		if (checkpoint) return stop(checkpoint);
 		info(`$ ${scrubEnvValues(cmd, input.envScrubMap)}`);
-		const result = await runShell(cmd, {
+		const env = {
 			...process.env,
 			...input.env
-		});
+		};
+		let result = await runShell(cmd, env);
+		if (result.status !== 0 && scrollCoveredIntoView(["--session", input.sessionName], abPositionalTokens(cmd), result)) result = await runShell(cmd, 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);
@@ -25979,7 +26158,7 @@ function cap(out) {
 }
 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.`;
+	if (actions.length === 0) return `No previous commands for ${step}: it is new or its text changed since the last recording. 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 }
@@ -26041,9 +26220,12 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	for (const w of conventions.warnings) warn(w);
 	const caseRef = testCase.ref;
 	const previous = await tryGetRecording(caseRef);
+	const digests = stepDigests(testCase);
+	const replayable = unchangedSteps(previous?.stepDigests, digests);
 	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 replayableActions = previousActions.filter((a) => a.stepId !== void 0 && replayable.has(a.stepId));
+	if (previous) meta("previous", opts.freshIr ? "ignored (--fresh-ir)" : previous.stepDigests ? `${[...replayable].filter((id) => id !== SETUP_STEP_ID).length} unchanged step(s) offered as a map` : "not offered (recorded before step digests)");
+	const offersMap = !opts.freshIr && replayableActions.length > 0;
 	const baseSystemPrompt = buildTraceSystemPrompt({
 		title: testCase.title,
 		steps,
@@ -26056,7 +26238,10 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		...testCase.cleanupExpectations.length > 0 ? { cleanupExpectations: testCase.cleanupExpectations } : {},
 		...testCase.context.length > 0 ? { context: testCase.context } : {},
 		...opts.instruction ? { instruction: opts.instruction } : {},
-		...offersMap ? { previousRecording: previousActions } : {}
+		...offersMap ? { previousRecording: {
+			actions: previousActions,
+			replayable
+		} } : {}
 	});
 	const promptBundle = await loadPromptBundle(opts.hubContext ?? null, "record", opts.cwd ?? process.cwd());
 	if (promptBundle !== null) meta("prompt", promptBundle.loaded.join(" + "));
@@ -26115,7 +26300,7 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		runId: sessionName
 	});
 	const traceTools = buildTraceTools({
-		previous: offersMap ? previousActions : [],
+		previous: offersMap ? replayableActions : [],
 		sessionName,
 		env: invokeBase.env ?? {},
 		envScrubMap,
@@ -26185,7 +26370,7 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	const routeActions = validatedActions.filter((a) => !cleanupIds.has(a.stepId ?? ""));
 	const cleanupActions = validatedActions.filter((a) => cleanupIds.has(a.stepId ?? ""));
 	if (overallStatus === "passed") {
-		const saved = await saveRecording(caseRef, routeActions, cleanupActions);
+		const saved = await saveRecording(caseRef, routeActions, cleanupActions, digests);
 		recordingPath = saved.path;
 		if (previous) await reportRouteDiff(caseRef, previous, saved.recording, steps);
 		else await removeRouteDiff(caseRef);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.60.0",
+  "version": "1.60.2",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/dist/runtime/test-helpers.cjs

@@ -118,6 +118,54 @@ function subcommand(args) {
 */
 function spawnAB(args, opts) {
 	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	const result = spawnABRetrying(args, timeoutMs);
+	if (result.status === 0) return result;
+	const session = args[0] === "--session" ? args.slice(0, 2) : [];
+	return scrollCoveredIntoView(session, args.slice(session.length), result) ? spawnABRetrying(args, timeoutMs) : result;
+}
+const COVERED_PATTERN = /Element '(.+?)' is covered by /;
+/**
+* When agent-browser refused `command` because another element (a sticky
+* footer, a banner) covers the target's click point, scroll the target to the
+* centre and say whether the command is worth running again. The refusal comes
+* before any input is dispatched, so running it again cannot act twice.
+*/
+function scrollCoveredIntoView(session, command, failed) {
+	const covered = COVERED_PATTERN.exec(`${failed.stdout}\n${failed.stderr}`)?.[1];
+	if (covered === void 0) return false;
+	const scroll = command[0] === "find" ? scrollToFound(command, session) : ["scrollintoview", covered];
+	return scroll !== null && spawnABOnce([...session, ...scroll], PROCESS_HARD_TIMEOUT_MS).status === 0;
+}
+/** The `find` forms whose element can be addressed again; the rest stay refused. */
+function scrollToFound(find, session) {
+	const [, by = "", value = ""] = find;
+	switch (by) {
+		case "testid": return ["scrollintoview", `[data-testid=${JSON.stringify(value)}]`];
+		case "first": return scrollToNth(value, "0");
+		case "last": return scrollToNth(value, "els.length - 1");
+		case "nth": return scrollToNth(find[3] ?? "", String(Number(value)));
+		case "role": return scrollToRole(find, session);
+		default: return null;
+	}
+}
+function scrollToNth(css, index) {
+	return ["eval", `{ const els = document.querySelectorAll(${JSON.stringify(css)}); els[${index}]?.scrollIntoView({ block: "center" }); }`];
+}
+/** The snapshot's ref for the element `find role` matches: same role, name by `--exact` or case-insensitive substring. */
+function scrollToRole(find, session) {
+	const role = (find[2] ?? "").toLowerCase();
+	const flag = find.indexOf("--name");
+	const name = flag === -1 ? null : find[flag + 1] ?? "";
+	const named = (label) => name === null || (find.includes("--exact") ? label === name : label.toLowerCase().includes(name.toLowerCase()));
+	const snapshot = spawnABOnce([
+		...session,
+		"snapshot",
+		"-i"
+	], PROCESS_HARD_TIMEOUT_MS);
+	for (const [, r, label = "", ref] of snapshot.stdout.matchAll(/^\s*- (\S+)(?: "(.*)")?.*\bref=(e\d+)/gm)) if (r.toLowerCase() === role && named(label)) return ["scrollintoview", `@${ref}`];
+	return null;
+}
+function spawnABRetrying(args, timeoutMs) {
 	let result = spawnABOnce(args, timeoutMs);
 	let elapsed = 0;
 	let attempt = 0;

package/dist/runtime/test-helpers.mjs

@@ -118,6 +118,54 @@ function subcommand(args) {
 */
 function spawnAB(args, opts) {
 	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	const result = spawnABRetrying(args, timeoutMs);
+	if (result.status === 0) return result;
+	const session = args[0] === "--session" ? args.slice(0, 2) : [];
+	return scrollCoveredIntoView(session, args.slice(session.length), result) ? spawnABRetrying(args, timeoutMs) : result;
+}
+const COVERED_PATTERN = /Element '(.+?)' is covered by /;
+/**
+* When agent-browser refused `command` because another element (a sticky
+* footer, a banner) covers the target's click point, scroll the target to the
+* centre and say whether the command is worth running again. The refusal comes
+* before any input is dispatched, so running it again cannot act twice.
+*/
+function scrollCoveredIntoView(session, command, failed) {
+	const covered = COVERED_PATTERN.exec(`${failed.stdout}\n${failed.stderr}`)?.[1];
+	if (covered === void 0) return false;
+	const scroll = command[0] === "find" ? scrollToFound(command, session) : ["scrollintoview", covered];
+	return scroll !== null && spawnABOnce([...session, ...scroll], PROCESS_HARD_TIMEOUT_MS).status === 0;
+}
+/** The `find` forms whose element can be addressed again; the rest stay refused. */
+function scrollToFound(find, session) {
+	const [, by = "", value = ""] = find;
+	switch (by) {
+		case "testid": return ["scrollintoview", `[data-testid=${JSON.stringify(value)}]`];
+		case "first": return scrollToNth(value, "0");
+		case "last": return scrollToNth(value, "els.length - 1");
+		case "nth": return scrollToNth(find[3] ?? "", String(Number(value)));
+		case "role": return scrollToRole(find, session);
+		default: return null;
+	}
+}
+function scrollToNth(css, index) {
+	return ["eval", `{ const els = document.querySelectorAll(${JSON.stringify(css)}); els[${index}]?.scrollIntoView({ block: "center" }); }`];
+}
+/** The snapshot's ref for the element `find role` matches: same role, name by `--exact` or case-insensitive substring. */
+function scrollToRole(find, session) {
+	const role = (find[2] ?? "").toLowerCase();
+	const flag = find.indexOf("--name");
+	const name = flag === -1 ? null : find[flag + 1] ?? "";
+	const named = (label) => name === null || (find.includes("--exact") ? label === name : label.toLowerCase().includes(name.toLowerCase()));
+	const snapshot = spawnABOnce([
+		...session,
+		"snapshot",
+		"-i"
+	], PROCESS_HARD_TIMEOUT_MS);
+	for (const [, r, label = "", ref] of snapshot.stdout.matchAll(/^\s*- (\S+)(?: "(.*)")?.*\bref=(e\d+)/gm)) if (r.toLowerCase() === role && named(label)) return ["scrollintoview", `@${ref}`];
+	return null;
+}
+function spawnABRetrying(args, timeoutMs) {
 	let result = spawnABOnce(args, timeoutMs);
 	let elapsed = 0;
 	let attempt = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.60.0",
+  "version": "1.60.2",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {