ccqa 1.1.1 → 1.2.1

package/dist/bin/ccqa.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { n as spawnAB, t as sleepSync } from "../spawn-ab-Cr967J2N.mjs";
+import { a as formatAgentBrowserUnavailableMessage, i as assertAgentBrowserAvailable, n as spawnAB, o as pathWithAgentBrowserShim, r as AgentBrowserUnavailableError, s as resolveAgentBrowserBin$1, t as sleepSync } from "../spawn-ab-B9Il2TMd.mjs";
 import { HubApiError, createHubClient } from "../hub-client/index.mjs";
 import { createRequire } from "node:module";
 import { Command } from "commander";
-import { accessSync, createWriteStream, existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { accessSync, createWriteStream, existsSync, readFileSync, rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { access, chmod, cp, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { basename, delimiter, dirname, isAbsolute, join, normalize, posix, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize, posix, relative, resolve, sep } from "node:path";
 import { parse, stringify } from "yaml";
 import { ZodError, z } from "zod";
 import { execFile, spawn, spawnSync } from "node:child_process";
@@ -429,26 +429,6 @@ async function removeLegacyPerspectivesFiles(cwd) {
 	for (const path of candidates) if (await unlink(path).then(() => true).catch(() => false)) removed.push(path);
 	return removed;
 }
-/**
-* Replace (or insert) the `relatedPaths` key in the spec. Preserves every
-* other top-level field and the entire steps array. Returns the absolute
-* path that was written, or null if the spec file does not exist.
-*/
-async function updateSpecRelatedPaths(featureName, specName, relatedPaths, cwd) {
-	const specPath = join(getSpecDir(featureName, specName, cwd), SPEC_FILE);
-	const existing = await readFile(specPath, "utf-8").catch(() => null);
-	if (existing === null) return null;
-	await writeFile(specPath, stringify(stripUndefined({
-		...parseTestSpec(existing, specPath),
-		relatedPaths: relatedPaths.length > 0 ? relatedPaths : void 0
-	}), { lineWidth: 0 }), "utf-8");
-	return specPath;
-}
-function stripUndefined(obj) {
-	const out = {};
-	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
-	return out;
-}
 const LEGACY_RECORDING_FILES = ["actions.json", "route.md"];
 async function saveRecording(featureName, specName, actions, cwd) {
 	const specDir = getSpecDir(featureName, specName, cwd);
@@ -699,10 +679,10 @@ function bundledVitestConfigPath() {
 }
 //#endregion
 //#region src/runtime/spawn-vitest.ts
-const require$2 = createRequire(import.meta.url);
+const require$1 = createRequire(import.meta.url);
 function resolveVitestBin() {
-	const pkgPath = require$2.resolve("vitest/package.json");
-	const pkg = require$2(pkgPath);
+	const pkgPath = require$1.resolve("vitest/package.json");
+	const pkg = require$1(pkgPath);
 	const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vitest;
 	if (!binRel) throw new Error(`vitest package.json has no bin entry (resolved at ${pkgPath})`);
 	return resolve(dirname(pkgPath), binRel);
@@ -1891,7 +1871,7 @@ ${formatBlockList(blocks)}
 
 1. Read the codebase under cwd to find concrete strings: routes, button labels, aria-labels, page titles, placeholders. Use those exact strings in \`expected\`.
 2. If you use \`include:\` steps, verify each \`params\` key matches a declared param of the block (see the Available blocks list above).
-3. Populate \`relatedPaths\` with **provisional** glob patterns pointing at the source files this spec touches: the route/page file for each URL the spec visits, plus the component files (or their parent feature directory) that render the aria-labels, placeholders, or visible texts the spec asserts on. Prefer directory globs (e.g. \`src/features/tasks/**\`) when several files in one area are involved. Be conservative — include a path if you're unsure rather than omit it. \`ccqa trace\` will refine this list later from real browser observations.
+3. Populate \`relatedPaths\` with glob patterns pointing at the source files this spec depends on — this is the spec's final, authoritative list (nothing else updates it later, so get it right here): the route/page file for each URL the spec visits, plus the component files (or their parent feature directory) that render the aria-labels, placeholders, or visible texts the spec asserts on. Prefer directory globs (e.g. \`src/features/tasks/**\`) when several files in one area are involved. Confirm each path actually exists via \`Glob\`/\`Read\` before listing it — never guess a path by convention. Be conservative — when unsure whether a real path is relevant, include it rather than omit it (a missing path means a code change silently escapes \`drift --changed\`).
 4. Validate the (current or proposed) spec on four axes — emit one issue per finding:
    - **assertable**: each \`expected\` can be verified against a string/URL/state that exists in code.
    - **blocks**: every \`include\` resolves to a real block; every \`params\` key is declared on that block; every required param is provided.
@@ -3951,104 +3931,6 @@ async function warnStaleBlockArtifacts() {
 	for (const p of stale) hint(`stale block artifact detected: ${p} — v0.4 no longer uses these; delete it manually.`);
 }
 //#endregion
-//#region src/runtime/agent-browser-bin.ts
-const require$1 = createRequire(import.meta.url);
-function hasAgentBrowserShim(dir) {
-	try {
-		statSync(join(dir, "agent-browser"));
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Walks up from `start` looking for a `node_modules/.bin/agent-browser` shim.
-* Returns the .bin directory containing the shim, or null if none is found.
-*/
-function findNodeModulesBin(start) {
-	let cur = start;
-	while (true) {
-		const candidate = join(cur, "node_modules", ".bin");
-		if (hasAgentBrowserShim(candidate)) return candidate;
-		const parent = dirname(cur);
-		if (parent === cur) return null;
-		cur = parent;
-	}
-}
-/**
-* Resolves the directory containing the `agent-browser` shim that npm/pnpm
-* exposes on PATH for the peer-installed package. Used by `ccqa trace` to
-* prepend this directory to PATH so the Claude subprocess can invoke
-* `agent-browser ...` without requiring a global install.
-*
-* Returns null if agent-browser cannot be located.
-*/
-function resolveAgentBrowserBinDir() {
-	const fromCwd = findNodeModulesBin(process.cwd());
-	if (fromCwd) return fromCwd;
-	const fromSelf = findNodeModulesBin(dirname(require$1.resolve("agent-browser/package.json")));
-	if (fromSelf) return fromSelf;
-	try {
-		const candidate = join(dirname(require$1.resolve("agent-browser/package.json")), "node_modules", ".bin");
-		if (hasAgentBrowserShim(candidate)) return candidate;
-	} catch {}
-	return null;
-}
-/**
-* Returns a PATH string with the agent-browser shim directory prepended,
-* so `agent-browser ...` resolves without a global install. Falls back to
-* the original PATH when the package can't be resolved.
-*/
-function pathWithAgentBrowserShim(currentPath) {
-	const path = currentPath ?? "";
-	const dir = resolveAgentBrowserBinDir();
-	if (!dir) return path;
-	if (path.split(delimiter).includes(dir)) return path;
-	return dir + delimiter + path;
-}
-/**
-* Confirms before launching Claude that an `agent-browser` shim is reachable
-* via PATH. We do this up front so a missing peer dependency fails fast with
-* a clear message, instead of Claude burning tokens probing the system with
-* `which`, `find`, `npm install`, etc.
-*
-* The `resolver` argument is for tests; production calls take no args.
-*/
-function assertAgentBrowserAvailable(resolver = resolveAgentBrowserBinDir) {
-	const dir = resolver();
-	if (!dir) throw new AgentBrowserUnavailableError();
-	const shim = join(dir, "agent-browser");
-	try {
-		const s = statSync(shim);
-		if (!s.isFile() && !s.isSymbolicLink()) throw new AgentBrowserUnavailableError();
-	} catch {
-		throw new AgentBrowserUnavailableError();
-	}
-	return dir;
-}
-var AgentBrowserUnavailableError = class extends Error {
-	constructor() {
-		super("agent-browser binary not found on PATH");
-		this.name = "AgentBrowserUnavailableError";
-	}
-};
-/** Human-readable explanation shown to the user when the guard fires. */
-function formatAgentBrowserUnavailableMessage() {
-	return [
-		"agent-browser is not installed or not on PATH.",
-		"",
-		"ccqa drives the browser via the peer-installed `agent-browser` package.",
-		"Install it in this project:",
-		"",
-		"  pnpm add -D agent-browser",
-		"  # or",
-		"  npm install -D agent-browser",
-		"",
-		"If it is already installed, make sure you are running ccqa from the",
-		"project root (or via your package runner, e.g. `pnpm exec ccqa ...`)."
-	].join("\n");
-}
-//#endregion
 //#region src/cli/preflight.ts
 /**
 * Shared startup steps for every command that drives a real `agent-browser`
@@ -4327,6 +4209,14 @@ function readOctal(buf, offset, fieldLen) {
 /** Default per-profile sessions root, relative to the project (`--cwd`). */
 const SESSIONS_SUBDIR = ".ccqa/sessions";
 /**
+* Key under which `bootstrap` embeds the verify URL inside the uploaded
+* storage-state JSON. The hub roundtrips it opaquely; `mergeStorageStates`
+* rebuilds a `{cookies, origins}` object, so the key never reaches
+* agent-browser (which would reject an unknown top-level field). `ccqa run`
+* reads it to health-check the restore before executing steps.
+*/
+const SESSION_VERIFY_URL_KEY = "__ccqaVerifyUrl";
+/**
 * Resolve a session name to its state file path:
 * `<cwd>/.ccqa/sessions/<profile>/<name>.json`. The name is a slug (validated
 * by SessionNameSchema), so it can't escape the sessions directory. Used by
@@ -4448,20 +4338,54 @@ function loadStateIntoSession(sessionName, statePath) {
 	};
 	return { ok: true };
 }
+/** Drop every trailing slash so `/a` and `/a/` compare equal. */
+function normalizePath(pathname) {
+	return pathname.replace(/\/+$/, "");
+}
 /**
-* Prove a just-saved session actually restores to a signed-in page, in a fresh
-* throwaway agent-browser session, before it's trusted (e.g. uploaded to the
-* hub). Loads `statePath` into a clean session, navigates to `verifyUrl`, and
-* checks that a login form did NOT appear — the common failure mode where a
-* bootstrap was saved before the app finished signing in, so cookies restore
-* but the app still demands re-auth.
+* Behaviour-based "signed in?" check with no product knowledge: after
+* restoring a session, opening `requestedUrl` must settle on the SAME origin
+* and WITHIN the requested path. An expired/absent auth redirects elsewhere —
+* a sign-in route on the same origin, or a different origin entirely — so a
+* final URL that left the requested origin+path means the restore failed.
+*
+* This replaces the old "is a password input visible?" heuristic, which had
+* false positives (multi-step / SSO / workspace-picker sign-in screens show no
+* password field) and false negatives (a signed-in page can host a
+* change-password form). Trailing slashes are insensitive; a malformed URL on
+* either side returns false.
 *
-* "Signed-in" is detected generically (no product strings): a password input
-* present means a login form is showing → not restored. This is a positive
-* gate on the save, not a runtime check. Best-effort: on infrastructure errors
-* (daemon won't start, navigation fails) it returns `restored: false` with the
-* error so the caller can surface it rather than silently trusting the save.
-* Always closes the throwaway session.
+* Limitation: if `requestedUrl` is just an origin root, any same-origin page
+* counts as "stayed" (`startsWith("")` is always true) — so callers should
+* pass a deep, already-signed-in page URL. And an app that renders a login
+* form IN PLACE at the same URL (no redirect) can't be caught this way; the
+* escape hatch for that is a future explicit positive signal (e.g. a
+* `--verify-text` the caller expects to see). See issue #109.
+*/
+function urlStayedAtTarget(requestedUrl, finalUrl) {
+	let requested;
+	let final;
+	try {
+		requested = new URL(requestedUrl);
+		final = new URL(finalUrl);
+	} catch {
+		return false;
+	}
+	if (requested.origin !== final.origin) return false;
+	return normalizePath(final.pathname).startsWith(normalizePath(requested.pathname));
+}
+/**
+* Prove a saved session actually restores to a signed-in page, in a fresh
+* throwaway agent-browser session. Loads `statePath` into a clean session,
+* opens `verifyUrl`, and checks the browser STAYED at that URL's origin+path
+* (see {@link urlStayedAtTarget}) — an expired/absent session redirects to a
+* sign-in route or another origin instead. Used both as a save-time gate in
+* `bootstrap` and as a pre-run health check in `ccqa run`.
+*
+* Best-effort: on infrastructure errors (daemon won't start, navigation
+* fails) it returns `restored: false` with the error so the caller can
+* surface it rather than silently trusting the session. Always closes the
+* throwaway session.
 */
 function verifySessionRestores(statePath, verifyUrl) {
 	const verifySession = `ccqa-session-verify-${process.pid}-${trackedTempDirs.size}`;
@@ -4497,17 +4421,17 @@ function verifySessionRestores(statePath, verifyUrl) {
 		const probe = spawnAB([
 			"--session",
 			verifySession,
-			"get",
-			"count",
-			"input[type=password]"
+			"eval",
+			"location.href"
 		]);
 		if (probe.status !== 0) return {
 			restored: false,
 			reason: (probe.stderr || probe.stdout || `probe exited ${probe.status}`).trim()
 		};
-		if ((Number.parseInt(probe.stdout.replace(/[^0-9]/g, ""), 10) || 0) >= 1) return {
+		const finalHref = unwrapEvalString(probe.stdout);
+		if (!urlStayedAtTarget(verifyUrl, finalHref)) return {
 			restored: false,
-			reason: "a sign-in form appeared — the app is not signed in after restore"
+			reason: `restore left the verify URL — landed on ${safeOriginPath(finalHref)}`
 		};
 		return { restored: true };
 	} finally {
@@ -4518,6 +4442,25 @@ function verifySessionRestores(statePath, verifyUrl) {
 		]);
 	}
 }
+/** Take the last non-empty line of `agent-browser eval` stdout and JSON-unquote it. */
+function unwrapEvalString(stdout) {
+	const lines = stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+	const last = lines[lines.length - 1] ?? "";
+	try {
+		const parsed = JSON.parse(last);
+		if (typeof parsed === "string") return parsed;
+	} catch {}
+	return last.replace(/^"|"$/g, "");
+}
+/** `origin + pathname` of a URL, or the raw string if it doesn't parse. */
+function safeOriginPath(href) {
+	try {
+		const u = new URL(href);
+		return u.origin + u.pathname;
+	} catch {
+		return href;
+	}
+}
 //#endregion
 //#region src/prompts/prompt-names.ts
 /**
@@ -5652,21 +5595,33 @@ async function runDriftAuditOne(r, opts, cwd) {
 	return result.issues.length > 0 ? result.issues : null;
 }
 /**
+* Sessions whose restore has already been health-checked this process, keyed
+* `<profile>/<name>`. A run of many specs restores the same session repeatedly;
+* we only open a throwaway verify browser the first time.
+*/
+const verifiedSessions = /* @__PURE__ */ new Set();
+/**
 * Resolve `spec.session` names to a single state file to restore, fetching
 * each named session from the hub (`.ccqa/sessions/*.json` is no longer
 * read here). Every name must load as a valid agent-browser state (the spec
 * assumes it starts signed-in); a missing/malformed session fails with a
-* `ccqa session bootstrap` hint instead of running unauthenticated. Loaded
-* states are always merged (even a single one) and written to a fresh temp
-* file — callers must invoke the returned `cleanup()` once the run is done.
-*/
-async function resolveSessionState(names, hubCtx, profile) {
+* `ccqa session bootstrap` hint instead of running unauthenticated.
+*
+* If a session carries an embedded verify URL (bootstrap saved it), the
+* restore is health-checked before the run starts, so an expired/unusable
+* session fails fast with a re-bootstrap hint instead of every step failing
+* generically. Loaded states are always merged (even a single one) and written
+* to a fresh temp file — callers must invoke the returned `cleanup()` once the
+* run is done. `verify` is injectable for tests.
+*/
+async function resolveSessionState(names, hubCtx, profile, verify = verifySessionRestores) {
 	if (names.length === 0 || hubCtx === null) return {
 		ok: false,
 		error: `session '${names.join(", ")}' requires a hub connection`,
 		hint: "set --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN) to restore sessions from the hub"
 	};
 	const resolvedProfile = profile ?? "default";
+	const profileFlag = profile ? ` --profile ${profile}` : "";
 	const loaded = [];
 	const broken = [];
 	for (const name of names) {
@@ -5681,16 +5636,28 @@ async function resolveSessionState(names, hubCtx, profile) {
 			broken.push(name);
 			continue;
 		}
+		const embedded = state[SESSION_VERIFY_URL_KEY];
+		if (typeof embedded === "string") {
+			const memoKey = `${resolvedProfile}/${name}`;
+			if (!verifiedSessions.has(memoKey)) {
+				const tmp = await writeMergedTempState(mergeStorageStates([state]));
+				const check = verify(tmp, embedded);
+				await removeTempStateDir(tmp);
+				if (!check.restored) return {
+					ok: false,
+					error: `session '${name}' did not restore to a signed-in page — ${check.reason}`,
+					hint: `re-bootstrap it: ccqa session bootstrap ${name}${profileFlag}`
+				};
+				verifiedSessions.add(memoKey);
+			}
+		} else warn(`session '${name}' has no embedded verify URL (saved by an older ccqa) — skipping the pre-run restore check`);
 		loaded.push(state);
 	}
-	if (broken.length > 0) {
-		const profileFlag = profile ? ` --profile ${profile}` : "";
-		return {
-			ok: false,
-			error: `session not usable on the hub: ${broken.join(", ")}`,
-			hint: `create it with: ${broken.map((name) => `ccqa session bootstrap ${name}${profileFlag}`).join("  ·  ")}`
-		};
-	}
+	if (broken.length > 0) return {
+		ok: false,
+		error: `session not usable on the hub: ${broken.join(", ")}`,
+		hint: `create it with: ${broken.map((name) => `ccqa session bootstrap ${name}${profileFlag}`).join("  ·  ")}`
+	};
 	const statePath = await writeMergedTempState(mergeStorageStates(loaded));
 	return {
 		ok: true,
@@ -10002,7 +9969,6 @@ function buildTraceSystemPrompt(input) {
 	const stepsText = input.steps.map((step) => `### ${step.id} [${step.source}]
 - **Instruction**: ${step.instruction}
 - **Expected**: ${step.expected}`).join("\n\n");
-	const relatedPathsBlock = buildRelatedPathsInstruction();
 	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
@@ -10272,6 +10238,9 @@ CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session
 - 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\` and \`get url\` exit 0 regardless of what they print. **Read the output**: if the printed count / URL 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).
+- **\`url_contains\` is opt-in, not a habit.** 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}/policies\`, assert \`\${APP_URL}/policies\` (or the tail \`/policies\`); 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\`, \`/policies/new\`), taken from a \`\${VAR}\` you opened — not from a redirect you watched.
 
 **Fallback text protocol** — ONLY for assert types the markers cannot express
 (\`element_enabled\`, \`element_disabled\`, \`element_checked\`,
@@ -10382,7 +10351,7 @@ RUN_COMPLETED|passed|<summary>
 RUN_COMPLETED|failed|<summary>
 \`\`\`
 
-${relatedPathsBlock}## Start
+## Start
 
 Begin by clearing cookies, then proceed straight to the first step's instruction.
 
@@ -10401,130 +10370,12 @@ AB_ACTION|cookies_clear
 Then emit \`STEP_START|step-01|...\` and execute the first step, prefixing
 every one of its agent-browser commands with \`CCQA_STEP=step-01\`. The first
 step is responsible for opening the initial URL.
-`;
-}
-function buildRelatedPathsInstruction() {
-	return `## Post-run: emit \`relatedPaths\` block
-
-After all steps are complete (regardless of pass/fail) and **before** \`RUN_COMPLETED\`, you MUST emit a single \`RELATED_PATHS\` block. The host (not you) writes these paths into the spec — your only job is to emit the block.
-
-\`relatedPaths\` is a list of glob patterns identifying the source files this spec depends on. CI uses them to decide whether a code change should trigger a drift check for this spec.
-
-**Do NOT modify any source files.** You have only \`Read\`, \`Grep\`, and \`Glob\` for source inspection. The block you emit is the only output the host uses to update the spec.
-
-**Inputs to consider:**
-- The URLs you opened (\`AB_ACTION|open|...\`)
-- The aria-labels, placeholders, and visible texts you clicked / filled / waited on
-- The component / page / route files that render those strings (find them with \`Grep\`/\`Read\`/\`Glob\`)
-
-**How to choose paths:**
-1. For each URL the test navigates to, locate the route/page file and include it (e.g. \`src/app/tasks/page.tsx\`, \`src/pages/tasks/index.tsx\`).
-2. For each unique aria-label / placeholder / visible text you interacted with, \`Grep\` the codebase, find the defining component, and include either the file or its parent feature directory.
-3. Prefer **directory globs** (e.g. \`src/features/tasks/**\`) over individual files when several related components live in the same area. Otherwise list specific files.
-4. Skip third-party files (\`node_modules/\`), build output (\`dist/\`, \`.next/\`), and generated code.
-5. Be conservative — false positives (extra paths) are fine; false negatives (missing paths) cause drift to be missed in CI. When unsure whether a path is relevant, include it.
-6. **Path base:** a path inside this working directory MUST be relative to it — the same base your \`Glob\`/\`Grep\` tools use (\`src/features/tasks/**\`, NOT the repo-root form \`apps/foo/src/features/tasks/**\`). For a file in a monorepo sibling package this spec genuinely depends on, use its **repo-root-relative** path (e.g. \`packages/ui-kit/src/FilePicker.tsx\`); never emit \`../\` forms.
-7. **Shared / design-system components:** include one only when the spec's checks depend on that component's specific behaviour (e.g. the flow exercises its file picker). Do NOT list generic primitives every screen uses (buttons, tags, dialogs, layout) — they would scope this spec into almost every UI change.
-
-**Output format (STRICT — one line per path, no leading dashes, no commentary inside the block):**
-
-\`\`\`
-RELATED_PATHS_BEGIN
-src/features/tasks/**
-src/app/tasks/page.tsx
-RELATED_PATHS_END
-\`\`\`
-
-Emit the block outside any other code block, on its own lines. If the test could not exercise the feature at all (e.g. blocked early), emit the block anyway with whatever paths you can identify; emit \`RELATED_PATHS_BEGIN\` immediately followed by \`RELATED_PATHS_END\` only if you genuinely could not identify any related file.
-
 `;
 }
 function buildTracePrompt(title) {
 	return `Execute the test for "${title}". Each step's instruction includes the URL or selector context it needs.`;
 }
 //#endregion
-//#region src/drift/parse-related-paths.ts
-/**
-* Pull a `RELATED_PATHS_BEGIN ... RELATED_PATHS_END` block out of the trace
-* agent's combined text output. Lines inside the block become entries; blank
-* lines, bullet markers, and code fences are tolerated. Returns null when the
-* agent did not emit a block at all so the caller can warn instead of silently
-* clearing the spec's existing relatedPaths.
-*/
-function parseRelatedPathsBlock(text) {
-	const match = text.match(/RELATED_PATHS_BEGIN\s*\n?([\s\S]*?)\n?RELATED_PATHS_END/);
-	if (!match || match[1] === void 0) return null;
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const raw of match[1].split("\n")) {
-		const line = raw.replace(/^```.*$/, "").trim();
-		if (!line) continue;
-		const cleaned = line.replace(/^[-*]\s+/, "").trim();
-		if (!cleaned || seen.has(cleaned)) continue;
-		seen.add(cleaned);
-		out.push(cleaned);
-	}
-	return out;
-}
-/**
-* Normalize parsed entries to the canonical bases the drift matcher expects:
-* app-relative for files inside the working directory, repo-root-relative
-* for files outside it. Models sometimes emit an in-app path in repo-root
-* form (`apps/foo/src/...`) or an outside-package path in `../` form — both
-* would silently never match.
-*
-* `cwdPrefix` is the working directory's path relative to the repo root
-* ("" when they coincide, unknown → pass `null` to skip prefix handling).
-*/
-function normalizeRelatedPaths(paths, cwdPrefix) {
-	const out = [];
-	const warnings = [];
-	const seen = /* @__PURE__ */ new Set();
-	const push = (p) => {
-		if (!seen.has(p)) {
-			seen.add(p);
-			out.push(p);
-		}
-	};
-	for (const raw of paths) {
-		const p = raw.replace(/^\.\//, "");
-		if (cwdPrefix !== null && cwdPrefix !== "" && p.startsWith(`${cwdPrefix}/`)) {
-			push(p.slice(cwdPrefix.length + 1));
-			continue;
-		}
-		if (p.startsWith("../")) {
-			if (cwdPrefix === null || cwdPrefix === "") {
-				warnings.push(`dropped relatedPaths entry "${raw}" — it points outside the repository`);
-				continue;
-			}
-			const segments = [...cwdPrefix.split("/"), ...p.split("/")];
-			const resolved = [];
-			let escaped = false;
-			for (const seg of segments) {
-				if (seg === "" || seg === ".") continue;
-				if (seg === "..") {
-					if (resolved.length === 0) {
-						escaped = true;
-						break;
-					}
-					resolved.pop();
-				} else resolved.push(seg);
-			}
-			if (escaped || resolved.length === 0) {
-				warnings.push(`dropped relatedPaths entry "${raw}" — it points outside the repository`);
-				continue;
-			}
-			push(resolved.join("/"));
-			continue;
-		}
-		push(p);
-	}
-	return {
-		paths: out,
-		warnings
-	};
-}
-//#endregion
 //#region src/runtime/replay-validate.ts
 function isPollCheck(x) {
 	return x !== null && !Array.isArray(x) && x.kind === "poll-present";
@@ -11029,7 +10880,11 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	const expanded = expandSpec(spec, { blocks: await loadAllBlocks(opts.cwd) });
 	const envScrub = buildSpecEnvScrub(spec, expanded);
 	const envScrubMap = envScrub.map;
-	if (envScrub.unresolved.length > 0) warn(`spec references env var(s) with empty/unset values: ${envScrub.unresolved.join(", ")} — their literal trace-time values will be baked into ir.json`);
+	if (envScrub.unresolved.length > 0) {
+		warn(`spec references env var(s) that are unset at record time: ${envScrub.unresolved.join(", ")}`);
+		warn("their concrete trace-time values (e.g. navigate URLs) will be baked into ir.json instead of kept as ${VAR}, so the recording won't switch across environments.");
+		hint("load these vars before recording — pass --profile <name> (hub) or define them in .env — then re-record.");
+	}
 	meta("spec", spec.title);
 	meta("steps", expanded.length);
 	const includes = collectIncludedBlockNames(spec);
@@ -11051,7 +10906,6 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	let overallStatus = "passed";
 	const traceActions = [];
 	const stepTracker = createStepTracker();
-	let relatedPathsBuffer = null;
 	const withStepId = (action, stepId) => {
 		if (!action) return null;
 		return stepId ? {
@@ -11098,13 +10952,7 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 		if (msg.type !== "assistant") return;
 		for (const block of msg.message.content ?? []) {
 			if (block.type !== "text" || !block.text) continue;
-			const text = block.text;
-			if (relatedPathsBuffer !== null) relatedPathsBuffer += text + "\n";
-			else {
-				const idx = text.indexOf("RELATED_PATHS_BEGIN");
-				if (idx !== -1) relatedPathsBuffer = text.slice(idx) + "\n";
-			}
-			for (const line of text.split("\n")) {
+			for (const line of block.text.split("\n")) {
 				const trimmed = line.trim();
 				const status = parseStatusLine(line);
 				if (status) {
@@ -11129,13 +10977,6 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	meta("saved", recordingPath);
 	meta("actions", validatedActions.length);
 	meta("status", overallStatus.toUpperCase());
-	const parsedRelatedPaths = relatedPathsBuffer !== null ? parseRelatedPathsBlock(relatedPathsBuffer) : null;
-	if (parsedRelatedPaths !== null) {
-		const { paths: relatedPaths, warnings } = normalizeRelatedPaths(parsedRelatedPaths, await resolveCwdPrefix(opts.cwd));
-		for (const w of warnings) warn(w);
-		const written = await updateSpecRelatedPaths(featureName, specName, relatedPaths, opts.cwd);
-		if (written) meta("relatedPaths", `${relatedPaths.length} path(s) written to ${written}`);
-	} else warn("trace did not emit a RELATED_PATHS block; drift --changed cannot scope this spec");
 	hint(`run 'ccqa generate ${featureName}/${specName}' to generate a test script`);
 	return {
 		status: overallStatus,
@@ -11429,23 +11270,6 @@ function parseStatusLine(text) {
 	}
 	return null;
 }
-/**
-* The working directory's path relative to the git repo root ("" when they
-* coincide), used to pin relatedPaths bases. Null when git is unavailable —
-* normalization then skips prefix handling rather than guessing.
-*/
-async function resolveCwdPrefix(cwd) {
-	const { execFile } = await import("node:child_process");
-	const { promisify } = await import("node:util");
-	const { relative, resolve } = await import("node:path");
-	const dir = resolve(cwd ?? process.cwd());
-	try {
-		const { stdout } = await promisify(execFile)("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
-		return relative(stdout.trim(), dir);
-	} catch {
-		return null;
-	}
-}
 //#endregion
 //#region src/prompts/perspectives.ts
 /**
@@ -13246,7 +13070,7 @@ const initCommand = new Command("init").description("Create the .ccqa/ spec skel
 });
 //#endregion
 //#region src/cli/session.ts
-const AB = createRequire(import.meta.url).resolve("agent-browser/bin/agent-browser.js");
+const AB = resolveAgentBrowserBin$1();
 /**
 * Run agent-browser attached to the user's terminal (no timeout, inherited
 * stdio) so a human can complete an interactive login during `bootstrap`.
@@ -13313,6 +13137,7 @@ const bootstrapCommand = new Command("bootstrap").description("Open a headed bro
 			process.exit(1);
 		}
 		const state = await loadStorageState(tmpPath);
+		let payload = state;
 		if (opts.url) {
 			info("verifying the saved session restores to a signed-in page…");
 			const check = verifySessionRestores(tmpPath, opts.url);
@@ -13322,8 +13147,12 @@ const bootstrapCommand = new Command("bootstrap").description("Open a headed bro
 				process.exit(1);
 			}
 			info("restore verified — the session starts signed in.");
-		}
-		await hub.putSession(project, opts.profile ?? "default", name, state);
+			payload = {
+				...state,
+				[SESSION_VERIFY_URL_KEY]: opts.url
+			};
+		} else warn("no --url given — the session can't be verified now, and runs can't health-check it before executing steps; strongly consider re-running with --url <a signed-in page URL>.");
+		await hub.putSession(project, opts.profile ?? "default", name, payload);
 	} finally {
 		await rm(tmpDir, {
 			recursive: true,

package/dist/package.json

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

package/dist/runtime/test-helpers.mjs

@@ -1,4 +1,4 @@
-import { i as FAILURE_STEP_ID, n as spawnAB, r as FAILURE_SOURCE, t as sleepSync } from "../spawn-ab-Cr967J2N.mjs";
+import { c as FAILURE_SOURCE, l as FAILURE_STEP_ID, n as spawnAB, t as sleepSync } from "../spawn-ab-B9Il2TMd.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 //#region src/runtime/test-helpers.ts

package/dist/spawn-ab-B9Il2TMd.mjs

@@ -0,0 +1,210 @@
+import { createRequire } from "node:module";
+import { statSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/runtime/evidence-constants.ts
+/**
+* Shared constants for step-boundary evidence captured by abStepEvidence() /
+* captureFailureEvidence() and consumed by the run report. Kept under
+* `runtime/` so the test-helpers module — which generated test scripts import
+* via `ccqa/test-helpers` — can stay free of CLI-side imports while still
+* sharing the literal with run.ts.
+*/
+/** stepId reserved for the screenshot captured by fail() at the moment of an assertion failure. */
+const FAILURE_STEP_ID = "failure";
+/** source value paired with FAILURE_STEP_ID so the report can tell failure captures apart from step captures. */
+const FAILURE_SOURCE = "failed";
+//#endregion
+//#region src/runtime/agent-browser-bin.ts
+const require = createRequire(import.meta.url);
+function hasAgentBrowserShim(dir) {
+	try {
+		statSync(join(dir, "agent-browser"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Walks up from `start` looking for a `node_modules/.bin/agent-browser` shim.
+* Returns the .bin directory containing the shim, or null if none is found.
+*/
+function findNodeModulesBin(start) {
+	let cur = start;
+	while (true) {
+		const candidate = join(cur, "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+		const parent = dirname(cur);
+		if (parent === cur) return null;
+		cur = parent;
+	}
+}
+/** The shim-directory walk shared by every resolution below (no env override). */
+function resolveShimDir() {
+	const fromCwd = findNodeModulesBin(process.cwd());
+	if (fromCwd) return fromCwd;
+	const fromSelf = findNodeModulesBin(dirname(require.resolve("agent-browser/package.json")));
+	if (fromSelf) return fromSelf;
+	try {
+		const candidate = join(dirname(require.resolve("agent-browser/package.json")), "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+	} catch {}
+	return null;
+}
+/**
+* INVARIANT: every agent-browser invocation in one ccqa process — the host
+* side (`spawnAB`: state load, replay probes, …) and the Claude subprocess
+* (via the PATH prepended by `pathWithAgentBrowserShim`) — must resolve to
+* the SAME binary. agent-browser runs one daemon per binary, and a state
+* loaded into one daemon's session is invisible to a same-named session on
+* another daemon, so a split resolution silently loses session restores.
+* Both entry points below therefore share one resolution order:
+* `CCQA_AB_BIN` (explicit override, e.g. the e2e harness or a dev build
+* driving a consumer project's agent-browser) → the peer-installed shim
+* (consumer project first, then ccqa's own tree).
+*/
+/**
+* Resolves the executable `spawnAB` should invoke. Falls back to the package
+* JS entry (resolvable whenever the peer dependency is installed) when no
+* shim directory exists; throws only if agent-browser is missing entirely.
+*/
+function resolveAgentBrowserBin() {
+	const override = process.env["CCQA_AB_BIN"];
+	if (override) return override;
+	const shimDir = resolveShimDir();
+	if (shimDir) return join(shimDir, "agent-browser");
+	return require.resolve("agent-browser/bin/agent-browser.js");
+}
+/**
+* Resolves the directory containing the `agent-browser` shim that npm/pnpm
+* exposes on PATH for the peer-installed package. Used by `ccqa trace` /
+* `ccqa run` to prepend this directory to PATH so the Claude subprocess can
+* invoke `agent-browser ...` without requiring a global install.
+*
+* Returns null if agent-browser cannot be located.
+*/
+function resolveAgentBrowserBinDir() {
+	const override = process.env["CCQA_AB_BIN"];
+	if (override) return dirname(override);
+	return resolveShimDir();
+}
+/**
+* Returns a PATH string with the agent-browser shim directory prepended,
+* so `agent-browser ...` resolves without a global install. Falls back to
+* the original PATH when the package can't be resolved.
+*/
+function pathWithAgentBrowserShim(currentPath) {
+	const path = currentPath ?? "";
+	const dir = resolveAgentBrowserBinDir();
+	if (!dir) return path;
+	if (path.split(delimiter).includes(dir)) return path;
+	return dir + delimiter + path;
+}
+/**
+* Confirms before launching Claude that an `agent-browser` shim is reachable
+* via PATH. We do this up front so a missing peer dependency fails fast with
+* a clear message, instead of Claude burning tokens probing the system with
+* `which`, `find`, `npm install`, etc.
+*
+* The `resolver` argument is for tests; production calls take no args.
+*/
+function assertAgentBrowserAvailable(resolver = resolveAgentBrowserBinDir) {
+	const probe = process.env["CCQA_AB_BIN"] ?? (() => {
+		const dir = resolver();
+		return dir === null ? null : join(dir, "agent-browser");
+	})();
+	if (!probe) throw new AgentBrowserUnavailableError();
+	try {
+		const s = statSync(probe);
+		if (!s.isFile() && !s.isSymbolicLink()) throw new AgentBrowserUnavailableError();
+	} catch {
+		throw new AgentBrowserUnavailableError();
+	}
+	return dirname(probe);
+}
+var AgentBrowserUnavailableError = class extends Error {
+	constructor() {
+		super("agent-browser binary not found on PATH");
+		this.name = "AgentBrowserUnavailableError";
+	}
+};
+/** Human-readable explanation shown to the user when the guard fires. */
+function formatAgentBrowserUnavailableMessage() {
+	return [
+		"agent-browser is not installed or not on PATH.",
+		"",
+		"ccqa drives the browser via the peer-installed `agent-browser` package.",
+		"Install it in this project:",
+		"",
+		"  pnpm add -D agent-browser",
+		"  # or",
+		"  npm install -D agent-browser",
+		"",
+		"If it is already installed, make sure you are running ccqa from the",
+		"project root (or via your package runner, e.g. `pnpm exec ccqa ...`)."
+	].join("\n");
+}
+//#endregion
+//#region src/runtime/spawn-ab.ts
+const AB = resolveAgentBrowserBin();
+const EAGAIN_PATTERN = /Resource temporarily unavailable|os error 35/i;
+const EAGAIN_TOTAL_BUDGET_MS = 3e4;
+const EAGAIN_BACKOFF_MS = [
+	100,
+	200,
+	300,
+	500,
+	700,
+	1e3,
+	1500,
+	2e3,
+	2500,
+	3e3,
+	3e3,
+	3e3,
+	3e3,
+	3e3,
+	3e3
+];
+const PROCESS_HARD_TIMEOUT_MS = 35e3;
+function sleepSync(ms) {
+	const buf = new SharedArrayBuffer(4);
+	Atomics.wait(new Int32Array(buf), 0, 0, ms);
+}
+function spawnABOnce(args) {
+	const result = spawnSync(AB, args, {
+		stdio: "pipe",
+		timeout: PROCESS_HARD_TIMEOUT_MS
+	});
+	return {
+		status: result.status,
+		stdout: result.stdout?.toString() ?? "",
+		stderr: (result.stderr?.toString() ?? "") + (result.signal === "SIGTERM" ? "\n[ccqa] agent-browser killed after hard timeout" : "")
+	};
+}
+/**
+* Invoke `agent-browser` once and return its exit status/stdout/stderr,
+* retrying internally up to ~30s while the daemon's state file is in the
+* "Resource temporarily unavailable" race window. Used by both the test
+* runtime (`test-helpers.ts`) and the post-trace replay validation
+* (`replay-validate.ts`). Kept out of `test-helpers.ts` because that
+* module is also the public surface for generated test scripts — exposing
+* the raw spawner there would widen the contract for end users.
+*/
+function spawnAB(args) {
+	let result = spawnABOnce(args);
+	let elapsed = 0;
+	let attempt = 0;
+	while (result.status !== 0 && elapsed < EAGAIN_TOTAL_BUDGET_MS) {
+		const combined = `${result.stdout}\n${result.stderr}`;
+		if (!EAGAIN_PATTERN.test(combined)) return result;
+		const wait = EAGAIN_BACKOFF_MS[attempt] ?? 3e3;
+		sleepSync(wait);
+		elapsed += wait;
+		attempt++;
+		result = spawnABOnce(args);
+	}
+	return result;
+}
+//#endregion
+export { formatAgentBrowserUnavailableMessage as a, FAILURE_SOURCE as c, assertAgentBrowserAvailable as i, FAILURE_STEP_ID as l, spawnAB as n, pathWithAgentBrowserShim as o, AgentBrowserUnavailableError as r, resolveAgentBrowserBin as s, sleepSync as t };

package/package.json

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

package/dist/spawn-ab-Cr967J2N.mjs

@@ -1,79 +0,0 @@
-import { createRequire } from "node:module";
-import { spawnSync } from "node:child_process";
-//#region src/runtime/evidence-constants.ts
-/**
-* Shared constants for step-boundary evidence captured by abStepEvidence() /
-* captureFailureEvidence() and consumed by the run report. Kept under
-* `runtime/` so the test-helpers module — which generated test scripts import
-* via `ccqa/test-helpers` — can stay free of CLI-side imports while still
-* sharing the literal with run.ts.
-*/
-/** stepId reserved for the screenshot captured by fail() at the moment of an assertion failure. */
-const FAILURE_STEP_ID = "failure";
-/** source value paired with FAILURE_STEP_ID so the report can tell failure captures apart from step captures. */
-const FAILURE_SOURCE = "failed";
-//#endregion
-//#region src/runtime/spawn-ab.ts
-const require = createRequire(import.meta.url);
-const AB = process.env["CCQA_AB_BIN"] ?? require.resolve("agent-browser/bin/agent-browser.js");
-const EAGAIN_PATTERN = /Resource temporarily unavailable|os error 35/i;
-const EAGAIN_TOTAL_BUDGET_MS = 3e4;
-const EAGAIN_BACKOFF_MS = [
-	100,
-	200,
-	300,
-	500,
-	700,
-	1e3,
-	1500,
-	2e3,
-	2500,
-	3e3,
-	3e3,
-	3e3,
-	3e3,
-	3e3,
-	3e3
-];
-const PROCESS_HARD_TIMEOUT_MS = 35e3;
-function sleepSync(ms) {
-	const buf = new SharedArrayBuffer(4);
-	Atomics.wait(new Int32Array(buf), 0, 0, ms);
-}
-function spawnABOnce(args) {
-	const result = spawnSync(AB, args, {
-		stdio: "pipe",
-		timeout: PROCESS_HARD_TIMEOUT_MS
-	});
-	return {
-		status: result.status,
-		stdout: result.stdout?.toString() ?? "",
-		stderr: (result.stderr?.toString() ?? "") + (result.signal === "SIGTERM" ? "\n[ccqa] agent-browser killed after hard timeout" : "")
-	};
-}
-/**
-* Invoke `agent-browser` once and return its exit status/stdout/stderr,
-* retrying internally up to ~30s while the daemon's state file is in the
-* "Resource temporarily unavailable" race window. Used by both the test
-* runtime (`test-helpers.ts`) and the post-trace replay validation
-* (`replay-validate.ts`). Kept out of `test-helpers.ts` because that
-* module is also the public surface for generated test scripts — exposing
-* the raw spawner there would widen the contract for end users.
-*/
-function spawnAB(args) {
-	let result = spawnABOnce(args);
-	let elapsed = 0;
-	let attempt = 0;
-	while (result.status !== 0 && elapsed < EAGAIN_TOTAL_BUDGET_MS) {
-		const combined = `${result.stdout}\n${result.stderr}`;
-		if (!EAGAIN_PATTERN.test(combined)) return result;
-		const wait = EAGAIN_BACKOFF_MS[attempt] ?? 3e3;
-		sleepSync(wait);
-		elapsed += wait;
-		attempt++;
-		result = spawnABOnce(args);
-	}
-	return result;
-}
-//#endregion
-export { FAILURE_STEP_ID as i, spawnAB as n, FAILURE_SOURCE as r, sleepSync as t };