ccqa 1.24.0 → 1.26.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(),
@@ -4726,6 +4780,42 @@ function appendCostRecord(command, cost) {
 		appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
 	} catch {}
 }
+/**
+* Read back what `appendCostRecord` wrote. `null` when the file isn't there:
+* ccqa never ran, which is not the answer "ran and was billed nothing". An
+* unbilled line (`totalCostUsd: null`) adds nothing to the total but is still
+* an invocation — a killed job leaves a half-written last line, which is
+* neither.
+*/
+async function readCostFileTotal(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (err) {
+		if (err instanceof Error && err.code === "ENOENT") return null;
+		throw err;
+	}
+	let totalUsd = 0;
+	let invocations = 0;
+	let unreadable = 0;
+	for (const line of raw.split("\n")) {
+		if (line.trim().length === 0) continue;
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			unreadable++;
+			continue;
+		}
+		invocations++;
+		if (typeof record.totalCostUsd === "number") totalUsd += record.totalCostUsd;
+	}
+	return {
+		totalUsd,
+		invocations,
+		unreadable
+	};
+}
 //#endregion
 //#region src/cli/draft.ts
 const CATEGORY_LABEL = DRAFT_CATEGORY_LABEL;
@@ -6738,7 +6828,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 +7198,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 +7249,53 @@ 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()
+});
+/**
+* What one batch of ccqa invocations spent on Claude, as the job that ran them
+* reported it (see `SpendStore`). `label` is the consumer's name for the batch
+* — its job name — and the only thing that says where the money went.
+*/
+const SpendEntrySchema = z.object({
+	id: z.string(),
+	at: z.string(),
+	costUsd: z.number(),
+	label: z.string(),
+	ciRunId: z.string().optional(),
+	runUrl: z.string().optional()
+});
+z.object({ entries: z.array(SpendEntrySchema).default([]) });
+/** Body of `POST /projects/:project/spend` — one batch's total. `at` defaults to now. */
+const RecordSpendRequestSchema = z.object({
+	costUsd: z.number().nonnegative(),
+	label: z.string().min(1).max(200),
+	at: z.string().refine((v) => !Number.isNaN(Date.parse(v)), "at must be an ISO-8601 instant").optional(),
+	ciRunId: z.string().optional(),
+	runUrl: z.string().optional()
+});
+z.object({
+	project: z.string(),
+	since: z.string().nullable(),
+	until: z.string().nullable(),
+	totalUsd: z.number(),
+	entries: z.array(SpendEntrySchema)
+});
 //#endregion
 //#region src/run/hub-selection.ts
 /**
@@ -8172,6 +8310,19 @@ function githubRunUrl(env = process.env) {
 function githubRunId(env = process.env) {
 	return env["GITHUB_RUN_ID"] ?? null;
 }
+/**
+* The CI provenance every hub record carries, ready to spread into a request
+* body. Empty outside Actions, so a local invocation sends neither field
+* rather than a null one.
+*/
+function ciProvenance(env = process.env) {
+	const ciRunId = githubRunId(env);
+	const runUrl = githubRunUrl(env);
+	return {
+		...ciRunId ? { ciRunId } : {},
+		...runUrl ? { runUrl } : {}
+	};
+}
 //#endregion
 //#region src/cli/deploy-paths.ts
 /**
@@ -8963,6 +9114,36 @@ function describeSelection(selection, diffAvailable) {
 	return `${values.filter((s) => s.verdict === "needed").length} needed / ${values.filter((s) => s.verdict === "unknown").length} unknown / ${values.length} specs`;
 }
 const deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --only-hub-rerun-needed`.").addCommand(deployRecord);
+const costPush = new Command("push").description("Record what this job spent on Claude: sum the cost file every ccqa invocation appended to ($CCQA_COST_FILE) and push the total to the hub as one spend entry. Run it last, once. A budget reads these totals INSTEAD OF summing the hub's runs: most commands that call Claude leave no run behind, and a batch already includes the ones that do, so adding both double-counts.").requiredOption("--label <name>", "What this batch was — typically the CI job's name. Required: an unlabelled entry tells a reader nothing about where the money went.").option("--from <path>", "Cost file to read. Defaults to $CCQA_COST_FILE.").option("--project <name>", "Project the spend is recorded against. Defaults to the current directory's name.").option(...cwdOption).option(...hubUrlOption).option(...hubTokenOption).action(withHubErrors(runCostPush));
+async function runCostPush(opts) {
+	const path = opts.from ?? process.env.CCQA_COST_FILE;
+	if (!path) {
+		error("no cost file to read (--from <path> or CCQA_COST_FILE)");
+		process.exit(2);
+	}
+	const project = resolveProject(opts);
+	const hub = connect(opts);
+	header("hub cost push", opts.label);
+	meta("project", project);
+	const total = await readCostFileTotal(path);
+	if (total === null) {
+		warn(`no cost file at ${path}; recorded nothing — ccqa never ran here, which is not a spend of zero`);
+		return;
+	}
+	if (total.invocations === 0) {
+		warn(`${path} holds no invocations; recorded nothing`);
+		return;
+	}
+	await hub.recordSpend(project, {
+		costUsd: total.totalUsd,
+		label: opts.label,
+		...ciProvenance()
+	});
+	meta("invocations", String(total.invocations));
+	if (total.unreadable > 0) warn(`${total.unreadable} line(s) of ${path} could not be read, so the total below is a floor: what they cost is not in it, and the hub now holds the short number`);
+	info(`recorded $${total.totalUsd.toFixed(4)} of spend on the hub`);
+}
+const costCommand = new Command("cost").description("Report what a CI job spent on Claude to the hub — the number a budget reads.").addCommand(costPush);
 const pushCommand = new Command("push").description("Upload the report directory of a finished `ccqa run --report` to the hub as a run. Run this after `ccqa run` (use `if: always()` in CI so failing runs are pushed too).").option("--report-dir <dir>", `Report directory to push. Default: ${DEFAULT_REPORT_DIR}/`).option("--project <name>", "Logical project name for the run. Defaults to the current directory's name.").option("--branch <name>", "Branch label. Defaults to $GITHUB_HEAD_REF / $GITHUB_REF_NAME / current git branch.").option("--profile <name>", "Profile (environment) the run executed against. Recorded for display; runs are not scoped by profile.").option(...hubUrlOption).option(...hubTokenOption).option("--cwd <path>", "Directory the report dir is resolved against (defaults to the current directory).").action(withHubErrors(async (opts) => {
 	const cwd = resolveCwd(opts.cwd);
 	const reportDir = join(cwd, opts.reportDir ?? "ccqa-report");
@@ -8997,7 +9178,7 @@ const pushCommand = new Command("push").description("Upload the report directory
 	meta("specs", `${run.specs.passed}/${run.specs.total} passed`);
 	info(`${resolveBaseUrl(opts)}/#/runs/${run.id}`);
 }));
-const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand);
+const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand);
 /** Loose check that a fetched session is agent-browser storage-state, mirroring loadStorageState. */
 function isStorageStateShape(state) {
 	return typeof state === "object" && state !== null && Array.isArray(state.cookies) && Array.isArray(state.origins);
@@ -10993,14 +11174,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 +11203,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 +12011,72 @@ 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)]);
+	try {
+		const run = await conn.hub.openRun({
+			project: conn.project,
+			kind,
+			...branch ? { branch } : {},
+			...profile ? { profile } : {},
+			...gitHead ? { gitHead } : {},
+			...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)})`);
+	}
+}
+/**
+* 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 +12614,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,
@@ -12513,16 +12754,13 @@ async function executeRun(targets, opts) {
 	let hubPublishBroken = false;
 	if (hubCtx != null && opts.reportToHub) try {
 		const branch = await detectBranch(cwd);
-		const ciRunId = githubRunId();
-		const runUrl = githubRunUrl();
 		const opened = await hubCtx.hub.openRun({
 			project: hubCtx.project,
 			...branch ? { branch } : {},
 			...opts.hubProfile ? { profile: opts.hubProfile } : {},
 			...git.head ? { gitHead: git.head } : {},
 			...deployedSha ? { deployedSha } : {},
-			...ciRunId ? { ciRunId } : {},
-			...runUrl ? { runUrl } : {},
+			...ciProvenance(),
 			kind: "run"
 		});
 		hubRunId = opened.id;
@@ -13137,7 +13375,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 +13395,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 +14932,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 +14944,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 +14975,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 +15004,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 +15081,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 +15102,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 +15123,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 +15162,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 +15173,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 +15468,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 +15480,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 +15667,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 +15805,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 +15838,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 +16124,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 +16202,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 +16233,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 +17080,7 @@ function gradedDriftEntry(ledger, key, runId, label) {
 		delete graded.headline;
 		delete graded.confidence;
 	}
+	if (label !== "SPEC_CHANGE") delete graded.specChangeKind;
 	return graded;
 }
 //#endregion
@@ -16877,11 +17134,15 @@ function mergeBucket(into, from) {
 //#endregion
 //#region src/hub/api/validate.ts
 /**
-* Validators for URL path parameters that flow into the storage layer's file
-* path construction (secret store scope/name, artifact relative paths).
+* Validators for the request parameters handlers read straight off the wire:
+* the URL path parameters that flow into the storage layer's file path
+* construction (secret store scope/name, artifact relative paths), and the
+* query params bounding a listing's time window.
+*
 * Router params come from `decodeURIComponent`-ed path segments, so a client
-* can put `..`, `/`, or `\` in them — these guards reject anything that
-* could escape the intended directory before it ever reaches disk I/O.
+* can put `..`, `/`, or `\` in them — the path validators below reject
+* anything that could escape the intended directory before it ever reaches
+* disk I/O.
 */
 const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /** Validate a single URL path parameter (e.g. `:profile`, `:name`) as a bare name. Throws 400 if unsafe. */
@@ -16896,6 +17157,26 @@ function requireSafeSegment(value, paramName) {
 function requireProfileParam(url) {
 	return requireSafeSegment(url.searchParams.get("profile") ?? "default", "profile");
 }
+/**
+* The `?since=`/`?until=` window a listing takes, in the shape its store's
+* `list` takes it. Half-open on purpose: a caller asking for one day passes
+* that day's start and the next day's start, and no record is counted twice
+* at a boundary.
+*/
+function requireWindowParams(url) {
+	const since = requireInstant(url.searchParams.get("since"), "since");
+	const until = requireInstant(url.searchParams.get("until"), "until");
+	return {
+		...since ? { since } : {},
+		...until ? { until } : {}
+	};
+}
+/** Rejected rather than ignored: a typo would otherwise read as "nothing that day". */
+function requireInstant(raw, name) {
+	if (raw === null || raw === "") return null;
+	if (Number.isNaN(Date.parse(raw))) throw new HttpError(400, "invalid_param", `invalid ${name}: must be an ISO-8601 instant`);
+	return raw;
+}
 /** Validate a `*path`-captured relative path (multiple segments allowed) as safe to join under a root dir. Throws 400 if unsafe. */
 function requireSafeRelPath(relPath, paramName) {
 	const segments = relPath.split("/");
@@ -16958,7 +17239,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 +17290,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 +17412,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 +17439,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 +17552,20 @@ function createPatchRunHandler(config) {
 		sendJson(ctx.res, 200, updated);
 	};
 }
-/** GET /api/v1/runs?project&branch&status&limit */
+/** GET /api/v1/runs?project&branch&status&kind&since&until&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) } : {},
+			...requireWindowParams(ctx.url),
 			...limitRaw ? { limit: Number(limitRaw) } : {}
 		});
 		sendJson(ctx.res, 200, { runs: await Promise.all(runs.map((r) => withGradedDrift(storage, r))) });
@@ -17410,16 +17699,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 +18259,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$3 = 1024 * 1024;
 /**
 * POST /api/v1/projects/:project/locks?profile=
 *
@@ -17979,7 +18273,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$3, AcquireLocksRequestSchema, "lock request");
 		let result = {
 			granted: [],
 			denied: []
@@ -18008,12 +18302,95 @@ 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$3, 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$2 = 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$2, 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/api/handlers/spend.ts
+/** One entry is a handful of short fields; anything larger is a malformed client. */
+const MAX_BODY_BYTES$1 = 4 * 1024;
+/**
+* POST /api/v1/projects/:project/spend
+*
+* What a batch of ccqa invocations cost, as the job that ran them reported it —
+* the number a budget reads instead of summing runs (ADR-0017).
+*/
+function createRecordSpendHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$1, RecordSpendRequestSchema, "spend body");
+		const entry = await storage.spend.append(project, {
+			id: randomUUID(),
+			at: new Date(body.at ?? Date.now()).toISOString(),
+			costUsd: body.costUsd,
+			label: body.label,
+			...body.ciRunId ? { ciRunId: body.ciRunId } : {},
+			...body.runUrl ? { runUrl: body.runUrl } : {}
+		});
+		sendJson(ctx.res, 201, entry);
+	};
+}
+/** GET /api/v1/projects/:project/spend?since=&until= — newest first, plus the window's total. */
+function createGetSpendHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const window = requireWindowParams(ctx.url);
+		const entries = await storage.spend.list(project, window);
+		sendJson(ctx.res, 200, {
+			project,
+			since: window.since ?? null,
+			until: window.until ?? null,
+			totalUsd: entries.reduce((sum, e) => sum + e.costUsd, 0),
+			entries
+		});
+	};
+}
+//#endregion
 //#region src/hub/core/rerun.ts
 /**
 * When each deployed commit reached the environment. A baseline read at that
@@ -18850,10 +19227,32 @@ const HTML_BODY = `
       <div class="page-bar">
         <h1 data-i18n="runs.title">Runs</h1>
         <span class="total" id="runs-total-cost" hidden></span>
+        <span class="total" id="runs-capped" hidden></span>
+        <!-- Ruled off from the two above because it counts something else: the
+             project's whole spend, not what the listed runs cost. -->
+        <span class="total apart" id="runs-spend-24h" hidden></span>
         <div class="spacer"></div>
         ${refreshButton("runs-refresh")}
       </div>
       <div class="content">
+        <!-- Deliberately selects and a native date input, not the .fchip
+             toggles the rest of the page uses: these three refetch, and a chip
+             group beside a date box would be the odd one out. Their options
+             are built by syncRunsFilters. -->
+        <div class="toolbar">
+          <div class="fgroup">
+            <label class="fgroup-label" for="runs-f-date" data-i18n="runs.filter.date">Date</label>
+            <input class="fctl" type="date" id="runs-f-date">
+          </div>
+          <div class="fgroup">
+            <label class="fgroup-label" for="runs-f-kind" data-i18n="runs.filter.kind">Kind</label>
+            <select class="fctl" id="runs-f-kind"></select>
+          </div>
+          <div class="fgroup">
+            <label class="fgroup-label" for="runs-f-status" data-i18n="runs.filter.status">Status</label>
+            <select class="fctl" id="runs-f-status"></select>
+          </div>
+        </div>
         <div class="card" id="runs-card">
           <div class="table-wrap">
             <table>
@@ -19214,6 +19613,7 @@ const CSS = `
   .page-bar .back svg { width: 15px; height: 15px; }
   .page-bar .filters { display: flex; gap: 8px; margin-left: 8px; }
   .page-bar .total { font-size: 12px; color: var(--muted); font-variant-numeric: tabular-nums; white-space: nowrap; }
+  .page-bar .total.apart { padding-left: 12px; border-left: 1px solid var(--border); }
   .page-bar .spacer { flex: 1; }
   .content { padding: 18px 24px 48px; }
 
@@ -19263,7 +19663,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 +19684,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 +19704,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
@@ -19625,6 +20042,13 @@ const CSS = `
   .fchip[aria-pressed="true"] { background: var(--accent); color: var(--accent-fg); border-color: var(--accent); }
   .fchip .fcount { margin-left: 6px; font-variant-numeric: tabular-nums; color: var(--muted-2); }
   .fchip[aria-pressed="true"] .fcount { color: var(--accent-fg); opacity: 0.7; }
+  /* A filter control that picks one value out of many (the runs bar's date box
+     and selects), sized to itself — .input is the full-width form field the
+     sheets use, which in a toolbar row swallows the whole line. */
+  .fctl { height: 32px; padding: 0 8px; border: 1px solid var(--border-strong); border-radius: var(--radius-sm); background: var(--surface); color: var(--fg); font: inherit; font-size: 13px; }
+  /* Native chrome (the date picker's glyph, the select's arrow) takes its
+     colours from the color-scheme property, not from any class of ours. */
+  .dark .fctl { color-scheme: dark; }
 
   .chip.live { background: var(--info-bg); color: var(--info); border-color: var(--info-border); }
   .badge.ok { background: var(--pass-bg); color: var(--pass); border-color: var(--pass-border); }
@@ -19729,7 +20153,10 @@ const CLIENT_JS = `
   var PREDICTED_LABELS = ${JSON.stringify(PREDICTED_LABELS)};
   var AGENT_BROWSER_TARGET = ${JSON.stringify(AGENT_BROWSER_TARGET)};
   var GUIDANCE_KINDS = ${JSON.stringify(GUIDANCE_KINDS)};
-  var state = { token: "", project: "", profile: "default", detailRunId: "", jobPollToken: 0 };
+  // Every status a run can be in, from the contract that defines them, so the
+  // runs filter offers exactly what a row's badge can say.
+  var RUN_STATUSES = ${JSON.stringify(RunStatusSchema.options)};
+  var state = { token: "", project: "", profile: "default", detailRunId: "", jobPollToken: 0, runsLoadToken: 0, spendLoadToken: 0 };
   var knownProfiles = [];
   var TOKEN_KEY = "ccqa-hub-token";
   var LANG_KEY = "ccqa-hub-lang";
@@ -19754,9 +20181,13 @@ const CLIENT_JS = `
       "projects.title": "Projects", "projects.new": "New project",
       "runs.title": "Runs", "runs.empty": "Select a project to see its runs.",
       "runs.none": "No runs yet for this project.", "projects.none": "No projects yet. Create one to get started.", "projects.noneShort": "No projects yet",
+      "runs.noMatch": "No runs match this filter.",
       "runs.col.run": "Run", "runs.col.branch": "Branch", "runs.col.status": "Status",
       "runs.col.specs": "Specs", "runs.col.cost": "Cost", "runs.col.created": "Created",
-      "runs.totalCost": "Cost of these {n}:",
+      "runs.totalCost": "Cost of these {n}:", "runs.capped": "showing the first {n}",
+      "runs.spend24h": "All spend, last 24h:",
+      "runs.filter.date": "Date", "runs.filter.kind": "Kind", "runs.filter.status": "Status",
+      "runs.filter.all": "All",
       "detail.back": "Runs", "detail.specs": "Specs",
       "detail.download": "Download artifacts",
       "detail.triage": "Triage",
@@ -19765,6 +20196,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 +20205,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",
@@ -19912,9 +20344,13 @@ const CLIENT_JS = `
       "projects.title": "プロジェクト", "projects.new": "新規プロジェクト",
       "runs.title": "実行", "runs.empty": "プロジェクトを選択すると実行一覧が表示されます。",
       "runs.none": "このプロジェクトにはまだ実行がありません。", "projects.none": "まだプロジェクトがありません。作成して始めましょう。", "projects.noneShort": "プロジェクトなし",
+      "runs.noMatch": "条件に一致する実行はありません。",
       "runs.col.run": "実行", "runs.col.branch": "ブランチ", "runs.col.status": "ステータス",
       "runs.col.specs": "スペック", "runs.col.cost": "コスト", "runs.col.created": "作成",
-      "runs.totalCost": "この {n} 件のコスト:",
+      "runs.totalCost": "この {n} 件のコスト:", "runs.capped": "先頭 {n} 件のみ表示",
+      "runs.spend24h": "直近 24 時間の全支出:",
+      "runs.filter.date": "日付", "runs.filter.kind": "種類", "runs.filter.status": "結果",
+      "runs.filter.all": "すべて",
       "detail.back": "実行", "detail.specs": "スペック",
       "detail.download": "アーティファクトをダウンロード",
       "detail.triage": "トリアージ",
@@ -19923,6 +20359,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 +20368,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": "実行中",
@@ -20081,6 +20518,9 @@ const CLIENT_JS = `
     for (var i = 0; i < nodes.length; i++) { nodes[i].textContent = t(nodes[i].getAttribute("data-i18n")); }
     var phs = document.querySelectorAll("[data-i18n-ph]");
     for (var j = 0; j < phs.length; j++) { phs[j].placeholder = t(phs[j].getAttribute("data-i18n-ph")); }
+    // The runs filters' options are built rather than marked up, so they are
+    // not reached by the two loops above.
+    syncRunsFilters();
     document.documentElement.lang = lang;
   }
 
@@ -20310,6 +20750,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.
@@ -20533,13 +20988,58 @@ const CLIENT_JS = `
 
   // ── runs list ────────────────────────────────────────────────────────
 
+  var RUNS_LIMIT = 50;
+  // Outlives every render, so a refresh or a language switch comes back to the
+  // list the operator was looking at.
+  var runsFilter = { date: "", kind: "", status: "" };
+  function runsFilterActive() { return !!(runsFilter.date || runsFilter.kind || runsFilter.status); }
+
+  function runsQuery() {
+    var q = "/api/v1/runs?project=" + encodeURIComponent(state.project) + "&limit=" + RUNS_LIMIT;
+    if (runsFilter.kind) q += "&kind=" + encodeURIComponent(runsFilter.kind);
+    if (runsFilter.status) q += "&status=" + encodeURIComponent(runsFilter.status);
+    if (runsFilter.date) {
+      // The picked day becomes [local midnight, next local midnight). The API
+      // takes instants and carries no timezone, so the day has to be resolved
+      // here — against the clock of whoever picked it.
+      var p = runsFilter.date.split("-");
+      var start = new Date(+p[0], +p[1] - 1, +p[2]);
+      var next = new Date(+p[0], +p[1] - 1, +p[2] + 1);
+      q += "&since=" + encodeURIComponent(start.toISOString()) + "&until=" + encodeURIComponent(next.toISOString());
+    }
+    return q;
+  }
+
+  // Both selects take their values from the tables that label the rows, so a
+  // filter cannot name a kind or a status differently from the run it hides.
+  // Called on boot and on a language switch — the only times the labels move.
+  function syncRunsFilters() {
+    document.getElementById("runs-f-date").value = runsFilter.date;
+    fillRunsFilter("runs-f-kind", Object.keys(KINDS), function (k) { return t(kindOf(k).label); }, runsFilter.kind);
+    fillRunsFilter("runs-f-status", RUN_STATUSES, function (s) { return t("status." + s); }, runsFilter.status);
+  }
+
+  function fillRunsFilter(id, values, labelOf, selected) {
+    var sel = document.getElementById(id);
+    clear(sel);
+    var any = el("option", null, t("runs.filter.all"));
+    any.value = "";   // the empty value is what the query omits
+    sel.appendChild(any);
+    values.forEach(function (v) {
+      var opt = el("option", null, labelOf(v));
+      opt.value = v;
+      sel.appendChild(opt);
+    });
+    sel.value = selected;
+  }
+
   // What the listed runs cost together — the accumulating number an operator
   // reads to decide how often CI should run, so it follows whatever filter
   // produced the list. Hidden when no listed run carries a cost at all, since
   // a "$0.0000" total would read as "CI is free" rather than "nothing measured".
   //
-  // The label names the run count on purpose. The list is capped (limit=50), so
-  // an unqualified "total" would quietly under-report a project's spend the
+  // The label names the run count on purpose. The list is capped (RUNS_LIMIT),
+  // so an unqualified "total" would quietly under-report a project's spend the
   // moment it has more runs than that — the one number this feature exists to
   // get right.
   function renderRunsTotalCost(runs) {
@@ -20561,14 +21061,38 @@ const CLIENT_JS = `
     }
   }
 
+  // The project's whole spend over the last 24 hours — deliberately not the
+  // list's window or filter: the two numbers differ by everything that calls
+  // Claude without leaving a run behind, which is why both are here. Hidden
+  // when nothing was reported, since "$0.0000" would claim a free day.
+  function loadRunsSpend() {
+    var span = document.getElementById("runs-spend-24h");
+    span.hidden = true;
+    var token = ++state.spendLoadToken;
+    var since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    apiFetch("/api/v1/projects/" + encodeURIComponent(state.project) + "/spend?since=" + encodeURIComponent(since))
+      .then(function (data) {
+        if (token !== state.spendLoadToken) return;
+        if (!data.entries.length) return;
+        span.hidden = false;
+        span.textContent = t("runs.spend24h") + " " + costText(data.totalUsd);
+      })
+      .catch(function () { /* the runs list is the page; a missing total must not replace it with an error */ });
+  }
+
   function renderRunsList(runs) {
     var tbody = document.getElementById("runs-tbody");
     clear(tbody);
     renderRunsTotalCost(runs);
+    // A full page is almost certainly a truncated one, and under a date filter
+    // that turns the total beside it into a day's spend that stops at the cap.
+    var capped = document.getElementById("runs-capped");
+    capped.hidden = runs.length < RUNS_LIMIT;
+    capped.textContent = t("runs.capped").replace("{n}", RUNS_LIMIT);
     var empty = document.getElementById("runs-empty");
     if (runs.length === 0) {
       empty.hidden = false;
-      empty.textContent = t("runs.none");
+      empty.textContent = t(runsFilterActive() ? "runs.noMatch" : "runs.none");
       return;
     }
     empty.hidden = true;
@@ -20580,12 +21104,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 +21124,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)));
@@ -20633,19 +21159,33 @@ const CLIENT_JS = `
     });
   }
 
-  function loadRuns() {
-    var empty = document.getElementById("runs-empty");
-    empty.hidden = true;
-    apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&limit=50")
-      .then(function (data) { renderRunsList(data.runs); })
+  // Compared against the live token before painting, so a slower earlier
+  // response cannot land last: holding an arrow key down in the date box fires
+  // one request per day passed, and the table would end up on the wrong one.
+  function loadRunsList() {
+    var token = ++state.runsLoadToken;
+    document.getElementById("runs-empty").hidden = true;
+    apiFetch(runsQuery())
+      .then(function (data) {
+        if (token !== state.runsLoadToken) return;
+        renderRunsList(data.runs);
+      })
       .catch(function (err) {
-        clear(document.getElementById("runs-tbody"));
-        renderRunsTotalCost([]);
+        if (token !== state.runsLoadToken) return;
+        renderRunsList([]);
+        var empty = document.getElementById("runs-empty");
         empty.hidden = false;
         empty.textContent = "Error loading runs: " + err.message;
       });
   }
 
+  // Entering the view or refreshing it. The spend readout is a fixed window,
+  // so a filter change reloads the list alone.
+  function loadRuns() {
+    loadRunsSpend();
+    loadRunsList();
+  }
+
   // ── run detail: header ──────────────────────────────────────────────
 
   function renderRunHead(run) {
@@ -20663,7 +21203,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 +21237,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 +21346,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 +22546,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 = [];
@@ -23464,6 +24014,14 @@ const CLIENT_JS = `
 
   document.getElementById("detail-back").addEventListener("click", function () { location.hash = "#/runs"; });
   document.getElementById("runs-refresh").addEventListener("click", loadRuns);
+  // Every control refetches: the window and the kinds are the server's to
+  // apply, so filtering client-side would only narrow the same capped page.
+  [["runs-f-date", "date"], ["runs-f-kind", "kind"], ["runs-f-status", "status"]].forEach(function (pair) {
+    document.getElementById(pair[0]).addEventListener("change", function (e) {
+      runsFilter[pair[1]] = e.target.value;
+      loadRunsList();
+    });
+  });
   document.getElementById("learn-run").addEventListener("click", startLearn);
   document.getElementById("jobs-refresh").addEventListener("click", loadJobs);
   // Wrap so the click PointerEvent isn't passed as loadSecrets' statusAfter
@@ -23734,7 +24292,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 +24492,10 @@ 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));
+	router.post("/api/v1/projects/:project/spend", createRecordSpendHandler(storage));
+	router.get("/api/v1/projects/:project/spend", createGetSpendHandler(storage));
 	const sessionConfig = {
 		store: storage.sessions,
 		encryptionKey: config.encryptionKey
@@ -23967,6 +24530,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 +24679,8 @@ 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)
+*   spend/<project>.json                         (SpendLog, pruned to its retention window)
 *
 * 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 +24772,46 @@ 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`);
+}
+function spendPath(root, project) {
+	return join(root, "spend", `${project}.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 +24982,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 +24989,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 +25009,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 +25016,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 +25025,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 +25035,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 +25049,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));
 		},
@@ -24462,6 +25060,22 @@ function createFilePromptStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/time-window.ts
+/**
+* The half-open `[since, until)` window the run and spend listings both take,
+* as a predicate over a record's ISO-8601 timestamp. Compared as instants, not
+* as strings: the ends come off the wire in whatever offset the caller wrote
+* them in, while the stored field is always UTC.
+*/
+function windowFilter(q) {
+	const from = q.since === void 0 ? null : Date.parse(q.since);
+	const to = q.until === void 0 ? null : Date.parse(q.until);
+	return (at) => {
+		const instant = Date.parse(at);
+		return (from === null || instant >= from) && (to === null || instant < to);
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/run-store.ts
 /**
 * Read one run record for an aggregate scan, tolerating a bad entry: a
@@ -24494,8 +25108,12 @@ function createFileRunStore(root) {
 				};
 			});
 		},
-		async list({ project, branch, status, limit }) {
+		async list({ project, branch, status, kinds, since, until, limit }) {
 			const ids = await listSubdirsOrEmpty(runsDir(root));
+			const inWindow = windowFilter({
+				since,
+				until
+			});
 			const runs = [];
 			for (const id of ids) {
 				const run = await readRunOrSkip(root, id);
@@ -24503,6 +25121,8 @@ 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;
+				if (!inWindow(run.createdAt)) continue;
 				runs.push(run);
 			}
 			runs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
@@ -24521,14 +25141,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");
@@ -24583,6 +25195,55 @@ function createFileSecretStore(root, kind) {
 		}
 	};
 }
+/** Spend storage: one JSON document per project, pruned as it is appended to. */
+function createFileSpendStore(root) {
+	return {
+		async append(project, entry) {
+			assertSafeName(project, "project");
+			const path = spendPath(root, project);
+			const cutoff = Date.now() - 2160 * 60 * 60 * 1e3;
+			await updateJson(path, (current) => {
+				return { entries: [...readEntries(current, path).filter((e) => Date.parse(e.at) >= cutoff && !supersededBy(e, entry)), entry] };
+			});
+			return entry;
+		},
+		async list(project, window) {
+			assertSafeName(project, "project");
+			const path = spendPath(root, project);
+			const inWindow = windowFilter(window);
+			return readEntries(await readJson(path), path).filter((e) => inWindow(e.at)).sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+		}
+	};
+}
+/**
+* A second push from the same CI run under the same label replaces the first
+* rather than adding to it: a retried job really does spend again, but it also
+* rewrites its cost file from scratch, so its new total is the whole of it.
+*/
+function supersededBy(stored, incoming) {
+	return incoming.ciRunId !== void 0 && stored.ciRunId === incoming.ciRunId && stored.label === incoming.label;
+}
+/**
+* Entries parsed one at a time, keeping the survivors: a whole-document parse
+* would answer "this project spent nothing" for one bad entry, and a budget
+* reads that as zero rather than as an error. What is lost is logged, since
+* nothing else would ever say so.
+*/
+function readEntries(raw, path) {
+	if (raw === null || raw === void 0) return [];
+	const stored = raw.entries;
+	if (!Array.isArray(stored)) {
+		console.error(`hub: spend log at ${path} is not a spend document; ignoring what it holds`);
+		return [];
+	}
+	const entries = [];
+	for (const value of stored) {
+		const parsed = SpendEntrySchema.safeParse(value);
+		if (parsed.success) entries.push(parsed.data);
+	}
+	if (entries.length < stored.length) console.error(`hub: skipping ${stored.length - entries.length} unreadable spend entries in ${path}`);
+	return entries;
+}
 //#endregion
 //#region src/hub/core/storage/file/triage-store.ts
 function createFileTriageStore(root) {
@@ -24622,7 +25283,9 @@ function createFileHubStorage(dataDir) {
 		ledger: createFileSpecLedgerStore(dataDir),
 		driftLedger: createFileDriftLedgerStore(dataDir),
 		deploys: createFileDeployStore(dataDir),
-		locks: createFileLockStore(dataDir)
+		locks: createFileLockStore(dataDir),
+		acks: createFileAckStore(dataDir),
+		spend: createFileSpendStore(dataDir)
 	};
 }
 //#endregion