ccqa 1.21.0 → 1.23.0

package/dist/bin/ccqa.mjs

@@ -6842,10 +6842,26 @@ const SpecLedgerEntrySchema = z.object({
 	deployedSha: z.string().nullable().optional(),
 	deployedShaAmbiguous: z.boolean().optional()
 });
+/**
+* A red-bucket entry: where the failure happened, plus what it was. The cause
+* is copied off the run report's `analysis` so a reader learns why a spec is
+* red without fetching the report of every red spec.
+*
+* Only the red bucket carries it. A pass has no cause, so putting these on
+* `SpecLedgerEntry` would invite writing them where they cannot exist.
+*
+* Both fields are optional and mean the same thing by their absence — nothing
+* is on record. Failure analysis is opt-in (`--on-fail-explain`), and entries
+* written before this release have neither field.
+*/
+const SpecRedLedgerEntrySchema = SpecLedgerEntrySchema.extend({
+	label: PredictedLabelSchema.optional(),
+	headline: z.string().optional()
+});
 z.object({
 	green: z.record(z.string(), SpecLedgerEntrySchema).default({}),
 	run: z.record(z.string(), SpecLedgerEntrySchema).default({}),
-	red: z.record(z.string(), SpecLedgerEntrySchema).default({})
+	red: z.record(z.string(), SpecRedLedgerEntrySchema).default({})
 });
 /** One deploy, as the consumer's deploy job reported it (ADR-0010). */
 const DeployEntrySchema = z.object({
@@ -7025,7 +7041,7 @@ const SpecRerunSchema = z.object({
 	heldBy: SpecLockSchema.nullable(),
 	lastRun: SpecLedgerEntrySchema.nullable(),
 	lastGreen: SpecLedgerEntrySchema.nullable(),
-	lastRed: SpecLedgerEntrySchema.nullable(),
+	lastRed: SpecRedLedgerEntrySchema.nullable(),
 	touchedBy: z.array(z.string()).optional(),
 	touchedByDeploy: DeployRefSchema.nullable().optional()
 });
@@ -7075,7 +7091,7 @@ z.object({
 z.object({
 	entries: z.record(z.string(), SpecLedgerEntrySchema),
 	lastRun: z.record(z.string(), SpecLedgerEntrySchema).default({}),
-	lastRed: z.record(z.string(), SpecLedgerEntrySchema).default({})
+	lastRed: z.record(z.string(), SpecRedLedgerEntrySchema).default({})
 });
 /**
 * One spec's last drift audit, as recorded by `ccqa audit --report-to-hub`. Unlike the
@@ -15299,16 +15315,18 @@ const DEFAULT_CONCURRENCY$1 = 3;
 * `cli/run` calls this with just the failing specs after vitest.
 */
 async function analyzeDrift(input) {
-	const { targets, cwd, blocks, concurrency = DEFAULT_CONCURRENCY$1, model, language, guidance, onSpecStart } = input;
+	const { targets, cwd, blocks, concurrency = DEFAULT_CONCURRENCY$1, model, language, guidance, onSpecStart, onSpecDone } = input;
 	return runPool(targets, concurrency, async (target) => {
 		onSpecStart?.(target);
-		return checkSpec(target, {
+		const result = await checkSpec(target, {
 			cwd,
 			blocks,
 			model,
 			language,
 			guidance
 		});
+		await onSpecDone?.(result);
+		return result;
 	});
 }
 async function checkSpec(target, opts) {
@@ -15497,37 +15515,35 @@ function specStatus(result, threshold) {
 	return "passed";
 }
 /**
-* Adapts `ccqa audit` results into the shared RunReportData shape so they can
-* be pushed to the hub (`ccqa audit --report-to-hub`) and rendered by the same report
-* UI as `ccqa run`/`ccqa live`. Browser-execution fields (testCounts,
-* evidence, liveRun, ...) don't apply to a drift audit and are always null —
-* which is why `mode` is carried separately: nothing ran, but which surfaces
-* were audited is still a fact about the row.
+* One audited spec as a report row. Browser-execution fields don't apply to an
+* audit and stay empty — which is why `mode` is carried separately: nothing
+* ran, but which surfaces were audited is still a fact about the row. The
+* diagnosis goes into `analysis` because for a `kind: "drift"` report the
+* diagnosis IS the row's verdict, so it renders through the same card a failed
+* `ccqa run` spec does.
 *
-* Each result's diagnosis goes into `analysis`: for a `kind: "drift"` report
-* the diagnosis IS the row's verdict, so it renders through the same diagnosis
-* card a failed `ccqa run` spec does. `reasoning` has no drift-audit
-* equivalent (the audit gives one headline, not a deliberation) so it is
-* filled with an empty string to satisfy `FailureAnalysisSchema`.
+* Shared by the incremental push and the final report: the hub upserts by
+* feature/spec, so two mappings would let the closing patch rewrite history.
 */
-function driftResultsToReport(results, meta) {
-	const specResults = results.map((result) => ({
-		feature: result.target.featureName,
-		spec: result.target.specName,
-		title: result.title ?? null,
+function driftResultToRow(result, threshold) {
+	return {
+		...emptySpecRow({
+			feature: result.target.featureName,
+			spec: result.target.specName,
+			title: result.title ?? null,
+			status: specStatus(result, threshold)
+		}),
 		...result.live === void 0 ? {} : { mode: result.live ? "live" : "deterministic" },
-		status: specStatus(result, meta.threshold),
-		testCounts: null,
-		durationMs: null,
-		assertions: null,
-		analysis: result.drift ? result.drift : null,
-		analysisSkipped: null,
-		failureLogExcerpt: null,
-		diffExcerpt: null,
-		specYaml: null,
-		evidence: null,
-		liveRun: null
-	}));
+		analysis: result.drift ?? null
+	};
+}
+/**
+* Adapts `ccqa audit` results into the shared RunReportData shape so they can
+* be pushed to the hub (`ccqa audit --report-to-hub`) and rendered by the same
+* report UI as `ccqa run`/`ccqa live`.
+*/
+function driftResultsToReport(results, meta) {
+	const specResults = results.map((result) => driftResultToRow(result, meta.threshold));
 	return {
 		schemaVersion: 1,
 		kind: "drift",
@@ -15807,8 +15823,13 @@ async function runAudit(specPath, opts) {
 	requireReportToHubConnection(opts);
 	let results;
 	let promptCtx;
+	let push = null;
 	try {
 		promptCtx = await resolveAuditPromptContext(opts, cwd);
+		if (opts.reportToHub) {
+			push = await openDriftPush(opts, cwd);
+			if (format === "text") info(`hub: incremental drift run opened (${push.runId})`);
+		}
 		results = await analyzeDrift({
 			targets,
 			cwd,
@@ -15819,16 +15840,18 @@ async function runAudit(specPath, opts) {
 			guidance: promptCtx.guidance,
 			onSpecStart: (t) => {
 				if (format === "text") info(`checking ${t.featureName}/${t.specName}`);
+			},
+			onSpecDone: async (r) => {
+				if (push) await sendDriftRow(push, r, threshold);
 			}
 		});
 	} finally {
 		if (holder) await releaseSpecs(hub, hubProject, opts.hubProfile, holder);
 	}
 	process.stdout.write(renderDrift(results, format, cwd));
-	if (opts.reportToHub) await pushDriftResults({
+	if (push) await sealDriftPush(push, {
 		results,
 		threshold,
-		cwd,
 		opts,
 		format,
 		baseRef,
@@ -15877,59 +15900,92 @@ function requireReportToHubConnection(opts) {
 	process.exit(2);
 }
 /**
-* Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
-* shows up alongside `ccqa run` runs in the hub UI. A missing hub connection
-* is a usage error, not a silent skip — a CI job that asked to publish and
-* did not must say so.
+* Open the drift run this sweep patches into. A failure here is fatal, as it
+* is for `ccqa run`: a job that asked to publish and cannot reach the hub has
+* not done what it was told, and the audit has no local artifact to fall back
+* on — the hub is its only output. Raised before any spec is checked, so
+* nothing is wasted. Not retried: a dropped response after the hub committed
+* would leave a second orphan running run.
 *
-* `resolveHub` is injectable so tests can supply a fake `HubClient` without
-* a real hub connection; it defaults to the real flag/env resolution.
+* `resolveHub` is injectable for tests.
 */
-async function pushDriftResults(args, resolveHub = resolveHubClient) {
-	const { results, threshold, cwd, opts, format, baseRef, promptCtx } = args;
+async function openDriftPush(opts, cwd, resolveHub = resolveHubClient) {
 	const hub = resolveHub(opts);
-	if (!hub) {
-		error("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-		process.exit(2);
+	if (!hub) throw new RunUsageError("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	const project = resolveProject({
+		project: opts.project,
+		cwd
+	});
+	const [branch, gitHead] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
+	const ciRunId = githubRunId();
+	const runUrl = githubRunUrl();
+	try {
+		return {
+			hub,
+			runId: (await hub.openRun({
+				project,
+				kind: "drift",
+				...branch ? { branch } : {},
+				...opts.hubProfile ? { profile: opts.hubProfile } : {},
+				...gitHead ? { gitHead } : {},
+				...ciRunId ? { ciRunId } : {},
+				...runUrl ? { runUrl } : {}
+			})).id,
+			gitHead
+		};
+	} catch (err) {
+		throw new RunUsageError(`--report-to-hub: could not open a run on the hub (${errMessage(err)})`);
 	}
+}
+/**
+* Send one finished spec. A failure is warned and swallowed rather than
+* thrown: the seal resends every row, so a dropped patch costs freshness for
+* the rest of the sweep, not the record.
+*/
+async function sendDriftRow(push, result, threshold) {
 	try {
-		const project = resolveProject({
-			project: opts.project,
-			cwd
+		await push.hub.patchRun(push.runId, {
+			rows: [driftResultToRow(result, threshold)],
+			reportMeta: { cost: currentReportCost() }
 		});
-		const [branch, head] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
-		const report = driftResultsToReport(results, {
-			threshold,
-			git: {
-				head,
-				base: baseRef ?? null
-			},
-			customPromptVersion: promptCtx?.customPromptVersion ?? null,
-			triageUserPromptHash: promptCtx?.triageUserPromptHash ?? null
+	} catch (err) {
+		warn(`hub: could not push ${result.target.featureName}/${result.target.specName}: ${errMessage(err)}`);
+	}
+}
+/**
+* Close the run with every row and the envelope metadata. Resends all rows
+* rather than only the unsent ones, so this one call also repairs any row
+* whose mid-sweep patch failed. Status is left to the hub, which derives it
+* from the rows.
+*/
+async function sealDriftPush(push, args) {
+	const { results, threshold, opts, format, baseRef, promptCtx } = args;
+	const report = driftResultsToReport(results, {
+		threshold,
+		git: {
+			head: push.gitHead,
+			base: baseRef ?? null
+		},
+		customPromptVersion: promptCtx?.customPromptVersion ?? null,
+		triageUserPromptHash: promptCtx?.triageUserPromptHash ?? null
+	});
+	try {
+		await push.hub.patchRun(push.runId, {
+			rows: report.results,
+			done: true,
+			reportMeta: {
+				git: report.git,
+				promptVersion: report.promptVersion,
+				customPromptVersion: report.customPromptVersion,
+				...report.triageUserPromptHash ? { triageUserPromptHash: report.triageUserPromptHash } : {},
+				cost: report.cost
+			}
 		});
-		const dir = await mkdtemp(join(tmpdir(), "ccqa-drift-push-"));
-		try {
-			await writeFile(join(dir, "report.json"), JSON.stringify(report, null, 2), "utf8");
-			const archive = await packDirToTarGz(dir);
-			const run = await hub.pushRun(archive, {
-				project,
-				...branch ? { branch } : {},
-				kind: "drift"
-			});
-			if (format === "text") info(`pushed drift result to hub: ${(opts.hubUrl ?? process.env.CCQA_HUB_URL ?? "").replace(/\/+$/, "")}/#/runs/${run.id}`);
-		} finally {
-			await rm(dir, {
-				recursive: true,
-				force: true
-			});
-		}
 	} catch (err) {
-		if (err instanceof HubApiError) {
-			error(`hub request failed (${err.status} ${err.code}): ${err.message}`);
-			process.exit(2);
-		}
-		throw err;
+		error(`hub: could not close the drift run ${push.runId}: ${errMessage(err)}`);
+		process.exit(2);
 	}
+	if (format === "text") info(`pushed drift result to hub: ${(opts.hubUrl ?? process.env.CCQA_HUB_URL ?? "").replace(/\/+$/, "")}/#/runs/${push.runId}`);
 }
 /**
 * Adapts `AuditOptions` to `resolveHubContext`'s flat option shape. Unlike
@@ -16755,12 +16811,17 @@ function toLedger(raw) {
 }
 /** Fold `from` into `into` in place, per bucket and key, newest `at` winning. */
 function mergeLedgerInto(into, from) {
-	for (const name of BUCKET_NAMES) for (const [key, entry] of Object.entries(from[name])) {
-		const prev = into[name][key];
-		if (!prev || prev.at <= entry.at) into[name][key] = entry;
-	}
+	mergeBucket(into.green, from.green);
+	mergeBucket(into.run, from.run);
+	mergeBucket(into.red, from.red);
 	return into;
 }
+function mergeBucket(into, from) {
+	for (const [key, entry] of Object.entries(from)) {
+		const prev = into[key];
+		if (!prev || prev.at <= entry.at) into[key] = entry;
+	}
+}
 //#endregion
 //#region src/hub/api/validate.ts
 /**
@@ -16971,7 +17032,7 @@ async function updateSpecLedger(storage, run, results) {
 		const key = `${row.feature}/${row.spec}`;
 		ledger.run[key] = entry;
 		if (row.status === "passed") ledger.green[key] = entry;
-		else ledger.red[key] = entry;
+		else ledger.red[key] = redEntry(entry, row);
 	}
 	if (Object.keys(ledger.run).length === 0) return;
 	try {
@@ -16981,6 +17042,23 @@ async function updateSpecLedger(storage, run, results) {
 	}
 }
 /**
+* The red bucket's entry: the coordinate every bucket carries, plus what the
+* failure analysis concluded, so a reader of the ledger learns why a spec is
+* red without fetching its report.
+*
+* A field with nothing behind it is left out rather than written empty:
+* `analysis` is null when the run did not ask for one (`--on-fail-explain` is
+* opt-in), and a model that answered with no headline leaves `headline` "".
+*/
+function redEntry(entry, row) {
+	if (!row.analysis) return entry;
+	return {
+		...entry,
+		label: row.analysis.label,
+		...row.analysis.headline ? { headline: row.analysis.headline } : {}
+	};
+}
+/**
 * Advance the drift ledger from a terminal `kind: "drift"` run: each row's
 * `analysis` (the diagnosis `driftResultsToReport` put there) becomes that
 * spec's newest audit entry. No profile — drift asks whether the spec still
@@ -17119,23 +17197,20 @@ function createPatchRunHandler(config) {
 			};
 		});
 		if (evidence) for (const [relPath, b64] of Object.entries(evidence)) await config.storage.artifacts.putFile(id, relPath, Buffer.from(b64, "base64"));
-		const patch = done ? {
-			status: finalStatus ?? (specs.failed > 0 ? "failed" : "passed"),
+		const patch = {
 			specs,
 			costUsd,
 			...run.kind === "drift" ? { drift: summarizeDrift(mergedResults) } : {},
-			...reportMeta?.git?.head ? { gitHead: reportMeta.git.head } : {},
-			...reportMeta?.promptVersion ? { promptVersion: reportMeta.promptVersion } : {},
-			...await deployHeadMovedDuringRun(config.storage, run) ? { deployedShaAmbiguous: true } : {}
-		} : {
-			specs,
-			costUsd
+			...done ? {
+				status: finalStatus ?? (specs.failed > 0 ? "failed" : "passed"),
+				...reportMeta?.git?.head ? { gitHead: reportMeta.git.head } : {},
+				...reportMeta?.promptVersion ? { promptVersion: reportMeta.promptVersion } : {},
+				...await deployHeadMovedDuringRun(config.storage, run) ? { deployedShaAmbiguous: true } : {}
+			} : {}
 		};
 		const updated = await config.storage.runs.update(id, patch);
-		if (done) {
-			await updateSpecLedger(config.storage, updated, mergedResults);
-			await updateDriftLedger(config.storage, updated, mergedResults);
-		}
+		await updateDriftLedger(config.storage, updated, mergedResults);
+		if (done) await updateSpecLedger(config.storage, updated, mergedResults);
 		sendJson(ctx.res, 200, updated);
 	};
 }
@@ -22205,6 +22280,17 @@ const CLIENT_JS = `
     badge.appendChild(document.createTextNode(" " + t("perspectives.run.state." + runState)));
     td.appendChild(badge);
 
+    // What the failure was, as the run's analysis called it — the same place
+    // the audit column names its drift label. Absent on a red entry the run
+    // never analyzed, and on entries written before the ledger carried it.
+    if (runState === "failed" && rr.lastRed && rr.lastRed.label) {
+      var cause = el("span", "cellsub", labelText(rr.lastRed.label));
+      // The one-line conclusion, for a pointer. The detail panel shows it in
+      // full, so nothing here depends on finding it.
+      if (rr.lastRed.headline) cause.title = rr.lastRed.headline;
+      td.appendChild(cause);
+    }
+
     // The sub-line is the coordinate of the result being reported — the same
     // "when is this from" evidence the audit column carries above, so the two
     // axes read as siblings. Why the currency matters belongs to the verdict
@@ -22423,6 +22509,21 @@ const CLIENT_JS = `
     return wrap;
   }
 
+  // The failure: which run it was, then what the analysis concluded. The
+  // headline is model output, already localized server-side, so it is shown as
+  // written. A run made without failure analysis carries neither field, and the
+  // row is then the coordinate alone — what it has always been.
+  function rerunFailureValue(entry) {
+    var wrap = el("div");
+    wrap.appendChild(ledgerLine(entry));
+    if (entry.label) {
+      var line = el("div", "d-prose", labelText(entry.label));
+      if (entry.headline) line.appendChild(document.createTextNode(" · " + entry.headline));
+      wrap.appendChild(line);
+    }
+    return wrap;
+  }
+
   // Detail row: a definition list of the case's fields plus the note editor.
   // Built with createElement/textContent throughout — every field here is
   // API-derived, so none of it may go through innerHTML.
@@ -22456,7 +22557,7 @@ const CLIENT_JS = `
     var rr = ledgerEntryFor(perspState.rerun, feature, spec);
     if (rr) {
       row(rerunEvidenceLabelKey(rr), rerunEvidenceValue(rr));
-      if (rerunHasFailure(rr)) row("perspectives.d.lastRed", ledgerLine(rr.lastRed));
+      if (rerunHasFailure(rr)) row("perspectives.d.lastRed", rerunFailureValue(rr.lastRed));
     }
     frag.appendChild(dl);
 

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

@@ -314,6 +314,14 @@ declare const RerunReportSchema: z.ZodObject<{
       at: z.ZodString;
       deployedSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       deployedShaAmbiguous: z.ZodOptional<z.ZodBoolean>;
+      label: z.ZodOptional<z.ZodEnum<{
+        TEST_DRIFT: "TEST_DRIFT";
+        SPEC_CHANGE: "SPEC_CHANGE";
+        PRODUCT_BUG: "PRODUCT_BUG";
+        ENVIRONMENT: "ENVIRONMENT";
+        UNKNOWN: "UNKNOWN";
+      }>>;
+      headline: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     touchedBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
     touchedByDeploy: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/package.json

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