ccqa 1.59.0 → 1.60.1

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 {
@@ -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;
@@ -14836,6 +14885,12 @@ function tail(output) {
 	const trimmed = output.trim();
 	return trimmed.length <= OUTPUT_TAIL_CHARS ? trimmed : trimmed.slice(-OUTPUT_TAIL_CHARS);
 }
+const LOGGED_TAIL_LINES = 40;
+/** The end of an output tail that is already scrubbed, one log line per line. */
+function logOutputTail(scrubbed, write) {
+	if (scrubbed === "") return;
+	for (const line of scrubbed.split("\n").slice(-LOGGED_TAIL_LINES)) write(`  | ${line}`);
+}
 /**
 * Where new support files may be created.
 *
@@ -15027,16 +15082,19 @@ async function runVerificationLoop(p, state) {
 				failing = run;
 			}
 		}
+		const outputTail = scrubEnvValues(tail(failing.output), outputScrub);
 		if (attempt >= maxRetries) {
 			warn(`verification still failing after ${maxRetries} fix attempt(s) — generated files kept`);
+			logOutputTail(outputTail, warn);
 			await clearCaseRun(p.ctx.ref);
 			return finish(false);
 		}
 		fix(`verification failed (exit ${failing.exitCode}) — requesting a fix (${attempt + 1}/${maxRetries})`);
+		logOutputTail(outputTail, fix);
 		const fixPrompt = buildLlmFixPrompt({
 			targetId: p.target,
 			command: failing.command,
-			outputTail: scrubEnvValues(tail(failing.output), outputScrub),
+			outputTail,
 			files: [...state.entries()].map(([path, f]) => ({
 				path,
 				contents: f.contents,
@@ -25277,12 +25335,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) ?? [];
@@ -25294,9 +25351,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:
@@ -25310,19 +25367,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")}
 `;
@@ -25395,7 +25449,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
@@ -25532,6 +25586,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
 
@@ -25881,6 +25936,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. */
@@ -25926,10 +26014,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);
@@ -25970,7 +26060,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 }
@@ -26032,9 +26122,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,
@@ -26047,7 +26140,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(" + "));
@@ -26106,7 +26202,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,
@@ -26176,7 +26272,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);
@@ -29038,12 +29134,12 @@ function releaseAll(locks, holder) {
 }
 //#endregion
 //#region src/hub/core/audit-need.ts
-function auditNeed(drift, key, range) {
-	const entry = drift.specs[key];
+function auditNeed(drift, spec, range, deployTimes) {
+	const entry = drift.specs[spec.key];
 	if (!entry) return { because: "neverAudited" };
-	const since = freshness(entry.gitHead, key, range);
+	const since = freshness(entry.gitHead, spec.key, range);
 	switch (since.kind) {
-		case "current": return { because: "current" };
+		case "current": return specMovedSince(spec.changedAt, entry.gitHead, entry.at, deployTimes) ? { because: "deployReached" } : { because: "current" };
 		case "touched": return { because: "deployReached" };
 		case "unanswerable": return {
 			because: "cannotTell",
@@ -29052,13 +29148,52 @@ function auditNeed(drift, key, range) {
 		default: throw new Error(`unhandled freshness: ${String(since)}`);
 	}
 }
+/**
+* When each deployed commit reached the environment. A baseline read at that
+* commit cannot have seen anything committed after it was deployed.
+*/
+function deployedAt(log) {
+	const out = /* @__PURE__ */ new Map();
+	for (const entry of log.entries) out.set(entry.sha, entry.at);
+	return out;
+}
+/**
+* Has the spec moved since the baseline was taken?
+*
+* A verdict is a claim about a (spec, product) pair, so either side moving
+* invalidates it. The deploy log covers the product side; this covers the
+* other one. Without it a spec repaired and merged stays `needsRepair` until
+* a deploy happens to reach it, and a run that passed against the previous
+* spec keeps answering `verified` for the new one.
+*
+* Compared against when the baseline commit was *deployed*, not when the audit
+* or run happened: the tree read at that commit predates its deployment, so an
+* edit after it is definitely not in it. Falls back to the baseline's own
+* timestamp when the log cannot place the commit.
+*
+* One-directional. A later edit time proves the baseline is stale; an earlier
+* one proves nothing, and this answers false rather than guessing.
+*/
+function specMovedSince(changedAt, baselineSha, baselineAt, deployTimes) {
+	if (!changedAt) return null;
+	return isLater(changedAt, baselineSha && deployTimes.get(baselineSha) || baselineAt) ? changedAt : null;
+}
+/**
+* Compared as instants, never as strings: a spec's edit time carries its
+* committer's offset, and `+09:00` sorts after `Z` for an earlier moment.
+* An unparseable side answers false, the same as a missing one.
+*/
+function isLater(a, b) {
+	return Date.parse(a) > Date.parse(b);
+}
 /** True for every answer but `current`. */
 function needsAudit(need) {
 	return need.because !== "current";
 }
 function computeAuditNeed(input) {
 	const range = buildRange(input.log, input.touchIndex);
-	return Object.fromEntries(input.specs.map((spec) => [spec.key, heldBy(input.locks, spec.key, input.now) ? { because: "held" } : auditNeed(input.drift, spec.key, range)]));
+	const deployTimes = deployedAt(input.log);
+	return Object.fromEntries(input.specs.map((spec) => [spec.key, heldBy(input.locks, spec.key, input.now) ? { because: "held" } : auditNeed(input.drift, spec, range, deployTimes)]));
 }
 //#endregion
 //#region src/drift/audit-selection.ts
@@ -29620,7 +29755,8 @@ async function readChunk(cwd, paths, byRelPath, out) {
 	let when = "";
 	for (const line of stdout.split("\n")) {
 		if (line.startsWith("\0")) {
-			when = line.slice(1).trim();
+			const ms = Date.parse(line.slice(1).trim());
+			when = Number.isNaN(ms) ? "" : new Date(ms).toISOString();
 			continue;
 		}
 		const abs = byRelPath.get(line.trim());
@@ -32244,36 +32380,6 @@ function createGetCoverageEdgesHandler(config) {
 }
 //#endregion
 //#region src/hub/core/rerun.ts
-/**
-* When each deployed commit reached the environment. A baseline read at that
-* commit cannot have seen anything committed after it was deployed.
-*/
-function deployedAt(log) {
-	const out = /* @__PURE__ */ new Map();
-	for (const entry of log.entries) out.set(entry.sha, entry.at);
-	return out;
-}
-/**
-* Has the spec moved since the baseline was taken?
-*
-* A verdict is a claim about a (spec, product) pair, so either side moving
-* invalidates it. The deploy log covers the product side; this covers the
-* other one. Without it a spec repaired and merged stays `needsRepair` until
-* a deploy happens to reach it, and a run that passed against the previous
-* spec keeps answering `verified` for the new one.
-*
-* Compared against when the baseline commit was *deployed*, not when the audit
-* or run happened: the tree read at that commit predates its deployment, so an
-* edit after it is definitely not in it. Falls back to the baseline's own
-* timestamp when the log cannot place the commit.
-*
-* One-directional. A later edit time proves the baseline is stale; an earlier
-* one proves nothing, and this answers false rather than guessing.
-*/
-function specMovedSince(changedAt, baselineSha, baselineAt, deployTimes) {
-	if (!changedAt) return null;
-	return changedAt > (baselineSha && deployTimes.get(baselineSha) || baselineAt) ? changedAt : null;
-}
 function computeRerun(input) {
 	const { specs, ledger, log, touchIndex, drift, locks, attestations, dismissals, now } = input;
 	const range = buildRange(log, touchIndex);
@@ -32285,7 +32391,7 @@ function computeRerun(input) {
 			lastGreen: ledger.green[spec.key] ?? null,
 			lastRed: ledger.red[spec.key] ?? null
 		};
-		let audit = auditState(drift, spec.key, range);
+		let audit = auditState(drift, spec, range, deployTimes);
 		let execution = executionState(coords, (sha) => freshness(sha, spec.key, range));
 		const driftEntry = drift.specs[spec.key];
 		const dismissal = dismissals.specs[spec.key];
@@ -32293,7 +32399,6 @@ function computeRerun(input) {
 		if (dismissed) audit = { audit: "clean" };
 		const auditMoved = specMovedSince(spec.changedAt, driftEntry?.gitHead ?? null, driftEntry?.at ?? "", deployTimes);
 		const runMoved = specMovedSince(spec.changedAt, coords.lastRun?.deployedSha ?? null, coords.lastRun?.at ?? "", deployTimes);
-		if (auditMoved && audit.audit !== "due") audit = { audit: "due" };
 		if (runMoved && execution.execution === "passed") execution = { execution: "stale" };
 		const manualState = readAttestation(attestations.specs[spec.key], spec, coords, range, log, deployTimes);
 		const lapsedOverRed = manualState?.kind === "lapsed" && manualState.because !== "newerRed";
@@ -32338,7 +32443,7 @@ function computeRerun(input) {
 */
 function readAttestation(attest, spec, { lastRun, lastRed }, range, log, deployTimes) {
 	if (!attest) return null;
-	const newerRed = lastRed !== null && lastRed.at > attest.at;
+	const newerRed = lastRed !== null && isLater(lastRed.at, attest.at);
 	if (newerRed && lastRed.runId === lastRun?.runId) return {
 		kind: "lapsed",
 		attest,
@@ -32384,8 +32489,8 @@ function readAttestation(attest, spec, { lastRun, lastRed }, range, log, deployT
 * rule out is treated as having landed (ADR-0014). The hole is kept as an
 * annotation so the answer stays explicable.
 */
-function auditState(drift, key, range) {
-	const need = auditNeed(drift, key, range);
+function auditState(drift, spec, range, deployTimes) {
+	const need = auditNeed(drift, spec, range, deployTimes);
 	switch (need.because) {
 		case "neverAudited":
 		case "deployReached": return { audit: "due" };
@@ -32394,7 +32499,7 @@ function auditState(drift, key, range) {
 			...need.reason ? { auditAssumedReached: need.reason } : {}
 		};
 		case "current": {
-			const label = drift.specs[key].label;
+			const label = drift.specs[spec.key].label;
 			if (label === null) return { audit: "clean" };
 			if (label === "UNKNOWN") return { audit: "undecided" };
 			if (label === "PRODUCT_BUG" || label === "ENVIRONMENT") return { audit: "clean" };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.59.0",
+  "version": "1.60.1",
   "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.59.0",
+  "version": "1.60.1",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {