ccqa 1.50.1 → 1.51.1

package/dist/bin/ccqa.mjs

@@ -11126,6 +11126,7 @@ ${stepsText}
 - Judge ONLY this step's \`Expected\` condition. Do not infer pass/fail from steps that have not run yet.
 - If the page shows an error banner, a 404, a login wall, or any blocker that prevents the expected outcome — fail.
 - If the expected outcome is partially satisfied (e.g. the page loaded but the asserted element is missing) — fail, and say which part is missing.
+- **An \`Expected\` may label its parts.** A \`must:\` line is the assertion — the rule above applies to it. A \`when present:\` line is observed, not required: judge it when it is there, and when it is absent say so in your reason and pass on the \`must:\` lines alone. Every line of a labelled \`Expected\` carries a label; text with no labels at all is all \`must:\`.
 - Pass only when you have *positive* evidence (a successful snapshot, a verified URL, a wait that resolved). "No error shown" is not enough on its own.
 - Do not invent success when blocked: fail honestly with a short reason.
 - **Evidence discipline**: when the assertion target is a specific row / message / banner / URL, scroll it into view (or focus the relevant pane) before letting the step end. The "after" screenshot is captured for you automatically — your job is to make sure that screenshot shows the thing your STEP_RESULT line is talking about.
@@ -12634,12 +12635,21 @@ function isStateSelector(selector) {
 function plainSelectorOf(action) {
 	return action.locator && action.index === void 0 ? locatorToSelector(action.locator) : void 0;
 }
+/**
+* A `wait` the post-trace validator actually ran and saw fail. Cascade-skipped
+* actions carry the flag without ever having been attempted, so they are not
+* evidence of anything and stay.
+*/
+function isProvenFailedWait(action) {
+	return action.replayUnstable === true && !(action.replayReason ?? "").includes("skipped after a preceding action failed");
+}
 function actionToLine$1(action) {
 	if (isRefSelector(plainSelectorOf(action))) return null;
 	if (action.action === "assert" && action.replayUnstable && typeof action.replayReason === "string" && action.replayReason.includes("selector not present")) {
 		const sel = plainSelectorOf(action) ?? action.observation ?? "(unknown)";
 		return `// [warn] replay-unstable: dropped over-assertion (${action.assert ?? "assert"} ${sel}) — selector not present on replay`;
 	}
+	if (action.action === "wait" && isProvenFailedWait(action)) return `// [warn] replay-unstable: dropped wait (${plainSelectorOf(action) ?? "(unknown)"}) — did not resolve on replay`;
 	switch (action.action) {
 		case "snapshot": return action.observation ? `// ${action.observation}` : null;
 		case "wait": {
@@ -13725,6 +13735,7 @@ function actionToLine(action) {
 		const sel = action.locator?.value ?? action.observation ?? "(unknown)";
 		return `// [warn] replay-unstable: dropped over-assertion (${action.assert ?? "assert"} ${sel}) — selector not present on replay`;
 	}
+	if (action.action === "wait" && action.replayUnstable === true && !(action.replayReason ?? "").includes("skipped after a preceding action failed")) return `// [warn] replay-unstable: dropped wait (${action.locator?.value ?? "(unknown)"}) — did not resolve on replay`;
 	const locator = action.locator ? locatorToPlaywright(action.locator, action.index) : null;
 	const subject = locator !== null && action.index === void 0 ? `${locator}.first()` : locator;
 	switch (action.action) {
@@ -14664,32 +14675,42 @@ function requireReportToHubConnection(conn) {
 	process.exit(2);
 }
 /**
-* Open the run a `--report-to-hub` command patches into. Failure is fatal: a
-* job that asked to publish and cannot reach the hub has not done what it was
-* told. Thrown rather than exited, so a caller's `finally` still runs (the
-* audit releases its spec claims there). Not retried: a dropped response after
-* the hub committed would leave a second orphan running run.
+* Open the run a `--report-to-hub` command patches into, and name it on stderr
+* — stdout belongs to the report (`--report-format json`), and a caller that
+* links to the run needs its id before the command ends (docs/hub.md).
+*
+* Failure is fatal: a job that asked to publish and cannot reach the hub has
+* not done what it was told. Thrown rather than exited, so a caller's
+* `finally` still runs (the audit releases its spec claims there). Not
+* retried: a dropped response after the hub committed would leave a second
+* orphan running run.
 */
-async function openHubRun(kind, conn, cwd, profile) {
-	const [branch, gitHead] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
+async function openHubRun(kind, conn, cwd, opts = {}) {
+	const [branch, gitHead] = await Promise.all([detectBranch(cwd), opts.gitHead !== void 0 ? opts.gitHead : getGitHead(cwd)]);
+	let opened;
 	try {
-		const run = await conn.hub.openRun({
+		opened = await conn.hub.openRun({
 			project: conn.project,
 			kind,
 			...branch ? { branch } : {},
-			...profile ? { profile } : {},
+			...opts.profile ? { profile: opts.profile } : {},
 			...gitHead ? { gitHead } : {},
+			...opts.deployedSha ? { deployedSha: opts.deployedSha } : {},
 			...ciProvenance()
 		});
-		return {
-			hub: conn.hub,
-			kind,
-			runId: run.id,
-			gitHead
-		};
 	} catch (err) {
 		throw new RunUsageError(`--report-to-hub: could not open a run on the hub (${errMessage(err)})`);
 	}
+	process.stderr.write(`[hub-run] ${JSON.stringify({
+		id: opened.id,
+		kind
+	})}\n`);
+	return {
+		hub: conn.hub,
+		kind,
+		runId: opened.id,
+		gitHead
+	};
 }
 /**
 * Close an open run with its final rows and envelope, answering whether it
@@ -15437,25 +15458,17 @@ async function executeRun(targets, opts) {
 			reportDir: null
 		};
 	}
-	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir, resources);
 	let hubRunId = null;
 	let hubSink;
 	let hubPublishBroken = false;
-	if (hubCtx != null && opts.reportToHub) try {
-		const branch = await detectBranch(cwd);
-		const opened = await hubCtx.hub.openRun({
-			project: hubCtx.project,
-			...branch ? { branch } : {},
+	if (hubCtx != null && opts.reportToHub) {
+		const { runId } = await openHubRun("run", hubCtx, cwd, {
 			...opts.hubProfile ? { profile: opts.hubProfile } : {},
-			...git.head ? { gitHead: git.head } : {},
-			...deployedSha ? { deployedSha } : {},
-			...ciProvenance(),
-			kind: "run"
+			gitHead: git.head,
+			deployedSha
 		});
-		hubRunId = opened.id;
-		info(`hub: incremental run opened (${opened.id})`);
-		await coverage?.linkHubRun(opened.id);
-		const runId = opened.id;
+		hubRunId = runId;
+		await coverage?.linkHubRun(runId);
 		let hubPatchEverSucceeded = false;
 		hubSink = { onUpsert: async (row) => {
 			try {
@@ -15473,8 +15486,6 @@ async function executeRun(targets, opts) {
 				} else warn(`hub: incremental push failed for ${row.feature}/${row.spec}: ${errMessage(err)}`);
 			}
 		} };
-	} catch (err) {
-		throw new RunUsageError(`--report-to-hub: could not open a run on the hub (${errMessage(err)})`);
 	}
 	const incrementalReport = createIncrementalReport(reportDir, buildReportEnvelope({
 		git,
@@ -15499,6 +15510,7 @@ async function executeRun(targets, opts) {
 			warn(`hub: could not finalize interrupted run ${hubRunId}: ${errMessage(err)}`);
 		}
 	});
+	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir, resources);
 	const externalRows = await runExternalSpecs(dispatch, {
 		cwd,
 		reportDir,
@@ -16828,6 +16840,8 @@ CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session
 
 - **Assert what the step asks about, nothing else.** The \`expected\` is the contract; anything else you happened to see on the way is not. A nav item, a heading or a greeting that the step never mentions adds no coverage, differs between recordings of the same spec, and is the first thing to break on replay — so the next recording quietly drops it and the test gets weaker without anyone deciding that.
 
+- **An \`expected\` that labels its parts is recorded down to the \`must:\` lines.** A \`when present:\` line names something the product does not produce on every run, so **nothing that fails on its absence may be recorded for it** — no assert, and no \`wait --text\` either: a recorded wait throws on the next run that legitimately lacks it, which is the same failure an assert would have caused. Look at it with \`snapshot\` or \`get count\` if you want to see it, and record nothing. When the step needs to wait for something asynchronous to arrive, anchor that wait on a \`must:\` signal — waiting on the optional one makes the whole step hinge on it. Every line of a labelled \`expected\` carries a label; text with no labels at all is all \`must:\`.
+
 - **\`url_contains\` is opt-in, not a habit.** The same rule, in the form that gets broken most. Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
 - **When you do assert a URL, the substring may come from ONE place only:** a \`\${VAR}\` URL that *this step's own instruction* opened, written as that \`\${VAR}\` followed by the literal tail after it. If the step opens \`\${APP_URL}/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.
@@ -17986,8 +18000,7 @@ async function runRecord(specPath, opts) {
 		}
 		throw e;
 	});
-	const push = pushConn ? await openHubRun("record", pushConn, cwdForProfile, opts.hubProfile) : null;
-	if (push) info(`hub: record run opened (${push.runId})`);
+	const push = pushConn ? await openHubRun("record", pushConn, cwdForProfile, { ...opts.hubProfile ? { profile: opts.hubProfile } : {} }) : null;
 	let recorded = false;
 	let sealed = true;
 	let tracingStep;
@@ -19065,10 +19078,7 @@ async function runAudit(specPath, opts) {
 	let push = null;
 	try {
 		promptCtx = await resolveAuditPromptContext(opts, cwd);
-		if (pushConn) {
-			push = await openHubRun("drift", pushConn, cwd, opts.hubProfile);
-			if (format === "text") info(`hub: incremental drift run opened (${push.runId})`);
-		}
+		if (pushConn) push = await openHubRun("drift", pushConn, cwd, { ...opts.hubProfile ? { profile: opts.hubProfile } : {} });
 		results = await analyzeDrift({
 			targets,
 			cwd,
@@ -20613,7 +20623,7 @@ function createPatchRunHandler(config) {
 		sendJson(ctx.res, 200, updated);
 	};
 }
-/** GET /api/v1/runs?project&branch&status&kind&since&until&limit */
+/** GET /api/v1/runs?project&branch&status&kind&ciRunId&since&until&limit */
 function createListRunsHandler(storage) {
 	return async (ctx) => {
 		const project = ctx.url.searchParams.get("project");
@@ -20621,11 +20631,13 @@ function createListRunsHandler(storage) {
 		const status = ctx.url.searchParams.get("status");
 		const limitRaw = ctx.url.searchParams.get("limit");
 		const kindsRaw = ctx.url.searchParams.get("kind");
+		const ciRunId = boundedParam(ctx.url.searchParams.get("ciRunId"), "ciRunId", 128);
 		const runs = await storage.runs.list({
 			...project ? { project } : {},
 			...branch ? { branch } : {},
 			...status ? { status } : {},
 			...kindsRaw ? { kinds: kindsRaw.split(",").map(requireKind) } : {},
+			...ciRunId ? { ciRunId } : {},
 			...requireWindowParams(ctx.url),
 			...limitRaw ? { limit: Number(limitRaw) } : {}
 		});
@@ -24817,12 +24829,15 @@ const CLIENT_JS = `
     // Disconnected: the full-screen login gate is the only thing to show.
     if (!state.token) { showAuthGate(false); return; }
     showAuthGate(true);
+    // A run is addressed by its own id, not through a project, so a link from
+    // outside (a chat message, a CI job) opens it even in a browser that has
+    // never picked one — ahead of the gate below, which would drop the link.
+    var m = parseRunHash(location.hash);
+    if (m) { openRunDetail(m.runId, m.caseKey); return; }
     // With no project chosen yet, the Projects picker is the only useful view —
     // land there (e.g. right after login) instead of an empty Runs list, and
-    // gate any deep-linked #/runs or #/secrets to it too.
+    // gate any deep-linked project-scoped view to it too.
     if (location.hash === "#/projects" || !state.project) { openProjects(); return; }
-    var m = parseRunHash(location.hash);
-    if (m) { openRunDetail(m.runId, m.caseKey); return; }
     if (location.hash === "#/perspectives") { openPerspectives(); return; }
     if (location.hash === "#/coverage") { openCoverage(); return; }
     if (location.hash === "#/secrets") { openSecrets(); return; }
@@ -26406,6 +26421,11 @@ const CLIENT_JS = `
     var runGone = false;
 
     apiFetch("/api/v1/runs/" + encodeURIComponent(runId)).then(function (run) {
+      // Arrived by an outside link: the selected project is whatever the last
+      // visit or the boot auto-select left, which need not be this run's.
+      // Follow the run, so the nav around it answers for the project the page
+      // is actually showing.
+      if (run.project && run.project !== state.project) adoptProject(run.project);
       renderRunHead(run);
     }).catch(function (err) {
       runGone = err.status === 404;
@@ -28483,14 +28503,20 @@ const CLIENT_JS = `
     updateNavGate();
   }
 
-  // Scope to a project and land on its Runs view. Shared by the top menu, the
-  // Projects grid, and the "new project" flow. Switching project restores the
-  // profile last chosen for that project (or "default" if none was saved);
-  // the Secrets tab reloads the profile list when opened.
-  function chooseProject(p) {
+  // Scope the UI to a project, restoring the profile last chosen for it (or
+  // "default" if none was saved); the Secrets tab reloads the profile list when
+  // opened. Separate from the navigation below because arriving on a run by
+  // link adopts a project without going anywhere.
+  function adoptProject(p) {
     setProject(p);
     storeProject(p);
     setProfile(storedProfileForProject(p) || "default");
+  }
+
+  // Scope to a project and land on its Runs view. Shared by the top menu, the
+  // Projects grid, and the "new project" flow.
+  function chooseProject(p) {
+    adoptProject(p);
     location.hash = "#/runs";
     route();
   }
@@ -30188,7 +30214,7 @@ function createFileRunStore(root) {
 		async delete(id) {
 			await serialize(runMetaPath(root, id), () => removePath(runDir(root, id)));
 		},
-		async list({ project, branch, status, kinds, since, until, limit }) {
+		async list({ project, branch, status, kinds, ciRunId, since, until, limit }) {
 			const ids = await listSubdirsOrEmpty(runsDir(root));
 			const inWindow = windowFilter({
 				since,
@@ -30202,6 +30228,7 @@ function createFileRunStore(root) {
 				if (branch !== void 0 && run.branch !== branch) continue;
 				if (status !== void 0 && run.status !== status) continue;
 				if (kinds !== void 0 && !kinds.includes(run.kind)) continue;
+				if (ciRunId !== void 0 && run.ciRunId !== ciRunId) continue;
 				if (!inWindow(run.createdAt)) continue;
 				runs.push(run);
 			}

package/dist/hub-client/index.d.mts

@@ -1147,9 +1147,10 @@ interface HubClient {
    * `gitHead` stamps the run's commit at open time, so even a run that dies
    * before its final reconcile patch is attributable to a commit.
    *
-   * `deployedSha` does the same for the environment's commit. The hub would
-   * otherwise read its own deploy-log head here, and the open happens after
-   * the deterministic phase, not before the first spec.
+   * `deployedSha` does the same for the environment's commit: the baseline the
+   * caller selected against, which a `--rerun` inherits from an earlier run.
+   * Left unset the hub reads its own deploy-log head, which by the time this
+   * call lands can already name a later deploy.
    */
   openRun(meta: {
     project: string;
@@ -1165,11 +1166,13 @@ interface HubClient {
   }): Promise<Run>;
   /** Add finished spec rows (+ evidence) to a running run; `done` closes it. */
   patchRun(id: string, body: PatchRunRequest): Promise<Run>;
+  /** `ciRunId` answers "which runs did this CI job create", whatever the window. */
   listRuns(q?: {
     project?: string;
     branch?: string;
     status?: RunStatus;
     kind?: Run["kind"];
+    ciRunId?: string;
     limit?: number;
   }): Promise<Run[]>;
   getRun(id: string): Promise<Run>;

package/dist/package.json

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

package/package.json

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