ccqa 1.24.0 → 1.25.0

package/dist/bin/ccqa.mjs

@@ -3115,12 +3115,29 @@ const NO_DRIFT_CAUSE = "NO_DRIFT";
 const DRIFT_ACTUAL_CAUSES = [...DRIFT_FAILURE_CAUSES, NO_DRIFT_CAUSE];
 const ACTUAL_CAUSES = [...FAILURE_CAUSES, NO_DRIFT_CAUSE];
 const ActualCauseSchema = z.enum(ACTUAL_CAUSES);
+/**
+* Report rows come in kinds, and each answers fewer questions than the last.
+* A "record" row answers none: it says a recording happened and what it cost,
+* and nothing was judged, so both vocabularies below are empty for it.
+*
+* The one source for the vocabulary: the report envelope, the hub's
+* `Run.kind` and the `?kind=` query params all derive from this enum, so a
+* fourth kind cannot be half-added. What a kind that judges nothing may and
+* may not advance is ADR-0017.
+*/
+const ReportKindSchema = z.enum([
+	"run",
+	"drift",
+	"record"
+]);
 /** What a person may record on a row of this kind. */
 function causesForKind(kind) {
+	if (kind === "record") return [];
 	return kind === "drift" ? DRIFT_ACTUAL_CAUSES : FAILURE_CAUSES;
 }
 /** What the model may answer on a row of this kind. */
 function predictedForKind(kind) {
+	if (kind === "record") return [];
 	return kind === "drift" ? [...DRIFT_FAILURE_CAUSES, "UNKNOWN"] : PREDICTED_LABELS;
 }
 const SUB_DIAGNOSES = [...FIXABLE_DIAGNOSIS_TYPES, "NONE"];
@@ -3146,6 +3163,20 @@ const FailureEvidenceSchema = z.object({
 */
 const DriftSurfaceSchema = z.enum(["spec", "generated"]);
 /**
+* Which repair a `SPEC_CHANGE` needs: `FEATURE_REMOVED` means the behaviour
+* the spec checks is gone from the code, so the spec goes with it;
+* `BEHAVIOUR_CHANGED` means it still exists but works differently, so the spec
+* is rewritten and re-recorded.
+*
+* A fourth axis rather than a `subDiagnosis` value, because that vocabulary is
+* `[...FIXABLE_DIAGNOSIS_TYPES, "NONE"]` — the shapes a machine knows how to
+* repair — so a spec change always lands on `NONE` there.
+*
+* Deliberately without an "unknown" member: absence carries it, and every
+* reader must treat an absent value as a call to leave to a human.
+*/
+const SpecChangeKindSchema = z.enum(["FEATURE_REMOVED", "BEHAVIOUR_CHANGED"]);
+/**
 * LLM output shape. Deliberately NOT .strict(): the model occasionally adds
 * keys, and rejecting the whole analysis over an extra field would collapse
 * a usable prediction into UNKNOWN. Zod's default strips unknown keys.
@@ -3162,7 +3193,8 @@ const FailureAnalysisSchema = z.object({
 	recommendation: z.string().default(""),
 	evidence: z.array(FailureEvidenceSchema),
 	reasoning: z.string(),
-	surface: DriftSurfaceSchema.optional()
+	surface: DriftSurfaceSchema.optional(),
+	specChangeKind: SpecChangeKindSchema.optional()
 });
 /**
 * What a drift audit may conclude, in the same vocabulary `ccqa run
@@ -3201,11 +3233,33 @@ const DriftDiagnosisSchema = z.object({
 	confidence: z.number().min(0).max(1),
 	surface: DriftSurfaceSchema.default("spec"),
 	subDiagnosis: DriftSubDiagnosisSchema.default("NONE"),
+	specChangeKind: SpecChangeKindSchema.optional(),
 	headline: z.string(),
 	recommendation: z.string().default(""),
 	evidence: z.array(FailureEvidenceSchema),
 	reasoning: z.string().default("")
 });
+/**
+* `specChangeKind` names which repair a `SPEC_CHANGE` needs, so under any other
+* label it is dropped. Dropped rather than rejected — a stray value must not
+* cost an otherwise usable verdict.
+*
+* Two producers apply it. `ccqa audit` normalizes at the parse boundary
+* (`src/drift/analyze.ts`), so every consumer of a verdict it produced — the
+* JSON output, the report rows, the hub push — is clean by construction. The
+* hub normalizes rows on the way into the drift ledger, which is what a
+* foreign client's push passes through.
+*
+* What does NOT hold: a pushed report's stored archive is kept verbatim and
+* served back unchanged, so a row a foreign client wrote can still carry a
+* stray field. That is why the UI re-checks the label before rendering the
+* chip rather than trusting the stored row.
+*/
+function normalizeDiagnosis(diagnosis) {
+	if (diagnosis.label === "SPEC_CHANGE" || diagnosis.specChangeKind === void 0) return diagnosis;
+	const { specChangeKind: _dropped, ...rest } = diagnosis;
+	return rest;
+}
 const ReportAssertionSchema = z.object({
 	name: z.string(),
 	status: z.enum([
@@ -3359,7 +3413,7 @@ const GitEnvelopeSchema = z.object({
 });
 const RunReportDataSchema = z.object({
 	schemaVersion: z.literal(1),
-	kind: z.enum(["run", "drift"]).default("run"),
+	kind: ReportKindSchema.default("run"),
 	createdAt: z.string(),
 	runId: z.string().nullable(),
 	runUrl: z.string().nullable().optional(),
@@ -6738,7 +6792,7 @@ z.object({
 	profile: z.string().nullable(),
 	branch: z.string().nullable(),
 	status: RunStatusSchema,
-	kind: z.enum(["run", "drift"]).default("run"),
+	kind: ReportKindSchema.default("run"),
 	drift: z.object({
 		specs: z.number(),
 		testDrift: z.number(),
@@ -7108,6 +7162,7 @@ z.object({
 const SpecDriftEntrySchema = z.object({
 	label: DriftLabelSchema.nullable(),
 	surface: DriftSurfaceSchema.optional(),
+	specChangeKind: SpecChangeKindSchema.optional(),
 	confidence: z.number().optional(),
 	headline: z.string().optional(),
 	gitHead: z.string(),
@@ -7158,6 +7213,24 @@ const CreateLearningJobRequestSchema = z.object({
 	profile: z.string(),
 	runLimit: z.number().int().positive().max(1e3).optional()
 });
+const MAX_ACK_KEYS = 5e3;
+const MAX_ACK_KEY_LENGTH = 256;
+/**
+* A named set of opaque keys a consumer has already acted on, as stored (see
+* `AckStore`). `at` is null only for a set that was never written — an ack
+* nobody has recorded yet reads as empty rather than missing.
+*/
+const AckSchema = z.object({
+	keys: z.array(z.string()),
+	at: z.string().nullable()
+});
+/** Body of `PUT /projects/:project/acks/:name?profile=` — the whole set, not a delta. */
+const PutAckRequestSchema = z.object({ keys: z.array(z.string().min(1).max(MAX_ACK_KEY_LENGTH)).max(MAX_ACK_KEYS) });
+AckSchema.extend({
+	project: z.string(),
+	profile: z.string(),
+	name: z.string()
+});
 //#endregion
 //#region src/run/hub-selection.ts
 /**
@@ -10993,14 +11066,9 @@ async function generateAgentBrowserTest(ctx) {
 	blank();
 	const agentBrowserSession = fix.useSnapshot ? `ccqa-generate-${Date.now()}` : void 0;
 	const runVitestForSession = (path) => runVitest(path, agentBrowserSession);
-	let signalHandler = null;
 	if (agentBrowserSession) {
 		await closeSession(agentBrowserSession);
-		signalHandler = () => {
-			closeSession(agentBrowserSession).finally(() => process.exit(130));
-		};
-		process.once("SIGINT", signalHandler);
-		process.once("SIGTERM", signalHandler);
+		ctx.teardown?.trackSession(agentBrowserSession);
 	}
 	try {
 		const initialRun = await timedPhase("vitest run #1", () => runVitestForSession(scriptPath), "run");
@@ -11027,11 +11095,10 @@ async function generateAgentBrowserTest(ctx) {
 			passed
 		};
 	} finally {
-		if (signalHandler) {
-			process.off("SIGINT", signalHandler);
-			process.off("SIGTERM", signalHandler);
+		if (agentBrowserSession) {
+			ctx.teardown?.untrackSession(agentBrowserSession);
+			await closeSession(agentBrowserSession);
 		}
-		if (agentBrowserSession) await closeSession(agentBrowserSession);
 	}
 }
 /**
@@ -11836,6 +11903,75 @@ function createIncrementalReport(reportDir, envelope, sink, costNow) {
 	};
 }
 //#endregion
+//#region src/cli/open-hub-run.ts
+/** The one wording for "this flag needs a hub, and none is configured". */
+function needsHubConnection(flag) {
+	return `${flag} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`;
+}
+const REPORT_TO_HUB_NEEDS_CONNECTION = needsHubConnection("--report-to-hub");
+/**
+* The connection a `--report-to-hub` command publishes through. Both CLI
+* callers check this before the expensive part — the audit's sweep, the
+* recording's spec lock and browser — so a job that cannot publish spends
+* nothing finding out.
+*/
+function requireReportToHubConnection(conn) {
+	if (conn) return conn;
+	error(REPORT_TO_HUB_NEEDS_CONNECTION);
+	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.
+*/
+async function openHubRun(kind, conn, cwd, profile) {
+	const [branch, gitHead] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
+	const ciRunId = githubRunId();
+	const runUrl = githubRunUrl();
+	try {
+		const run = await conn.hub.openRun({
+			project: conn.project,
+			kind,
+			...branch ? { branch } : {},
+			...profile ? { profile } : {},
+			...gitHead ? { gitHead } : {},
+			...ciRunId ? { ciRunId } : {},
+			...runUrl ? { runUrl } : {}
+		});
+		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)})`);
+	}
+}
+/**
+* Close an open run with its final rows and envelope, answering whether it
+* closed. A failed seal leaves the run `running` with whatever rows landed — a
+* wrong record, not merely a missing one — so a CLI caller must not exit clean.
+* The exit is the caller's to make rather than taken here: `ccqa record` seals
+* from inside a teardown finalizer, and exiting there would skip the
+* browser-session reap queued behind it.
+*/
+async function sealHubRun(push, body) {
+	try {
+		await push.hub.patchRun(push.runId, {
+			...body,
+			done: true
+		});
+		return true;
+	} catch (err) {
+		error(`hub: could not close the ${push.kind} run ${push.runId}: ${errMessage(err)}`);
+		return false;
+	}
+}
+//#endregion
 //#region src/prompts/agent-update.ts
 /**
 * Build the prompts used by the `--learn-*-prompt` flags to refresh
@@ -12373,9 +12509,9 @@ async function executeRun(targets, opts) {
 	});
 	if (wantsLastGreen && hubCtx == null) throw new RunUsageError("--on-fail-explain needs a hub connection for the per-spec last-green baselines (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN), or an explicit --on-fail-explain-base <ref>");
 	const ledgerHub = wantsLastGreen ? hubCtx : null;
-	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError("--only-hub-rerun-needed requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-	if (opts.reportToHub && hubCtx == null) throw new RunUsageError("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-	if (opts.learnHubLivePrompt && hubCtx == null) throw new RunUsageError("--learn-hub-live-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError(needsHubConnection("--only-hub-rerun-needed"));
+	if (opts.reportToHub && hubCtx == null) throw new RunUsageError(REPORT_TO_HUB_NEEDS_CONNECTION);
+	if (opts.learnHubLivePrompt && hubCtx == null) throw new RunUsageError(needsHubConnection("--learn-hub-live-prompt"));
 	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead] = await Promise.all([
 		forExecution ? fetchCustomPrompt(hubCtx) : null,
 		forExecution ? fetchTriageUserPrompt(hubCtx) : null,
@@ -13137,7 +13273,16 @@ async function streamFiltered(source, sink, capture) {
 function createRunTeardown() {
 	const sessions = /* @__PURE__ */ new Set();
 	const finalizers = [];
-	let torn = false;
+	let running = null;
+	const tearDown = async () => {
+		for (const fn of finalizers) try {
+			await fn();
+		} catch (err) {
+			warn(`teardown finalizer failed (partial report may be incomplete): ${err instanceof Error ? err.message : String(err)}`);
+		}
+		await Promise.all([...sessions].map((name) => closeSession(name)));
+		sessions.clear();
+	};
 	return {
 		trackSession(name) {
 			sessions.add(name);
@@ -13148,24 +13293,18 @@ function createRunTeardown() {
 		onFinalize(fn) {
 			finalizers.push(fn);
 		},
-		async run() {
-			if (torn) return;
-			torn = true;
-			for (const fn of finalizers) try {
-				await fn();
-			} catch (err) {
-				warn(`teardown finalizer failed (partial report may be incomplete): ${err instanceof Error ? err.message : String(err)}`);
-			}
-			await Promise.all([...sessions].map((name) => closeSession(name)));
-			sessions.clear();
+		run() {
+			running ??= tearDown();
+			return running;
 		}
 	};
 }
 /**
 * Install SIGINT/SIGTERM handlers that run {@link RunTeardown.run} then exit
 * with the conventional signal code, and return a disposer that removes them.
-* Mirrors the pattern in `src/targets/agent-browser/generate.ts`. A second
-* signal while tearing down hard-exits immediately rather than waiting.
+* A command must install at most one: a second handler that also exits would
+* race this one and could terminate mid-finalizer. A second signal while
+* tearing down hard-exits immediately rather than waiting.
 */
 function installTeardownSignalHandlers(teardown) {
 	let handling = false;
@@ -14691,8 +14830,11 @@ function parseAutoFixFlag(raw) {
 * The `generate` flow shared by `ccqa generate` and the codegen half of
 * `ccqa record`: resolve the spec's target plugin, load its input (the
 * recording, for input:"recording" targets), and dispatch to the plugin.
-* This layer owns the CLI concerns — overwrite confirmation, logging,
-* exit-code policy — while the plugin owns the generation pipeline.
+* This layer owns the CLI concerns — overwrite confirmation, logging — while
+* the plugin owns the generation pipeline. A generation whose output still
+* fails is reported as `{ passed: false }` rather than thrown or exited: both
+* callers have work left that `process.exit` would skip — `ccqa record
+* --report-to-hub` still has to seal the run holding what the retries cost.
 */
 async function runGenerate(featureName, specName, opts) {
 	header("generate", `${featureName}/${specName}`);
@@ -14700,7 +14842,7 @@ async function runGenerate(featureName, specName, opts) {
 	await ensureCcqaDir(cwd);
 	const releaseLock = await acquireSpecLock(featureName, specName, "generate", cwd);
 	try {
-		await runGenerateLocked(featureName, specName, opts, cwd);
+		return await runGenerateLocked(featureName, specName, opts, cwd);
 	} finally {
 		await releaseLock();
 	}
@@ -14731,7 +14873,7 @@ async function runGenerateLocked(featureName, specName, opts, cwd) {
 	if (existingOutput && !opts.force) {
 		if (!await confirmOverwrite(existingOutput)) {
 			info("aborted; pass --overwrite to replace it without prompting");
-			return;
+			return { passed: true };
 		}
 	}
 	let recording;
@@ -14760,15 +14902,14 @@ async function runGenerateLocked(featureName, specName, opts, cwd) {
 			maxRetries: opts.maxRetries,
 			mode: opts.fixMode,
 			useSnapshot: opts.useSnapshot
-		}
+		},
+		teardown: opts.teardown
 	};
 	const result = await target.generate(ctx);
 	if (opts.updateAgentPrompt) await runGenerateAgentPromptUpdate(target, featureName, specName, result, opts, cwd);
-	if (!result.passed) {
-		warn("auto-fix exhausted; test still failing");
-		process.exit(1);
-	}
-	hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+	if (!result.passed) warn("auto-fix exhausted; test still failing");
+	else hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+	return { passed: result.passed };
 }
 /**
 * `ccqa generate --learn-hub-codegen-prompt`: refresh the target's learned
@@ -14838,15 +14979,18 @@ async function runGenerateCli(specPath, opts) {
 		cwd
 	});
 	if (opts.learnHubCodegenPrompt && hubClient === null) {
-		error("--learn-hub-codegen-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		error(needsHubConnection("--learn-hub-codegen-prompt"));
 		process.exit(2);
 	}
 	const hubContext = hubClient && project ? {
 		hub: hubClient,
 		project
 	} : null;
+	const teardown = createRunTeardown();
+	const disposeSignalHandlers = installTeardownSignalHandlers(teardown);
+	let passed;
 	try {
-		await runGenerate(featureName, specName, {
+		({passed} = await runGenerate(featureName, specName, {
 			maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
 			fixMode: toFixMode(opts.autoFix ?? "interactive"),
 			force: opts.overwrite ?? false,
@@ -14856,15 +15000,20 @@ async function runGenerateCli(specPath, opts) {
 			targetOverride: opts.target,
 			cwd,
 			hubContext,
-			updateAgentPrompt: opts.learnHubCodegenPrompt ?? false
-		});
+			updateAgentPrompt: opts.learnHubCodegenPrompt ?? false,
+			teardown
+		}));
 	} catch (e) {
 		if (e instanceof SpecLockedError) {
 			error(e.message);
 			process.exit(2);
 		}
 		throw e;
+	} finally {
+		await teardown.run();
+		disposeSignalHandlers();
 	}
+	if (!passed) process.exit(1);
 }
 //#endregion
 //#region src/cli/record.ts
@@ -14872,7 +15021,7 @@ const VALIDATION_MODES = ["lenient", "strict"];
 const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
-}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("record", () => runRecord(specPath, opts));
 }));
 async function runRecord(specPath, opts) {
@@ -14911,9 +15060,10 @@ async function runRecord(specPath, opts) {
 		project: hubProject
 	} : null;
 	if (opts.learnHubTracePrompt && hubContext === null) {
-		error("--learn-hub-trace-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		error(needsHubConnection("--learn-hub-trace-prompt"));
 		process.exit(2);
 	}
+	const pushConn = opts.reportToHub ? requireReportToHubConnection(hubContext) : null;
 	const releaseLock = await acquireSpecLock(featureName, specName, "record", cwdForProfile).catch((e) => {
 		if (e instanceof SpecLockedError) {
 			error(e.message);
@@ -14921,37 +15071,78 @@ async function runRecord(specPath, opts) {
 		}
 		throw e;
 	});
-	let traceResult = null;
+	const push = pushConn ? await openHubRun("record", pushConn, cwdForProfile, opts.hubProfile) : null;
+	if (push) info(`hub: record run opened (${push.runId})`);
+	let recorded = false;
+	let sealed = true;
+	const teardown = createRunTeardown();
+	teardown.onFinalize(async () => {
+		if (push) sealed = await sealRecordPush(push, featureName, specName, recorded);
+	});
+	const disposeSignalHandlers = installTeardownSignalHandlers(teardown);
 	try {
-		traceResult = await runTrace(featureName, specName, opts.model, opts.traceValidation ?? "lenient", language, {
-			cwd: cwdForProfile,
-			hubContext
-		});
-		blank();
-		if (!opts.traceOnly) await runGenerate(featureName, specName, {
-			maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
-			fixMode: toFixMode(opts.autoFix ?? "interactive"),
-			force: opts.overwrite ?? false,
-			useSnapshot: opts.sessionPin !== false,
-			language,
-			model: opts.model,
-			cwd: cwdForProfile,
-			hubContext
-		});
+		let traceResult = null;
+		let generated = true;
+		try {
+			traceResult = await runTrace(featureName, specName, opts.model, opts.traceValidation ?? "lenient", language, {
+				cwd: cwdForProfile,
+				hubContext
+			});
+			blank();
+			if (!opts.traceOnly) generated = (await runGenerate(featureName, specName, {
+				maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
+				fixMode: toFixMode(opts.autoFix ?? "interactive"),
+				force: opts.overwrite ?? false,
+				useSnapshot: opts.sessionPin !== false,
+				language,
+				model: opts.model,
+				cwd: cwdForProfile,
+				hubContext,
+				teardown
+			})).passed;
+		} finally {
+			await releaseLock();
+		}
+		if (opts.learnHubTracePrompt && traceResult !== null) {
+			blank();
+			await updateAgentPrompt({
+				kind: "record",
+				flag: "--learn-hub-trace-prompt",
+				runSummary: buildRecordRunSummary(featureName, specName, traceResult),
+				hubContext,
+				...opts.model ? { model: opts.model } : {},
+				...language ? { language } : {}
+			});
+		}
+		recorded = generated;
 	} finally {
-		await releaseLock();
-	}
-	if (opts.learnHubTracePrompt && traceResult !== null) {
-		blank();
-		await updateAgentPrompt({
-			kind: "record",
-			flag: "--learn-hub-trace-prompt",
-			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
-			hubContext,
-			...opts.model ? { model: opts.model } : {},
-			...language ? { language } : {}
-		});
+		await teardown.run();
+		disposeSignalHandlers();
 	}
+	if (!sealed) process.exit(2);
+	if (!recorded) process.exit(1);
+}
+/**
+* Close the record run with the one row this command produced, answering
+* whether it closed. One spec is recorded per invocation, so one row is the
+* whole run — enough for the runs list to say what the money bought.
+*/
+async function sealRecordPush(push, featureName, specName, recorded) {
+	return sealHubRun(push, {
+		rows: [emptySpecRow({
+			feature: featureName,
+			spec: specName,
+			title: null,
+			status: recorded ? "passed" : "failed"
+		})],
+		reportMeta: {
+			git: {
+				head: push.gitHead,
+				base: null
+			},
+			cost: currentReportCost()
+		}
+	});
 }
 /**
 * Compact summary of the trace pass for the record agent-prompt refresh.
@@ -15175,6 +15366,7 @@ Drift found:
     "confidence": 0.0,
     "surface": "spec" | "generated",
     "subDiagnosis": "SELECTOR_DRIFT" | "OVER_ASSERTION" | "NONE",
+    "specChangeKind": "FEATURE_REMOVED" | "BEHAVIOUR_CHANGED",
     "headline": "<one line: what is out of sync>",
     "recommendation": "<what to change to bring them back in sync>",
     "reasoning": "<how you reached this label: what you looked for, what you found, why it is this label and not the other>",
@@ -15186,6 +15378,13 @@ Drift found:
 \`\`\`
 
 \`subDiagnosis\`: \`SELECTOR_DRIFT\` when a selector or string was renamed, \`OVER_ASSERTION\` when the spec asserts something narrower than the product ever promised, \`NONE\` otherwise.
+
+\`specChangeKind\`: set it only when the label is \`SPEC_CHANGE\`, and omit the field entirely otherwise. It says which repair the spec needs — deleting it, or rewriting and re-recording it:
+
+- \`FEATURE_REMOVED\` — the code no longer implements the behaviour at all: removed, moved elsewhere, or deliberately disabled. This is the stronger claim, so earn it: your evidence must point at where the implementation would be if it still existed.
+- \`BEHAVIOUR_CHANGED\` — the behaviour is still there, but its wording, its route, or the conditions it runs under moved.
+
+When the evidence does not support "gone", answer \`BEHAVIOUR_CHANGED\`. When neither reading is supported, omit the field — there is no value for "I cannot tell", and a human decides what you leave unsaid.
 `;
 }
 function buildDriftUserPrompt(artifacts) {
@@ -15366,10 +15565,11 @@ async function checkSpec(target, opts) {
 			continue;
 		}
 		try {
+			const reply = DriftReplySchema.parse(JSON.parse(json));
 			return {
 				target,
 				ok: true,
-				drift: DriftReplySchema.parse(JSON.parse(json)).drift,
+				drift: reply.drift ? normalizeDiagnosis(reply.drift) : null,
 				live: artifacts.live,
 				title: artifacts.title
 			};
@@ -15503,7 +15703,7 @@ function determineExitCode(results, threshold) {
 //#endregion
 //#region src/drift/to-report.ts
 /** Tracks the drift prompt's own version — the two must never drift apart. */
-const DRIFT_REPORT_PROMPT_VERSION = "5";
+const DRIFT_REPORT_PROMPT_VERSION = "6";
 /**
 * Spec-level status under the given threshold, mirroring determineExitCode's
 * per-spec logic (exit-code.ts) but scoped to a single SpecResult.
@@ -15536,7 +15736,7 @@ function driftResultToRow(result, threshold) {
 			status: specStatus(result, threshold)
 		}),
 		...result.live === void 0 ? {} : { mode: result.live ? "live" : "deterministic" },
-		analysis: result.drift ?? null
+		analysis: result.drift
 	};
 }
 /**
@@ -15822,14 +16022,24 @@ async function runAudit(specPath, opts) {
 		if (targets.length === 0) exitWithNoSpecs(format, "noDiffIntersection", "no specs intersect the changed file set; nothing to check");
 	}
 	const blocks = await loadAvailableBlocks(cwd);
-	requireReportToHubConnection(opts);
+	let pushConn = null;
+	if (opts.reportToHub) {
+		const pushHub = resolveHubClient(opts);
+		pushConn = requireReportToHubConnection(pushHub && {
+			hub: pushHub,
+			project: resolveProject({
+				project: opts.project,
+				cwd
+			})
+		});
+	}
 	let results;
 	let promptCtx;
 	let push = null;
 	try {
 		promptCtx = await resolveAuditPromptContext(opts, cwd);
-		if (opts.reportToHub) {
-			push = await openDriftPush(opts, cwd);
+		if (pushConn) {
+			push = await openHubRun("drift", pushConn, cwd, opts.hubProfile);
 			if (format === "text") info(`hub: incremental drift run opened (${push.runId})`);
 		}
 		results = await analyzeDrift({
@@ -15890,56 +16100,6 @@ async function releaseSpecs(hub, project, profile, holder) {
 	}
 }
 /**
-* Fail fast when `--report-to-hub` was requested but no hub connection is
-* available. Called at the top of `runAudit`, before the sweep spends any
-* model calls — `pushDriftResults` (below) keeps its own equivalent, injectable
-* check so it stays safe to call standalone (e.g. in tests) without this guard
-* having already run.
-*/
-function requireReportToHubConnection(opts) {
-	if (!opts.reportToHub || resolveHubClient(opts)) return;
-	error("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-	process.exit(2);
-}
-/**
-* 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 for tests.
-*/
-async function openDriftPush(opts, cwd, resolveHub = resolveHubClient) {
-	const hub = resolveHub(opts);
-	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.
@@ -15971,22 +16131,16 @@ async function sealDriftPush(push, args) {
 		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
-			}
-		});
-	} catch (err) {
-		error(`hub: could not close the drift run ${push.runId}: ${errMessage(err)}`);
-		process.exit(2);
-	}
+	if (!await sealHubRun(push, {
+		rows: report.results,
+		reportMeta: {
+			git: report.git,
+			promptVersion: report.promptVersion,
+			customPromptVersion: report.customPromptVersion,
+			...report.triageUserPromptHash ? { triageUserPromptHash: report.triageUserPromptHash } : {},
+			cost: report.cost
+		}
+	})) process.exit(2);
 	if (format === "text") info(`pushed drift result to hub: ${(opts.hubUrl ?? process.env.CCQA_HUB_URL ?? "").replace(/\/+$/, "")}/#/runs/${push.runId}`);
 }
 /**
@@ -16824,6 +16978,7 @@ function gradedDriftEntry(ledger, key, runId, label) {
 		delete graded.headline;
 		delete graded.confidence;
 	}
+	if (label !== "SPEC_CHANGE") delete graded.specChangeKind;
 	return graded;
 }
 //#endregion
@@ -16958,7 +17113,7 @@ function createPushRunHandler(config) {
 				runUrl: report.runUrl ?? null,
 				reportCreatedAt: report.createdAt,
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-				...await resolveDeployedSha(config.storage, project, profile, deployedSha),
+				...await resolveDeployedSha(config.storage, kind, project, profile, deployedSha),
 				deployedShaAmbiguous: false
 			};
 			await config.storage.artifacts.putDir(run.id, dir);
@@ -17009,7 +17164,7 @@ function createOpenRunHandler(config) {
 			runUrl: runUrl || null,
 			reportCreatedAt: now,
 			createdAt: now,
-			...await resolveDeployedSha(config.storage, project, profile, deployedSha),
+			...await resolveDeployedSha(config.storage, kind, project, profile, deployedSha),
 			deployedShaAmbiguous: false
 		};
 		await config.storage.runs.create(run);
@@ -17131,10 +17286,11 @@ async function updateDriftLedger(storage, run, results) {
 	for (const row of results) {
 		if (row.status === "skipped") continue;
 		const key = `${row.feature}/${row.spec}`;
-		const diagnosis = row.analysis;
+		const diagnosis = row.analysis ? normalizeDiagnosis(row.analysis) : null;
 		ledger.specs[key] = {
 			label: diagnosis ? diagnosis.label : null,
 			surface: diagnosis?.surface,
+			specChangeKind: diagnosis?.specChangeKind,
 			confidence: diagnosis?.confidence,
 			headline: diagnosis?.headline,
 			gitHead,
@@ -17157,11 +17313,15 @@ async function updateDriftLedger(storage, run, results) {
 * Best-effort: a deploy log the hub can't read leaves the run unattributed
 * (re-run selection then answers `unknown`) rather than rejecting the run.
 */
-async function resolveDeployedSha(storage, project, profile, explicit) {
+async function resolveDeployedSha(storage, kind, project, profile, explicit) {
 	if (explicit) return {
 		deployedSha: explicit,
 		deployedShaSource: "client"
 	};
+	if (kind === "record") return {
+		deployedSha: null,
+		deployedShaSource: null
+	};
 	try {
 		const head = await storage.deploys.head(project, profile ?? "default");
 		if (head) return {
@@ -17266,17 +17426,19 @@ function createPatchRunHandler(config) {
 		sendJson(ctx.res, 200, updated);
 	};
 }
-/** GET /api/v1/runs?project&branch&status&limit */
+/** GET /api/v1/runs?project&branch&status&kind&limit */
 function createListRunsHandler(storage) {
 	return async (ctx) => {
 		const project = ctx.url.searchParams.get("project");
 		const branch = ctx.url.searchParams.get("branch");
 		const status = ctx.url.searchParams.get("status");
 		const limitRaw = ctx.url.searchParams.get("limit");
+		const kindsRaw = ctx.url.searchParams.get("kind");
 		const runs = await storage.runs.list({
 			...project ? { project } : {},
 			...branch ? { branch } : {},
 			...status ? { status } : {},
+			...kindsRaw ? { kinds: kindsRaw.split(",").map(requireKind) } : {},
 			...limitRaw ? { limit: Number(limitRaw) } : {}
 		});
 		sendJson(ctx.res, 200, { runs: await Promise.all(runs.map((r) => withGradedDrift(storage, r))) });
@@ -17410,16 +17572,21 @@ function parseRunScope(ctx) {
 	const profileRaw = ctx.url.searchParams.get("profile");
 	const profile = profileRaw ? requireSafeSegment(profileRaw, "profile") : null;
 	const kindRaw = ctx.url.searchParams.get("kind");
-	if (kindRaw !== null && kindRaw !== "run" && kindRaw !== "drift") throw new HttpError(400, "invalid_param", `invalid kind: must be "run" or "drift"`);
 	const deployedSha = boundedParam(ctx.url.searchParams.get("deployedSha"), "deployedSha", 64);
 	return {
 		project,
 		branch,
 		profile,
-		kind: kindRaw ?? "run",
+		kind: kindRaw === null ? "run" : requireKind(kindRaw),
 		deployedSha
 	};
 }
+/** One `kind` value, validated against the enum so the message can't drift from it. */
+function requireKind(raw) {
+	const parsed = ReportKindSchema.safeParse(raw);
+	if (!parsed.success) throw new HttpError(400, "invalid_param", `invalid kind: must be one of ${ReportKindSchema.options.map((k) => `"${k}"`).join(", ")}`);
+	return parsed.data;
+}
 /**
 * A branch is a free-form label (e.g. `feature/foo`), so `/` is allowed —
 * only length is bounded (a sanity cap; the last-green ledger separately
@@ -17965,7 +18132,7 @@ function createGetAuditNeedHandler(storage) {
 //#endregion
 //#region src/hub/api/handlers/locks.ts
 /** A spec-key list and three short strings; nothing here should approach this. */
-const MAX_BODY_BYTES$1 = 1024 * 1024;
+const MAX_BODY_BYTES$2 = 1024 * 1024;
 /**
 * POST /api/v1/projects/:project/locks?profile=
 *
@@ -17979,7 +18146,7 @@ function createAcquireLocksHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$1, AcquireLocksRequestSchema, "lock request");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, AcquireLocksRequestSchema, "lock request");
 		let result = {
 			granted: [],
 			denied: []
@@ -18008,12 +18175,55 @@ function createReleaseLocksHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$1, ReleaseLocksRequestSchema, "release request");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, ReleaseLocksRequestSchema, "release request");
 		await storage.locks.update(project, profile, (current) => releaseAll(current, body.holder));
 		ctx.res.writeHead(204).end();
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/acks.ts
+/**
+* Pre-parse guard only. `PutAckRequestSchema` holds the real bound (5000 keys
+* of 256 characters); this sits above the largest body that can satisfy it —
+* 5000 keys of 256 `\uXXXX`-escaped characters — so a conforming client is
+* never answered 413 by a limit the documented bounds don't mention.
+*/
+const MAX_BODY_BYTES$1 = 8 * 1024 * 1024;
+function requireAckKey(ctx) {
+	return {
+		project: requireSafeSegment(ctx.params.project, "project"),
+		profile: requireProfileParam(ctx.url),
+		name: requireSafeSegment(ctx.params.name, "name")
+	};
+}
+/**
+* GET /api/v1/projects/:project/acks/:name?profile= — an unset ack answers 200
+* with an empty set, not 404: "nothing acted on yet" is a real answer, and a
+* 404 there is a special case consumers get wrong.
+*/
+function createGetAckHandler(storage) {
+	return async (ctx) => {
+		const key = requireAckKey(ctx);
+		const ack = await storage.acks.get(key.project, key.profile, key.name);
+		sendJson(ctx.res, 200, {
+			...key,
+			...ack
+		});
+	};
+}
+/** PUT /api/v1/projects/:project/acks/:name?profile= */
+function createPutAckHandler(storage) {
+	return async (ctx) => {
+		const key = requireAckKey(ctx);
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$1, PutAckRequestSchema, "ack body");
+		const ack = await storage.acks.put(key.project, key.profile, key.name, body.keys);
+		sendJson(ctx.res, 200, {
+			...key,
+			...ack
+		});
+	};
+}
+//#endregion
 //#region src/hub/core/rerun.ts
 /**
 * When each deployed commit reached the environment. A baseline read at that
@@ -19263,7 +19473,12 @@ const CSS = `
   .empty-note { color: var(--muted); font-size: 13px; padding: 16px 2px; }
 
   .runid { font-family: var(--mono); font-size: 13px; font-weight: 600; }
-  .subline { margin-top: 3px; }
+  /* Chips wrap when a run carries several labels. Laid out as inline content
+     they wrapped to a line indented by the chips' own left margin, and the two
+     lines sat at text leading — too tight to read as separate rows. Flex with a
+     gap aligns every line at the same left edge and spaces them the same way
+     horizontally and vertically. */
+  .subline { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; margin-top: 4px; }
   .ci-badge { display: inline-flex; align-items: center; gap: 5px; font-size: 11px; font-family: var(--mono); color: var(--muted); background: var(--surface-3); border: 1px solid var(--border); border-radius: 5px; padding: 1px 6px; }
   .ci-badge.local { color: var(--muted-2); }
   a.ci-badge { text-decoration: none; }
@@ -19279,6 +19494,15 @@ const CSS = `
   .badge.skipped .d { background: var(--muted); }
   .badge.running { background: var(--amber-bg); color: var(--amber); border-color: var(--amber-border); }
   .badge.running .d { background: var(--amber); }
+  /* A drift verdict is a diagnosis, not a broken test: amber, never fail-red.
+     Without these the badge rendered as bare text next to the pill-shaped
+     pass/fail ones, and read as a different kind of thing. */
+  .badge.dr-found { background: var(--amber-bg); color: var(--amber); border-color: var(--amber-border); }
+  .badge.dr-found .d { background: var(--amber); }
+  .badge.dr-clean { background: var(--pass-bg); color: var(--pass); border-color: var(--pass-border); }
+  .badge.dr-clean .d { background: var(--pass); }
+  .badge.dr-unknown { background: var(--surface-3); color: var(--muted); border-color: var(--border); }
+  .badge.dr-unknown .d { background: var(--muted); }
   .badge-live, .badge-det { display: inline-flex; align-items: center; padding: 2px 8px; border-radius: var(--radius-sm); font-size: 11px; font-weight: 600; border: 1px solid transparent; }
   .badge-live { background: var(--violet-bg); color: var(--violet); border-color: var(--violet-border); }
   .badge-det { background: var(--surface-3); color: var(--muted); border-color: var(--border); }
@@ -19290,8 +19514,11 @@ const CSS = `
      order decides). One amber look for every drift label chip — a label chip
      is a finding, not a severity, so it does not split into fail-red/amber
      the way the old errors/warnings counts did. */
-  .chip.kind-chip { color: var(--violet); background: var(--violet-bg); border-color: var(--violet-border); font-family: var(--font); margin-left: 6px; }
-  .chip.drift-count-chip { color: var(--amber); background: var(--amber-bg); border-color: var(--amber-border); margin-left: 6px; }
+  .chip.kind-chip { color: var(--violet); background: var(--violet-bg); border-color: var(--violet-border); font-family: var(--font); }
+  .chip.drift-count-chip { color: var(--amber); background: var(--amber-bg); border-color: var(--amber-border); }
+  /* Prose, not an identifier — and neutral, since it qualifies the label chip
+     beside it rather than claiming a severity of its own. */
+  .chip.spec-change-chip { font-family: var(--font); }
   .drift-meta-box { display: flex; flex-direction: column; gap: 4px; }
   /* The chips carry their own margin for the run list, where they sit inline
      after other chips. Here the container owns the spacing, so the margin only
@@ -19765,6 +19992,7 @@ const CLIENT_JS = `
       "meta.drift": "Drift",
       "diag.cause": "Cause", "diag.fix": "Fix",
       "diag.surface": "Surface", "diag.surface.spec": "spec", "diag.surface.generated": "generated code",
+      "diag.specChangeKind.FEATURE_REMOVED": "feature gone", "diag.specChangeKind.BEHAVIOUR_CHANGED": "behaviour changed",
       "acc.reasoning": "Reasoning", "acc.evidence": "Evidence", "acc.steps": "Live run steps",
       "acc.assertions": "Assertions",
       "acc.artifacts": "Artifacts",
@@ -19773,7 +20001,7 @@ const CLIENT_JS = `
       "spec.kind.live": "Live", "spec.kind.det": "Deterministic",
       "det.steps": "Steps",
       "det.noEvidence": "No step screenshots:",
-      "kind.run": "Test run", "kind.drift": "Drift audit",
+      "kind.run": "Test run", "kind.drift": "Drift audit", "kind.record": "Recording",
       "drift.summary.ratio": "{found} of {total} specs",
       "drift.clean": "No drift issues",
       "status.passed": "passed", "status.failed": "failed", "status.skipped": "skipped", "status.running": "running",
@@ -19923,6 +20151,7 @@ const CLIENT_JS = `
       "meta.drift": "ドリフト",
       "diag.cause": "原因", "diag.fix": "対処",
       "diag.surface": "対象", "diag.surface.spec": "spec", "diag.surface.generated": "生成コード",
+      "diag.specChangeKind.FEATURE_REMOVED": "機能が無い", "diag.specChangeKind.BEHAVIOUR_CHANGED": "振る舞いが変わった",
       "acc.reasoning": "推論", "acc.evidence": "根拠", "acc.steps": "実行ステップ",
       "acc.assertions": "アサーション",
       "acc.artifacts": "成果物",
@@ -19931,7 +20160,7 @@ const CLIENT_JS = `
       "spec.kind.live": "ライブ", "spec.kind.det": "決定的",
       "det.steps": "ステップ",
       "det.noEvidence": "ステップのスクリーンショットなし:",
-      "kind.run": "テスト実行", "kind.drift": "ドリフト監査",
+      "kind.run": "テスト実行", "kind.drift": "ドリフト監査", "kind.record": "収録",
       "drift.summary.ratio": "{found} / {total} スペック",
       "drift.clean": "ドリフトの問題なし",
       "status.passed": "合格", "status.failed": "失敗", "status.skipped": "スキップ", "status.running": "実行中",
@@ -20310,6 +20539,21 @@ const CLIENT_JS = `
     return run.kind === "drift" ? driftFoundBadge(driftRunState(run), "drift.run.") : statusBadge(run.status);
   }
 
+  // Which command left the run, and whether its spec counts are a tally of
+  // what was verified. A recording's rows are the specs it wrote, not specs it
+  // checked, so "1 / 1 passed" and a full meter would claim a test result.
+  // A kind from a newer hub keeps the generic label but is read the same
+  // cautious way, since nothing here knows what its counts mean.
+  var KINDS = {
+    run: { label: "kind.run", verifies: true },
+    drift: { label: "kind.drift", verifies: true },
+    record: { label: "kind.record", verifies: false },
+  };
+  function kindOf(kind) { return KINDS[kind] || { label: "kind.run", verifies: false }; }
+  function kindChip(kind) {
+    return el("span", "chip kind-chip", t(kindOf(kind).label));
+  }
+
   // A run's Claude spend, in the same $x.xxxx form as the per-step badge.
   // A run that billed nothing, and one stored before costs were recorded, both
   // arrive as a non-number — printing $0.0000 would claim a measured zero.
@@ -20580,12 +20824,10 @@ const CLIENT_JS = `
       runCell.appendChild(el("div", "runid", r.id.slice(0, 8)));
       var sub = el("div", "subline");
       sub.appendChild(ciBadge(r));
+      sub.appendChild(kindChip(r.kind));
       if (r.kind === "drift") {
-        sub.appendChild(el("span", "chip kind-chip", t("kind.drift")));
         var rowDrift = driftSummary(r);
         if (rowDrift) driftChips(rowDrift).forEach(function (chip) { sub.appendChild(chip); });
-      } else {
-        sub.appendChild(el("span", "chip kind-chip", t("kind.run")));
       }
       runCell.appendChild(sub);
       tr.appendChild(runCell);
@@ -20602,29 +20844,33 @@ const CLIENT_JS = `
       statusCell.appendChild(runStatusBadge(r));
       tr.appendChild(statusCell);
 
-      // A drift row counts what the audit found, not what "passed" — the same
-      // ratio its detail page shows. Reading passed/total here printed a
-      // different number for the same run in the two places you would compare.
-      var rowDriftSummary = r.kind === "drift" ? driftSummary(r) : null;
-      var found = rowDriftSummary
-        ? rowDriftSummary.testDrift + rowDriftSummary.specChange + rowDriftSummary.unknown
-        : null;
-      var num = rowDriftSummary
-        ? found + " / " + rowDriftSummary.specs
-        : r.specs.passed + " / " + r.specs.total;
-      var fillTotal = rowDriftSummary ? rowDriftSummary.specs : r.specs.total;
-      var fillPart = rowDriftSummary ? found : r.specs.passed;
-
       var specsCell = document.createElement("td");
-      var specsWrap = el("div", "specs");
-      var meter = el("span", "meter" + (rowDriftSummary ? " drift" : ""));
-      var pct = fillTotal > 0 ? Math.round((fillPart / fillTotal) * 100) : 0;
-      var bar = el("i");
-      bar.style.width = pct + "%";
-      meter.appendChild(bar);
-      specsWrap.appendChild(meter);
-      specsWrap.appendChild(el("span", "num muted", num));
-      specsCell.appendChild(specsWrap);
+      if (!kindOf(r.kind).verifies) {
+        specsCell.appendChild(el("span", "muted", "—"));
+      } else {
+        // A drift row counts what the audit found, not what "passed" — the same
+        // ratio its detail page shows. Reading passed/total here printed a
+        // different number for the same run in the two places you would compare.
+        var rowDriftSummary = r.kind === "drift" ? driftSummary(r) : null;
+        var found = rowDriftSummary
+          ? rowDriftSummary.testDrift + rowDriftSummary.specChange + rowDriftSummary.unknown
+          : null;
+        var num = rowDriftSummary
+          ? found + " / " + rowDriftSummary.specs
+          : r.specs.passed + " / " + r.specs.total;
+        var fillTotal = rowDriftSummary ? rowDriftSummary.specs : r.specs.total;
+        var fillPart = rowDriftSummary ? found : r.specs.passed;
+
+        var specsWrap = el("div", "specs");
+        var meter = el("span", "meter" + (rowDriftSummary ? " drift" : ""));
+        var pct = fillTotal > 0 ? Math.round((fillPart / fillTotal) * 100) : 0;
+        var bar = el("i");
+        bar.style.width = pct + "%";
+        meter.appendChild(bar);
+        specsWrap.appendChild(meter);
+        specsWrap.appendChild(el("span", "num muted", num));
+        specsCell.appendChild(specsWrap);
+      }
       tr.appendChild(specsCell);
 
       tr.appendChild(el("td", "muted num", costText(r.costUsd)));
@@ -20663,7 +20909,7 @@ const CLIENT_JS = `
     // What kind of run this is, said once. The spec cards below used to repeat
     // it per row, which read as "this spec was drift-audited" — a property of
     // the run described as if it varied spec to spec. Same chip as the run list.
-    sub.appendChild(el("span", "chip kind-chip", t(run.kind === "drift" ? "kind.drift" : "kind.run")));
+    sub.appendChild(kindChip(run.kind));
     idblock.appendChild(sub);
     head.appendChild(idblock);
 
@@ -20697,7 +20943,7 @@ const CLIENT_JS = `
         driftBox.appendChild(el("div", "muted", ratio));
         metaItem(t("meta.drift"), driftBox);
       }
-    } else {
+    } else if (kindOf(run.kind).verifies) {
       metaItem(t("meta.specs"), run.specs.passed + " / " + run.specs.total + " " + t("meta.passed"));
     }
     // Everything this run spent on Claude — live browsing, triage, the audit a
@@ -20806,6 +21052,12 @@ const CLIENT_JS = `
     var a = r.analysis;
     var head = el("div", "analysis-head");
     head.appendChild(labelChip(a.label));
+    // Which repair a SPEC_CHANGE needs — delete the spec, or rewrite it. The
+    // label is re-checked rather than trusted: this chip means nothing beside
+    // any other one, however the row reached the browser.
+    if (a.label === "SPEC_CHANGE" && a.specChangeKind) {
+      head.appendChild(el("span", "chip spec-change-chip", t("diag.specChangeKind." + a.specChangeKind)));
+    }
     head.appendChild(el("span", "conf", Math.round(a.confidence * 100) + "%"));
     wrap.appendChild(head);
     var kv = el("div", "analysis-kv");
@@ -22000,8 +22252,12 @@ const CLIENT_JS = `
   // runs and no deploys to judge). One runs page answers both: runId -> CI URL,
   // and the profiles a run was actually recorded under. A run pushed without a
   // profile lands in "default", exactly as the ledger stores it.
+  //
+  // Only the two kinds a ledger entry can point at, so recordings — which
+  // advance no ledger and are never looked up here — cannot crowd them out of
+  // the window.
   function fetchRunIndex() {
-    return apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&limit=200")
+    return apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&kind=run,drift&limit=200")
       .then(function (data) {
         var urls = {};
         var profiles = [];
@@ -23734,7 +23990,8 @@ function createLearningWorker(deps) {
 		const runLimit = job.input.runLimit > 0 ? job.input.runLimit : DEFAULT_RUN_LIMIT;
 		const runs = await storage.runs.list({
 			project: job.project,
-			limit: runLimit
+			limit: runLimit,
+			kinds: ["run"]
 		});
 		const cases = [];
 		let excluded = 0;
@@ -23933,6 +24190,8 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/audit-needed", createGetAuditNeedHandler(storage));
 	router.post("/api/v1/projects/:project/locks", createAcquireLocksHandler(storage));
 	router.delete("/api/v1/projects/:project/locks", createReleaseLocksHandler(storage));
+	router.get("/api/v1/projects/:project/acks/:name", createGetAckHandler(storage));
+	router.put("/api/v1/projects/:project/acks/:name", createPutAckHandler(storage));
 	const sessionConfig = {
 		store: storage.sessions,
 		encryptionKey: config.encryptionKey
@@ -23967,6 +24226,16 @@ function registerRoutes(router, config, queue) {
 }
 //#endregion
 //#region src/hub/core/storage/file/fs-helpers.ts
+/**
+* Defense-in-depth for a name this layer joins into a file path. The API's
+* `SAFE_SEGMENT` (api/validate.ts) is deliberately stricter — it also fixes a
+* charset and a length — and stays the rule for what a client may name; this
+* only refuses traversal, so it also covers callers that never came through
+* HTTP (tests, a library embedding the hub).
+*/
+function assertSafeName(value, label) {
+	if (value.length === 0 || value === "." || value === ".." || value.includes("/") || value.includes("\\")) throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
+}
 /** Read and JSON-parse a file, returning `null` when it doesn't exist. Malformed JSON throws. */
 async function readJson(path) {
 	let raw;
@@ -24106,6 +24375,7 @@ function isNotFound(err) {
 *   drift-ledger/<project>/<branch>.json         (DriftLedger, no profile)
 *   deploys/<project>/<profile>/log.json         (DeployLog, ring-buffered)
 *   deploys/<project>/<profile>/touch.json       (SpecTouchIndex derived from the log)
+*   acks/<project>/<profile>/<name>.json         (Ack: a consumer's acted-on keys)
 *
 * IDs and names are validated by their callers (run ids are server-minted
 * UUIDs; project/profile/name come from validated request params) before
@@ -24197,6 +24467,43 @@ function deployTouchIndexPath(root, project, profile) {
 function specLocksPath(root, project, profile) {
 	return join(root, "locks", project, profile, "locks.json");
 }
+function ackPath(root, project, profile, name) {
+	return join(root, "acks", project, profile, `${name}.json`);
+}
+//#endregion
+//#region src/hub/core/storage/file/ack-store.ts
+function assertSafeKey(project, profile, name) {
+	assertSafeName(project, "project");
+	assertSafeName(profile, "profile");
+	assertSafeName(name, "name");
+}
+/**
+* Ack storage: one JSON document per (project, profile, name). A write
+* replaces the document outright, so unlike the ledgers there is no
+* read-modify-write to serialize — but it still goes through `writeJson`'s
+* temp-then-rename, so a concurrent reader never sees a half-written set.
+*/
+function createFileAckStore(root) {
+	return {
+		async get(project, profile, name) {
+			assertSafeKey(project, profile, name);
+			const parsed = AckSchema.safeParse(await readJson(ackPath(root, project, profile, name)));
+			return parsed.success ? parsed.data : {
+				keys: [],
+				at: null
+			};
+		},
+		async put(project, profile, name, keys) {
+			assertSafeKey(project, profile, name);
+			const ack = {
+				keys,
+				at: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			await writeJson(ackPath(root, project, profile, name), ack);
+			return ack;
+		}
+	};
+}
 //#endregion
 //#region src/hub/core/storage/file/artifact-store.ts
 /**
@@ -24367,14 +24674,6 @@ function createFileSpecLedgerStore(root) {
 //#endregion
 //#region src/hub/core/storage/file/perspectives-store.ts
 /**
-* Defense-in-depth path validation: the HTTP layer already checks the project
-* segment, but this builds a file path from it, so it re-checks rather than
-* trusting callers. Mirrors the sibling prompt/secret stores.
-*/
-function assertSafeName$2(value, label) {
-	if (value.length === 0 || value.includes("/") || value.includes("\\") || value.split(/[\\/]/).includes("..") || value === ".") throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
-}
-/**
 * Perspectives storage: one JSON document per project, plain UTF-8 with no
 * encryption (an inventory of what is tested is not a secret). No meta file —
 * the document's own `generatedAt` is its timestamp.
@@ -24382,19 +24681,19 @@ function assertSafeName$2(value, label) {
 function createFilePerspectivesStore(root) {
 	return {
 		async put(project, blob) {
-			assertSafeName$2(project, "project");
+			assertSafeName(project, "project");
 			await writeBytes(perspectivesPath(root, project), blob);
 		},
 		async get(project) {
-			assertSafeName$2(project, "project");
+			assertSafeName(project, "project");
 			return readBytesOrNull(perspectivesPath(root, project));
 		},
 		async update(project, mutate) {
-			assertSafeName$2(project, "project");
+			assertSafeName(project, "project");
 			await updateJson(perspectivesPath(root, project), mutate);
 		},
 		async delete(project) {
-			assertSafeName$2(project, "project");
+			assertSafeName(project, "project");
 			await removePath(perspectivesPath(root, project));
 		}
 	};
@@ -24402,15 +24701,6 @@ function createFilePerspectivesStore(root) {
 //#endregion
 //#region src/hub/core/storage/file/prompt-store.ts
 /**
-* Defense-in-depth path validation: the HTTP layer already checks project/name,
-* but this builds file paths from them, so it re-checks rather than trusting
-* callers. (Which names are allowed at all is the handler's job — this only
-* guards against path traversal.)
-*/
-function assertSafeName$1(value, label) {
-	if (value.length === 0 || value.includes("/") || value.includes("\\") || value.split(/[\\/]/).includes("..") || value === ".") throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
-}
-/**
 * Prompt storage, project-scoped (not per-profile — prompts are project-wide).
 * The blob is plain UTF-8 text (Markdown or custom prompt JSON) with no encryption,
 * so this works whether or not `CCQA_HUB_ENCRYPTION_KEY` is configured.
@@ -24418,8 +24708,8 @@ function assertSafeName$1(value, label) {
 function createFilePromptStore(root) {
 	return {
 		async put(project, name, blob, meta = {}) {
-			assertSafeName$1(project, "project");
-			assertSafeName$1(name, "name");
+			assertSafeName(project, "project");
+			assertSafeName(name, "name");
 			await writeJson(promptMetaPath(root, project, name), {
 				meta,
 				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -24427,8 +24717,8 @@ function createFilePromptStore(root) {
 			await writeBytes(promptBlobPath(root, project, name), blob);
 		},
 		async get(project, name) {
-			assertSafeName$1(project, "project");
-			assertSafeName$1(name, "name");
+			assertSafeName(project, "project");
+			assertSafeName(name, "name");
 			const blob = await readBytesOrNull(promptBlobPath(root, project, name));
 			if (!blob) return null;
 			return {
@@ -24437,7 +24727,7 @@ function createFilePromptStore(root) {
 			};
 		},
 		async list(project) {
-			assertSafeName$1(project, "project");
+			assertSafeName(project, "project");
 			const names = (await listDirOrEmpty(promptProjectDir(root, project))).filter((f) => f.endsWith(".txt")).map((f) => f.slice(0, -4));
 			const out = [];
 			for (const name of names) {
@@ -24451,8 +24741,8 @@ function createFilePromptStore(root) {
 			return out;
 		},
 		async delete(project, name) {
-			assertSafeName$1(project, "project");
-			assertSafeName$1(name, "name");
+			assertSafeName(project, "project");
+			assertSafeName(name, "name");
 			await removePath(promptBlobPath(root, project, name));
 			await removePath(promptMetaPath(root, project, name));
 		},
@@ -24494,7 +24784,7 @@ function createFileRunStore(root) {
 				};
 			});
 		},
-		async list({ project, branch, status, limit }) {
+		async list({ project, branch, status, kinds, limit }) {
 			const ids = await listSubdirsOrEmpty(runsDir(root));
 			const runs = [];
 			for (const id of ids) {
@@ -24503,6 +24793,7 @@ function createFileRunStore(root) {
 				if (project !== void 0 && run.project !== project) continue;
 				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;
 				runs.push(run);
 			}
 			runs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
@@ -24521,14 +24812,6 @@ function createFileRunStore(root) {
 }
 //#endregion
 //#region src/hub/core/storage/file/secret-store.ts
-/**
-* Defense-in-depth: project/profile/name are expected to already be validated
-* by the HTTP layer (`requireSafeSegment`), but this store builds file paths
-* directly from them, so it re-checks rather than trusting callers blindly.
-*/
-function assertSafeName(value, label) {
-	if (value.length === 0 || value.includes("/") || value.includes("\\") || value.split(/[\\/]/).includes("..") || value === ".") throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
-}
 function assertSafeScope(scope) {
 	assertSafeName(scope.project, "project");
 	assertSafeName(scope.profile, "profile");
@@ -24622,7 +24905,8 @@ function createFileHubStorage(dataDir) {
 		ledger: createFileSpecLedgerStore(dataDir),
 		driftLedger: createFileDriftLedgerStore(dataDir),
 		deploys: createFileDeployStore(dataDir),
-		locks: createFileLockStore(dataDir)
+		locks: createFileLockStore(dataDir),
+		acks: createFileAckStore(dataDir)
 	};
 }
 //#endregion