ccqa 1.13.0 → 1.15.0

package/dist/bin/ccqa.mjs

@@ -477,7 +477,7 @@ function getBlocksDir(cwd) {
 /**
 * Inverse of `getBlockDir`. Given a file path that appears in a git diff,
 * return the block name if the path points at the block's spec.yaml, else
-* null. Used by `drift --changed` to invalidate specs whose included blocks
+* null. Used by `audit --only-affected-by` to invalidate specs whose included blocks
 * were edited. (v0.4 inlines blocks into every spec's own trace, so the
 * block directory holds only spec.yaml — no per-block recording lives
 * here anymore.)
@@ -524,24 +524,22 @@ const USER_PROMPT_MAX_BYTES = 32768;
 * Load the prompt bundle from the hub for one guidance kind ("record" /
 * "live" / an LLM-generation target such as "playwright" or "runn").
 * Best-effort: no hub client, a fetch failure, or both prompts absent all
-* resolve to null — a broken/missing hub prompt must never stop a run.
+* A prompt that was never stored resolves to null. A hub that cannot be
+* reached throws: running with silently different guidance than the project
+* configured is worse than stopping.
 */
 async function loadPromptBundleFromHub(ctx, kind) {
 	if (!ctx) return null;
 	const userName = `${kind}.user`;
 	const agentName = `${kind}.agent`;
-	try {
-		const [userText, agentText] = await Promise.all([ctx.hub.getPrompt(ctx.project, userName).then(normalizePromptText), ctx.hub.getPrompt(ctx.project, agentName).then(normalizePromptText)]);
-		return assemblePromptBundle({
-			text: userText,
-			label: userName
-		}, {
-			text: agentText,
-			label: agentName
-		});
-	} catch {
-		return null;
-	}
+	const [userText, agentText] = await Promise.all([ctx.hub.getPrompt(ctx.project, userName).then(normalizePromptText), ctx.hub.getPrompt(ctx.project, agentName).then(normalizePromptText)]);
+	return assemblePromptBundle({
+		text: userText,
+		label: userName
+	}, {
+		text: agentText,
+		label: agentName
+	});
 }
 /**
 * Shared concatenation logic behind `loadPromptBundleFromHub`: section
@@ -557,7 +555,7 @@ function assemblePromptBundle(user, agent) {
 		loaded.push(user.label);
 	}
 	if (agent.text !== null) {
-		sections.push(`### Agent learnings (auto-updated by ccqa --update-agent-prompt)\n\n${agent.text}`);
+		sections.push(`### Agent learnings (auto-updated by ccqa's --learn-*-prompt flags)\n\n${agent.text}`);
 		loaded.push(agent.label);
 	}
 	let text = sections.join("\n\n");
@@ -2475,7 +2473,7 @@ const FailureAnalysisSchema = z.object({
 });
 /**
 * What a drift audit may conclude, in the same vocabulary `ccqa run
-* --failure-analysis` uses for a failure. One question, one answer, the same
+* --on-fail-explain` uses for a failure. One question, one answer, the same
 * words whether it was reached by running the spec or by reading the code — so
 * a reader never translates between two taxonomies, and the hub renders,
 * grades and learns from both through one path.
@@ -3312,7 +3310,7 @@ function relativeToCwd(path, cwd) {
 /** The model's reply: a diagnosis, or `null` for "the spec still matches the code". */
 const DriftReplySchema = z.object({ drift: DriftDiagnosisSchema.nullable() });
 /**
-* How a label reads against `--severity`. The threshold asks "would a
+* How a label reads against `--exit-on`. The threshold asks "would a
 * deterministic replay fail today", which is what the label already answers:
 * both findings mean the spec no longer describes the code, while `UNKNOWN`
 * means the audit could not tell and should not fail a build on its own.
@@ -3971,14 +3969,10 @@ ${customPrompt.guidance}
 */
 async function fetchCustomPrompt(ctx) {
 	if (!ctx) return null;
-	try {
-		const raw = await ctx.hub.getPrompt(ctx.project, "analysis-custom-prompt");
-		if (raw === null) return null;
-		const parsed = AnalysisCustomPromptSchema.safeParse(JSON.parse(raw));
-		return parsed.success ? parsed.data : null;
-	} catch {
-		return null;
-	}
+	const raw = await ctx.hub.getPrompt(ctx.project, "analysis-custom-prompt");
+	if (raw === null) return null;
+	const parsed = AnalysisCustomPromptSchema.safeParse(JSON.parse(raw));
+	return parsed.success ? parsed.data : null;
 }
 /**
 * Render the human-maintained `triage.user` guidance as a prompt section, or
@@ -4006,12 +4000,8 @@ ${trimmed}
 */
 async function fetchTriageUserPrompt(ctx) {
 	if (!ctx) return null;
-	try {
-		const trimmed = (await ctx.hub.getPrompt(ctx.project, "triage.user"))?.trim();
-		return trimmed ? trimmed : null;
-	} catch {
-		return null;
-	}
+	const trimmed = (await ctx.hub.getPrompt(ctx.project, "triage.user"))?.trim();
+	return trimmed ? trimmed : null;
 }
 /**
 * Short, stable content hash for a `triage.user` prompt. The Markdown body
@@ -4812,12 +4802,12 @@ async function readDotenv(path) {
 	}
 	return parseDotenv(content);
 }
-/** Absolute path of the default `.env` ccqa loads when `--profile` is absent. */
+/** Absolute path of the default `.env` ccqa loads when `--hub-profile` is absent. */
 function defaultEnvPath(cwd) {
 	return join(cwd, ".env");
 }
 /**
-* Load `<cwd>/.env`, the default when no `--profile` is given. A missing `.env`
+* Load `<cwd>/.env`, the default when no `--hub-profile` is given. A missing `.env`
 * is fine (returns `null`) — the run falls back to the existing `process.env`.
 */
 async function loadDefaultEnv(cwd) {
@@ -5023,7 +5013,7 @@ function addLanguageOption(command) {
 * `record`), registered identically so help text and behaviour don't drift.
 */
 function addProfileOption(command) {
-	return command.option("--profile <name>", "Load this profile's variables from the hub into the environment before resolving spec ${VAR} references (URLs, credentials), so one spec can target dev/stg/prd without per-environment copies. Profile values override the inherited environment. Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN).");
+	return command.option("--hub-profile <name>", "Load this profile's variables from the hub into the environment before resolving spec ${VAR} references (URLs, credentials), so one spec can run as a different tenant, account or role without a copy per set of values. A profile is a value set, not an environment — ccqa tracks one verification environment. Profile values override the inherited environment. Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN).");
 }
 /**
 * Shared `--hub-url` / `--hub-token` flags for commands that optionally talk
@@ -5901,7 +5891,7 @@ async function runVerificationLoop(p, ref, state) {
 	const runCommand = p.ctx.targetConfig.runCommand;
 	if (!runCommand) return true;
 	const maxRetries = p.ctx.fix.mode === "non-interactive" ? 0 : p.ctx.fix.maxRetries;
-	if (!p.ctx.fix.useSnapshot) warn(`--no-snapshot has no effect on the ${p.target} target — it captures no browser snapshot; the fix loop uses the command's output instead`);
+	if (!p.ctx.fix.useSnapshot) warn(`--no-session-pin has no effect on the ${p.target} target — it captures no browser snapshot; the fix loop uses the command's output instead`);
 	for (let attempt = 0;; attempt++) {
 		const testFiles = [...state.entries()].filter(([, f]) => f.kind === "test").map(([rel]) => rel);
 		const artifactsDir = await mkdtemp(join(tmpdir(), "ccqa-verify-artifacts-"));
@@ -6089,8 +6079,8 @@ const C$1 = {
 * script, so it keeps its own caller in `cli/run-live.ts`; only the
 * `ANALYSIS_DISABLED` string is shared with it.
 */
-/** `analysisSkipped` for a failed row when `--failure-analysis` was not requested. */
-const ANALYSIS_DISABLED = "skipped: --failure-analysis not enabled";
+/** `analysisSkipped` for a failed row when `--on-fail-explain` was not requested. */
+const ANALYSIS_DISABLED = "skipped: --on-fail-explain not enabled";
 /**
 * Create one analysis pass. The returned object is stateful on purpose: the
 * "source diff unavailable" notice and the summary block's header are printed
@@ -6610,7 +6600,7 @@ async function detectDefaultBranch(cwd) {
 /**
 * Fetch the last-green ledger for this run — one hub round trip, logged as
 * the run's analysis-base meta line. Fails fast (RunUsageError) when the hub
-* can't serve it: `--failure-analysis=last-green` explicitly opted into
+* can't serve it: `--on-fail-explain` explicitly opted into
 * hub-backed baselines, so a broken hub connection is a usage error, never a
 * silent no-baseline run.
 */
@@ -6633,7 +6623,7 @@ async function fetchLastGreenLedger(hubCtx, profile, cwd) {
 	return entries;
 }
 /**
-* Per-spec baseline resolver for `--failure-analysis=last-green`. A spec
+* Per-spec baseline resolver for `--on-fail-explain` without an explicit base. A spec
 * missing from the ledger (never green on a pushed run yet) or whose
 * baseline commit isn't in this checkout resolves to a skip — the run
 * continues; only that spec's classification is withheld, with the reason
@@ -6687,7 +6677,7 @@ async function deployHeadSha(hub, project, profile) {
 *
 * Captured before any spec executes and asserted on both push paths
 * (`?deployedSha=` on `POST /runs` via `ccqa hub push`, and on `POST
-* /runs/open` for `--push-report`). Left to itself the hub reads its own
+* /runs/open` for `--report-to-hub`). Left to itself the hub reads its own
 * deploy-log head when the call lands — after the whole run for a single-shot
 * push, after the deterministic phase for an incremental one — so a deploy
 * landing in that window would be recorded as the run's baseline and
@@ -6712,7 +6702,7 @@ async function tryDeployHeadSha(hubCtx, profile) {
 *
 * This exists because a selection can be wrong in a way that costs money.
 * `ccqa select-specs`'s model judgment is not infallible, and both
-* `--changed <ref>` and `--changed=last-run` decide from it, so a human has to
+* `--only-affected-by` and `--only-hub-rerun-needed` decide from it, so a human has to
 * be able to read the selection back before a live spec spends a Claude
 * budget on it.
 *
@@ -6744,53 +6734,9 @@ function formatDryRunLines(agentBrowser, routed) {
 	return tagged.map((t) => `  ${t.key.padEnd(width)}  ${t.tag}`);
 }
 //#endregion
-//#region src/run/audited-clean.ts
-/**
-* Fetch the drift ledger and reduce it to the specs that are safe to run.
-*
-* A spec qualifies only when the ledger holds an entry for it *and* that entry
-* found no drift. A spec that has never been audited does not qualify: the
-* point of the flag is to spend a run only where a cheap audit already said
-* the spec still describes the code, and "never looked" is not that.
-*/
-async function fetchAuditedLedger(hubCtx) {
-	let ledger;
-	try {
-		ledger = await hubCtx.hub.getDriftLedger(hubCtx.project);
-	} catch (err) {
-		throw new RunUsageError(`--only-audited-clean: could not fetch the drift ledger from the hub: ${errMessage(err)}`);
-	}
-	const clean = /* @__PURE__ */ new Set();
-	const audited = /* @__PURE__ */ new Set();
-	for (const [key, entry] of Object.entries(ledger.specs)) {
-		audited.add(key);
-		if (entry.label === null) clean.add(key);
-	}
-	return {
-		clean,
-		audited
-	};
-}
-function selectAuditedClean(specs, ledger) {
-	const selected = [];
-	let unaudited = 0;
-	let drifted = 0;
-	for (const spec of specs) {
-		const key = specKey(spec);
-		if (ledger.clean.has(key)) selected.push(spec);
-		else if (ledger.audited.has(key)) drifted++;
-		else unaudited++;
-	}
-	return {
-		selected,
-		unaudited,
-		drifted
-	};
-}
-//#endregion
 //#region src/run/rerun-selection.ts
 /**
-* `ccqa run --changed=last-run`: select specs from the hub's re-run verdicts
+* `ccqa run --only-hub-rerun-needed`: select specs from the hub's re-run verdicts
 * instead of from a git diff (ADR-0010). The baseline is not a ref at all —
 * it is each spec's own last run, positioned against the deploy log the
 * consuming deploy job feeds the hub — so this path does no git work.
@@ -6802,12 +6748,12 @@ function selectAuditedClean(specs, ledger) {
 /** First ccqa release whose hub serves `GET /projects/:project/rerun`. */
 const RERUN_MIN_HUB_VERSION = "1.9";
 /**
-* The profile `--changed=last-run` asks about. Mandatory: two environments sit
+* The profile `--only-hub-rerun-needed` asks about. Mandatory: two environments sit
 * at different commits and the deploy log is per-profile, so "needs re-run"
 * has no profile-free answer.
 */
 function requireRerunProfile(profile) {
-	if (profile === void 0) throw new RunUsageError("--only-stale requires --profile <name>: the deploy log it reads is per-profile, so which specs need a re-run has no answer without one");
+	if (profile === void 0) throw new RunUsageError("--only-hub-rerun-needed requires --hub-profile <name>: the deploy log it reads is per-profile, so which specs need a re-run has no answer without one");
 	return profile;
 }
 /**
@@ -6820,9 +6766,9 @@ async function fetchRerunReport(hubCtx, profile) {
 		report = await hubCtx.hub.getRerun(hubCtx.project, { profile });
 	} catch (err) {
 		if (err instanceof HubApiError && err.status === 404) throw new RunUsageError(explainNotFound(hubCtx, err));
-		throw new RunUsageError(`--only-stale: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
+		throw new RunUsageError(`--only-hub-rerun-needed: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
 	}
-	if (report.deployHead === null) throw new RunUsageError(`--only-stale: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or pass an explicit baseline (--changed=<ref>).`);
+	if (report.deployHead === null) throw new RunUsageError(`--only-hub-rerun-needed: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or select with --only-affected-by <ref> instead.`);
 	return {
 		...report,
 		deployHead: report.deployHead
@@ -6834,11 +6780,12 @@ async function fetchRerunReport(hubCtx, profile) {
 * means the hub does not serve this route at all.
 */
 function explainNotFound(hubCtx, err) {
-	if (err.code === "no_perspectives") return `--only-stale: project "${hubCtx.project}" has no perspectives document on the hub, so no spec is registered to compare against a deploy. Run \`ccqa perspectives\` first.`;
-	return `--only-stale: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or pass an explicit baseline (--changed=<ref>).`;
+	if (err.code === "no_perspectives") return `--only-hub-rerun-needed: project "${hubCtx.project}" has no perspectives document on the hub, so no spec is registered to compare against a deploy. Run \`ccqa perspectives\` first.`;
+	return `--only-hub-rerun-needed: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or select with --only-affected-by <ref> instead.`;
 }
 /** States the summary line reports, worst-known-first. */
 const SUMMARY_ORDER = [
+	"blocked",
 	"needed",
 	"unknown",
 	"neverRun",
@@ -6856,7 +6803,7 @@ const UNANSWERABLE = new Set([
 *
 * `needed` is always selected. `unknown` and `neverRun` are "the question
 * cannot be answered", so they are excluded by default and opted into with
-* `--include-unknown` — fail-open on request, never silently. `notNeeded` and
+* `--only-hub-rerun-needed-with-unknown` — fail-open on request, never silently. `notNeeded` and
 * `notEvaluated` are never selected.
 */
 function selectSpecsNeedingRerun(specs, report, opts) {
@@ -7634,7 +7581,7 @@ function safeOriginPath(href) {
 *
 * Two kinds share one namespace:
 *  - "guidance": the record/live prompt bundle — `.user.md` (human-maintained)
-*    and `.agent.md` (auto-rewritten by `ccqa run --update-agent-prompt`) —
+*    and `.agent.md` (auto-rewritten by `ccqa run --learn-hub-live-prompt`) —
 *    plus `triage.user`, the human-maintained guidance injected into the
 *    failure-analysis (triage) prompt.
 *  - "custom-prompt": `analysis-custom-prompt` — Claude-written calibration guidance
@@ -8039,11 +7986,19 @@ z.record(z.string(), SpecTouchSchema);
 const RerunStateSchema = z.enum([
 	"needed",
 	"notNeeded",
+	"blocked",
 	"unknown",
 	"neverRun",
 	"notEvaluated"
 ]);
 /**
+* Why a spec is `blocked`. Always carried: the two answers differ in who
+* repairs them and how long that takes — a stale recording is re-recorded
+* automatically within minutes, a changed spec waits for a human — so a view
+* that showed only "blocked" would hide the distinction that matters most.
+*/
+const RerunBlockedReasonSchema = z.enum(["testDrift", "specChange"]);
+/**
 * Why a spec is `unknown`. Always carried, so the view can name the missing
 * input ("no deploy log for this profile") instead of shrugging. `unknown` is
 * never rendered as "not needed".
@@ -8072,6 +8027,7 @@ const DeployRefSchema = z.object({
 const SpecRerunSchema = z.object({
 	state: RerunStateSchema,
 	reason: RerunUnknownReasonSchema.optional(),
+	blockedReason: RerunBlockedReasonSchema.optional(),
 	lastRun: SpecLedgerEntrySchema.nullable(),
 	lastGreen: SpecLedgerEntrySchema.nullable(),
 	lastRed: SpecLedgerEntrySchema.nullable(),
@@ -8103,7 +8059,7 @@ z.object({
 	lastRed: z.record(z.string(), SpecLedgerEntrySchema).default({})
 });
 /**
-* One spec's last drift audit, as recorded by `ccqa drift --push`. Unlike the
+* One spec's last drift audit, as recorded by `ccqa audit --report-to-hub`. Unlike the
 * spec ledger above, this carries no profile: drift asks whether a spec still
 * describes the code, which has nothing to do with which environment is
 * running it (ADR-0010 draws the same line for "needs re-run").
@@ -8313,7 +8269,7 @@ function isCcqaPath(path) {
 }
 /**
 * A malformed reply costs the whole selection, so it is worth one more call
-* before giving up. `ccqa drift` retries per spec for the same reason; this
+* before giving up. `ccqa audit` retries per spec for the same reason; this
 * call carries every undecided spec at once, so the blast radius is larger,
 * not smaller. Observed in practice: three runs over one commit produced a
 * parse failure, a clean answer, and a different clean answer.
@@ -8510,7 +8466,7 @@ const sessionCaptureCommand = new Command("capture").description("Open a headed
 		error(err.message);
 		process.exit(2);
 	}
-	header("session bootstrap", name);
+	header("session capture", name);
 	meta("project", project);
 	meta("profile", opts.profile ?? "default");
 	blank();
@@ -8631,7 +8587,7 @@ const sessionPush = new Command("push").description("Upload a locally-saved brow
 		state = await loadStorageState(path);
 	} catch (err) {
 		error(`could not read session "${name}" at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-		hint(`create it first with:  ccqa session bootstrap ${name}${opts.profile ? ` --profile ${opts.profile}` : ""}`);
+		hint(`create it first with:  ccqa hub session capture ${name}${opts.profile ? ` --profile ${opts.profile}` : ""}`);
 		process.exit(2);
 	}
 	await connect(opts).putSession(project, profile, name, state);
@@ -8718,12 +8674,12 @@ const promptPush = new Command("push").description("Upload a locally-generated p
 		body = await readFile(path, "utf8");
 	} catch (err) {
 		error(`could not read prompt "${name}" at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-		hint("nothing to push; generate it first (e.g. ccqa run --update-agent-prompt)");
+		hint("nothing to push; generate it first (e.g. ccqa run --learn-hub-live-prompt)");
 		process.exit(2);
 	}
 	if (body.trim().length === 0) {
 		error(`prompt "${name}" at ${path} is empty`);
-		hint("nothing to push; generate it first (e.g. ccqa run --update-agent-prompt)");
+		hint("nothing to push; generate it first (e.g. ccqa run --learn-hub-live-prompt)");
 		process.exit(2);
 	}
 	await connect(opts).putPrompt(project, name, body);
@@ -8749,7 +8705,7 @@ const promptRm = new Command("rm").description("Delete a prompt from the hub.").
 	info(`deleted prompt "${name}" from the hub`);
 }));
 const promptCommand = new Command("prompt").description("Manage prompt assets (per-flow user/agent guidance, triage user guidance, analysis custom prompt) stored on the hub (fetched automatically by `ccqa run` at run time).").addCommand(promptPush).addCommand(promptLs).addCommand(promptRm);
-const deployRecord = new Command("record").description("Tell the hub what a deploy shipped, so it can answer which specs need a re-run (`ccqa run --changed=last-run`). Run this from the deploy job, after the deploy succeeds. The changed paths are computed locally with a two-dot `git diff <previous> <sha>`; a job that has only curl and git can POST the same body directly (see docs/hub.md).").requiredOption("--profile <name>", "Environment this deploy landed in (e.g. 'stg'). Required: dev and stg sit at different commits, so the deploy log is per-profile.").requiredOption("--sha <sha>", "Commit that was deployed.").option("--previous <sha>", "Commit this deploy replaced. Defaults to the profile's current deploy-log head on the hub. With neither, there's nothing to diff against: changedPaths is unset and --select is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--select", "Also decide which specs this deploy reaches (`ccqa select-specs`) and send the verdict with it. Without it the deploy is a hole in the range: specs behind it report 'unknown' rather than 'not needed'.").option("-m, --model <name>", "Model for --select. Claude alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Project whose deploy log this entry joins. Defaults to the current directory's name.").option("--cwd <path>", "Directory the git diff and the default --project name are resolved against.").action(withHubErrors(async (opts) => {
+const deployRecord = new Command("record").description("Tell the hub what a deploy shipped, so it can answer which specs need a re-run (`ccqa run --only-hub-rerun-needed`). Run this from the deploy job, after the deploy succeeds. The changed paths are computed locally with a two-dot `git diff <previous> <sha>`; a job that has only curl and git can POST the same body directly (see docs/hub.md).").requiredOption("--profile <name>", "Environment this deploy landed in (e.g. 'stg'). Required: dev and stg sit at different commits, so the deploy log is per-profile.").requiredOption("--sha <sha>", "Commit that was deployed.").option("--previous <sha>", "Commit this deploy replaced. Defaults to the profile's current deploy-log head on the hub. With neither, there's nothing to diff against: changedPaths is unset and --select is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--select", "Also decide which specs this deploy reaches (`ccqa select-specs`) and send the verdict with it. Without it the deploy is a hole in the range: specs behind it report 'unknown' rather than 'not needed'.").option("-m, --model <name>", "Model for --select. Claude alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Project whose deploy log this entry joins. Defaults to the current directory's name.").option("--cwd <path>", "Directory the git diff and the default --project name are resolved against.").action(withHubErrors(async (opts) => {
 	const cwd = resolveCwd(opts.cwd);
 	const project = resolveProject(opts);
 	const hub = connect(opts);
@@ -8828,7 +8784,7 @@ function describeSelection(selection, diffAvailable) {
 	const values = Object.values(selection);
 	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 --changed=last-run`.").addCommand(deployRecord);
+const deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --only-hub-rerun-needed`.").addCommand(deployRecord);
 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");
@@ -8971,7 +8927,7 @@ function generateLiveSessionName() {
 * Project-specific guidance ("the admin tenant is foo.example", "session
 * times out at X minutes", …) is appended from
 * `.ccqa/prompts/live.user.md` (human-maintained) and
-* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --update-agent-prompt`)
+* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --learn-hub-live-prompt`)
 * by the caller, so ccqa stays clean of downstream-product context.
 *
 * Constraint posture: `ccqa record` (trace) enforces a strict selector
@@ -9726,7 +9682,7 @@ const verifiedSessions = /* @__PURE__ */ new Set();
 * each named session from the hub (`.ccqa/sessions/*.json` is no longer
 * read here). Every name must load as a valid agent-browser state (the spec
 * assumes it starts signed-in); a missing/malformed session fails with a
-* `ccqa session bootstrap` hint instead of running unauthenticated.
+* `ccqa hub session capture` hint instead of running unauthenticated.
 *
 * If a session carries an embedded verify URL (bootstrap saved it), the
 * restore is health-checked before the run starts, so an expired/unusable
@@ -9769,7 +9725,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 				if (!check.restored) return {
 					ok: false,
 					error: `session '${name}' did not restore to a signed-in page — ${check.reason}`,
-					hint: `re-bootstrap it: ccqa session bootstrap ${name}${profileFlag}`
+					hint: `re-bootstrap it: ccqa hub session capture ${name}${profileFlag}`
 				};
 				verifiedSessions.add(memoKey);
 			}
@@ -9779,7 +9735,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 	if (broken.length > 0) return {
 		ok: false,
 		error: `session not usable on the hub: ${broken.join(", ")}`,
-		hint: `create it with: ${broken.map((name) => `ccqa session bootstrap ${name}${profileFlag}`).join("  ·  ")}`
+		hint: `create it with: ${broken.map((name) => `ccqa hub session capture ${name}${profileFlag}`).join("  ·  ")}`
 	};
 	const statePath = await writeMergedTempState(mergeStorageStates(loaded));
 	return {
@@ -11652,7 +11608,7 @@ async function groupSpecsByTarget(specs, config, cwd, resolve = resolveTarget) {
 * then each external target group through its runner. Every row is upserted
 * into the incremental report the moment it exists — the runner reports each
 * spec through `onSpecComplete` as it finishes — so an interrupt keeps what
-* already ran and `--push-report` streams spec by spec. Rows are also
+* already ran and `--report-to-hub` streams spec by spec. Rows are also
 * returned for the tail phase (failure analysis) and the final batch write. A
 * crashing runner marks its own specs failed instead of aborting the run.
 */
@@ -11788,7 +11744,7 @@ function createIncrementalReport(reportDir, envelope, sink) {
 //#endregion
 //#region src/prompts/agent-update.ts
 /**
-* Build the prompts used by `--update-agent-prompt` to refresh
+* Build the prompts used by the `--learn-*-prompt` flags to refresh
 * `.ccqa/prompts/<kind>.agent.md` after a run:
 *   - `ccqa run` (live) → `live.agent`
 *   - `ccqa record` (trace) → `record.agent`
@@ -12044,10 +12000,7 @@ async function updateAgentPrompt(args) {
 		warn(`${flag} skipped (${auth.reason})`);
 		return;
 	}
-	if (!hubContext) {
-		warn(`${flag} skipped (hub connection required; pass --hub-url/--hub-token or set CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
-		return;
-	}
+	if (!hubContext) throw new Error(`${flag} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
 	const { hub, project } = hubContext;
 	const promptName = `${kind}.agent`;
 	try {
@@ -12169,6 +12122,19 @@ async function resolveVitestConfig(cwd) {
 function resolveReportDir(reportDir, cwd) {
 	return resolve(cwd, reportDir ?? "ccqa-report");
 }
+/**
+* Turn a hub transport failure into a usage error, as a `.catch` so the
+* tuple types of the `Promise.all` it guards survive.
+*
+* Without it the raw `fetch failed` escapes as an unhandled rejection: a stack
+* trace and exit 1, where the user needs "the hub is unreachable" and exit 2.
+* Errors the callers already shaped pass through — they say more than this
+* wrapper could.
+*/
+function asHubReadError(err) {
+	if (err instanceof RunUsageError) throw err;
+	throw new RunUsageError(`could not read from the hub: ${errMessage(err)}`);
+}
 /** De-dupe by `featureName/specName`, keeping first-seen order. */
 function dedupeSpecs(specs) {
 	const seen = /* @__PURE__ */ new Set();
@@ -12189,10 +12155,10 @@ function dedupeSpecs(specs) {
 * maps it to `process.exit(2)`).
 */
 async function executeRun(targets, opts) {
-	const filtering = Boolean(opts.onlyAffectedBy || opts.onlyStale || opts.onlyAuditedClean);
+	const filtering = Boolean(opts.onlyAffectedBy || opts.onlyHubRerunNeeded);
 	if (filtering && targets.length > 0) throw new RunUsageError("a --only-* filter and an explicit spec target cannot be combined");
-	const rerunProfile = opts.onlyStale === true ? requireRerunProfile(opts.profile) : null;
-	if (opts.onlyStaleWithUnknown && rerunProfile === null) warn("--only-stale-with-unknown is ignored: it only applies to --only-stale");
+	const rerunProfile = opts.onlyHubRerunNeeded === true ? requireRerunProfile(opts.hubProfile) : null;
+	if (opts.onlyHubRerunNeededWithUnknown && rerunProfile === null) warn("--only-hub-rerun-needed-with-unknown is ignored: it only applies to --only-hub-rerun-needed");
 	const forExecution = opts.dryRun !== true;
 	const cwd = opts.cwd ?? process.cwd();
 	const wantsLastGreen = opts.onFailExplain === true && opts.onFailExplainBase === void 0;
@@ -12217,8 +12183,8 @@ async function executeRun(targets, opts) {
 		meta("analysis-base", `${fixedBase.ref} (${fixedBase.sha.slice(0, 12)}, ${fixedBase.source})`);
 	}
 	if (forExecution) try {
-		if (opts.profile !== void 0) await resolveProfileEnv({
-			profile: opts.profile,
+		if (opts.hubProfile !== void 0) await resolveProfileEnv({
+			profile: opts.hubProfile,
 			project: resolveProjectOrThrow(opts.project, cwd),
 			cwd,
 			hubUrl: opts.hubUrl,
@@ -12234,7 +12200,7 @@ async function executeRun(targets, opts) {
 		if (err instanceof RunUsageError) throw err;
 		if (err instanceof ProjectNameError) throw new RunUsageError(err.message);
 		if (err instanceof HubConnectionError || err instanceof HubApiError) throw new RunUsageError(err.message);
-		throw new RunUsageError(`failed to load profile "${opts.profile}": ${errMessage(err)}`);
+		throw new RunUsageError(`failed to load profile "${opts.hubProfile}": ${errMessage(err)}`);
 	}
 	let hubCtx = null;
 	try {
@@ -12250,16 +12216,16 @@ 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-stale requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-	if (opts.onlyAuditedClean && hubCtx == null) throw new RunUsageError("--only-audited-clean requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead, auditedLedger] = await Promise.all([
+	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)");
+	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead] = await Promise.all([
 		forExecution ? fetchCustomPrompt(hubCtx) : null,
 		forExecution ? fetchTriageUserPrompt(hubCtx) : null,
-		forExecution && ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.profile, cwd) : null,
+		forExecution && ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.hubProfile, cwd) : null,
 		rerunProfile !== null && hubCtx ? fetchRerunReport(hubCtx, rerunProfile) : null,
-		forExecution && hubCtx && opts.profile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.profile) : null,
-		opts.onlyAuditedClean && hubCtx ? fetchAuditedLedger(hubCtx) : null
-	]);
+		forExecution && hubCtx && opts.hubProfile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.hubProfile) : null
+	]).catch(asHubReadError);
 	const deployedSha = rerunReport?.deployHead.sha ?? fetchedDeployHead;
 	if (ledgerEntries) diffProvider = createDiffProvider({
 		resolveBase: createLastGreenResolver(ledgerEntries, cwd),
@@ -12286,24 +12252,19 @@ async function executeRun(targets, opts) {
 		const before = specs.length;
 		let unanswerable = 0;
 		if (rerunReport) {
-			const selection = selectSpecsNeedingRerun(specs, rerunReport, { includeUnknown: opts.onlyStaleWithUnknown === true });
+			const selection = selectSpecsNeedingRerun(specs, rerunReport, { includeUnknown: opts.onlyHubRerunNeededWithUnknown === true });
 			specs = selection.selected;
 			unanswerable = selection.excludedUnanswerable;
 			meta("stale-base", `deploy ${rerunReport.deployHead.sha.slice(0, 12)} (profile ${rerunReport.profile})`);
 			meta("stale-states", selection.summary);
 		}
-		if (auditedLedger) {
-			const picked = selectAuditedClean(specs, auditedLedger);
-			specs = picked.selected;
-			meta("audit-states", `${picked.selected.length} clean, ${picked.drifted} drifted, ${picked.unaudited} never audited`);
-		}
 		if (opts.onlyAffectedBy) specs = (await collectChangedSpecs(specs, {
 			cwd,
 			base: opts.onlyAffectedBy,
 			...opts.model ? { model: opts.model } : {}
 		})).specs;
 		meta("selected", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
-		if (specs.length === 0 && unanswerable > 0) hint(`${unanswerable} spec(s) were excluded because the hub could not tell whether they need a re-run; pass --only-stale-with-unknown to run them anyway`);
+		if (specs.length === 0 && unanswerable > 0) hint(`${unanswerable} spec(s) were excluded because the hub could not tell whether they need a re-run; pass --only-hub-rerun-needed-with-unknown to run them anyway`);
 	}
 	if (specs.length === 0) {
 		warn("no specs to run");
@@ -12328,7 +12289,7 @@ async function executeRun(targets, opts) {
 		const why = "it only applies to agent-browser 'mode: live' specs, and this run has none";
 		if (typeof opts.liveStepRetry === "number" && opts.liveStepRetry > 0) warn(`--live-step-retry is ignored: ${why}`);
 		if (opts.liveArtifactsDir) warn(`--live-artifacts-dir is ignored: ${why}`);
-		if (opts.learnLivePrompt) warn(`--learn-live-prompt is ignored: ${why}`);
+		if (opts.learnHubLivePrompt) warn(`--learn-live-prompt is ignored: ${why}`);
 	} else if (opts.liveArtifactsDir && liveSpecs.length > 1) warn("--out is ignored when running multiple live specs");
 	if (detSpecs.length === 0 && opts.replaySkipEvidence === true) warn("--no-evidence is ignored: it only applies to agent-browser 'mode: deterministic' specs, and this run has none");
 	blank();
@@ -12343,7 +12304,6 @@ async function executeRun(targets, opts) {
 		};
 	}
 	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir);
-	if (opts.reportToHub && hubCtx == null) warn("--push-report requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN); skipping push");
 	let hubRunId = null;
 	let hubSink;
 	if (hubCtx != null && opts.reportToHub) try {
@@ -12353,7 +12313,7 @@ async function executeRun(targets, opts) {
 		const opened = await hubCtx.hub.openRun({
 			project: hubCtx.project,
 			...branch ? { branch } : {},
-			...opts.profile ? { profile: opts.profile } : {},
+			...opts.hubProfile ? { profile: opts.hubProfile } : {},
 			...git.head ? { gitHead: git.head } : {},
 			...deployedSha ? { deployedSha } : {},
 			...ciRunId ? { ciRunId } : {},
@@ -12375,7 +12335,7 @@ async function executeRun(targets, opts) {
 			}
 		} };
 	} catch (err) {
-		warn(`hub: could not open incremental run (${errMessage(err)}); continuing with local report only`);
+		throw new RunUsageError(`--report-to-hub: could not open a run on the hub (${errMessage(err)})`);
 	}
 	const incrementalReport = createIncrementalReport(reportDir, buildReportEnvelope({
 		git,
@@ -12414,7 +12374,7 @@ async function executeRun(targets, opts) {
 		reportDir,
 		...typeof opts.liveStepRetry === "number" ? { retry: opts.liveStepRetry } : {},
 		concurrency: opts.concurrency ?? 1,
-		...opts.profile ? { profile: opts.profile } : {},
+		...opts.hubProfile ? { profile: opts.hubProfile } : {},
 		diffProvider,
 		hubContext: hubCtx,
 		customPrompt,
@@ -12476,7 +12436,7 @@ async function executeRun(targets, opts) {
 			}
 		}
 	}
-	if (opts.learnLivePrompt && liveSpecs.length > 0) {
+	if (opts.learnHubLivePrompt && liveSpecs.length > 0) {
 		blank();
 		await updateAgentPrompt({
 			kind: "live",
@@ -12789,7 +12749,7 @@ const PATCH_FILES_RAW_BUDGET = 20 * 1024 * 1024;
 /**
 * Add one row's file assets to `acc` as `{ reportDir-relative posix path →
 * base64 }`. Every kind of screenshot a row can carry has to be collected here,
-* or `--push-report` — the way CI publishes — silently ships a report whose
+* or `--report-to-hub` — the way CI publishes — silently ships a report whose
 * images 404 on the hub: a live row's per-step PNGs
 * (`liveRun.steps[].beforePng/afterPng`), a script-driven row's step evidence
 * (`evidence[].pngPath` / `beforePngPath`, written by agent-browser replays and
@@ -13018,14 +12978,14 @@ function installTeardownSignalHandlers(teardown) {
 }
 //#endregion
 //#region src/cli/run.ts
-const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-stale", "Only specs whose last result no longer holds — each spec's own last run compared against the hub's deploy log. No git diff involved. Requires a hub connection and --profile.").option("--only-stale-with-unknown", "With --only-stale: also take specs whose re-run need the hub cannot answer ('unknown') and specs that never ran ('neverRun'). Off by default: an unanswerable question is reported, not guessed.").option("--only-audited-clean", "Only specs `ccqa audit` last found no drift in. A spec that has never been audited is not taken: this flag spends a run where a cheap audit already cleared the spec, and \"never looked\" is not that. Requires a hub connection.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
+const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `needed` for: their last result no longer covers what is deployed. Specs the audit rejected answer `blocked` and are never taken — a run cannot repair a spec. No git diff involved. Requires a hub connection and --hub-profile.").option("--only-hub-rerun-needed-with-unknown", "With --only-hub-rerun-needed: also take specs whose re-run need the hub cannot answer ('unknown') and specs that never ran ('neverRun'). Off by default: an unanswerable question is reported, not guessed.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
 	const n = Number(raw);
 	if (!Number.isFinite(n) || n < 0 || Math.floor(n) !== n) throw new Error(`--live-step-retry must be a non-negative integer, got "${raw}"`);
 	return n;
 }, 0).option("--live-artifacts-dir <dir>", "(live only) Override the per-spec artifact directory. Default: <specDir>/runs/<runId>. Ignored when running multiple specs.").option("--replay-skip-evidence", `(deterministic replay only) Skip step-boundary evidence capture (PNG + meta JSON written to ${DEFAULT_REPORT_DIR}/${EVIDENCE_SUBDIR}/ by default).`).optionsGroup("What to do about failures:").option("--on-fail-explain", "Classify each failure against the source diff since the commit where that spec last passed (per-spec baselines from the hub). Off by default — no Claude calls without it.").option("--on-fail-explain-base <ref>", "With --on-fail-explain: diff against <ref> instead of each spec's last green. Use when there is no hub to hold the baselines.").optionsGroup("What to do with the results:").option("--report-dir <dir>", `Directory for the structured run results (report.json + evidence PNGs), which are always written. Default: ${DEFAULT_REPORT_DIR}/.`).option("--report-format <fmt>", "Additional output format alongside HTML: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
 	if (REPORT_FORMATS.includes(raw)) return raw;
 	throw new Error(`--report-format must be one of ${REPORT_FORMATS.join(" | ")}`);
-}, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").optionsGroup("Learning:").option("--learn-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.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(async (targets, opts) => {
+}, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").optionsGroup("Learning:").option("--learn-hub-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.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(async (targets, opts) => {
 	await runCliAction(targets, opts);
 });
 /** Parse --concurrency: a positive integer. Rejects 0, negatives, non-integers. */
@@ -13041,11 +13001,7 @@ function parseConcurrency$1(raw) {
 function headerTarget(targets, opts) {
 	if (targets.length === 1) return targets[0];
 	if (targets.length > 1) return `${targets.length} targets`;
-	const filters = [
-		opts.onlyAffectedBy ? "affected" : null,
-		opts.onlyStale ? "stale" : null,
-		opts.onlyAuditedClean ? "audited clean" : null
-	].filter((s) => s !== null);
+	const filters = [opts.onlyAffectedBy ? "affected" : null, opts.onlyHubRerunNeeded ? "needs re-run" : null].filter((s) => s !== null);
 	return filters.length === 0 ? "(all specs)" : `(${filters.join(" + ")})`;
 }
 /**
@@ -15142,21 +15098,21 @@ async function runGenerateLocked(featureName, specName, opts, cwd) {
 	hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
 }
 /**
-* `ccqa generate --update-agent-prompt`: refresh the target's learned
+* `ccqa generate --learn-hub-codegen-prompt`: refresh the target's learned
 * `<target>.agent` playbook from this generation. Only targets that declare a
 * `guidanceKind` (the LLM-generating ones: playwright, runn) have such a
 * prompt — agent-browser's codegen is mechanical, so point at `ccqa record
-* --update-agent-prompt` for its tracer instead.
+* --learn-hub-trace-prompt` for its tracer instead.
 */
 async function runGenerateAgentPromptUpdate(target, featureName, specName, result, opts, cwd) {
 	if (target.guidanceKind === void 0) {
-		warn(`--update-agent-prompt has no effect on the "${target.id}" target — it has no learned generation prompt (only LLM-generating targets like playwright/runn do)`);
+		warn(`--learn-hub-codegen-prompt has no effect on the "${target.id}" target — it has no learned generation prompt (only LLM-generating targets like playwright/runn do)`);
 		return;
 	}
 	blank();
 	await updateAgentPrompt({
 		kind: target.guidanceKind,
-		flag: "--learn-codegen-prompt",
+		flag: "--learn-hub-codegen-prompt",
 		runSummary: buildGenerateRunSummary(target.id, featureName, specName, result, cwd),
 		hubContext: opts.hubContext ?? null,
 		...opts.model ? { model: opts.model } : {},
@@ -15182,7 +15138,7 @@ async function confirmOverwrite(path) {
 		rl.close();
 	}
 }
-const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").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("--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 previously generated test code without warning").optionsGroup("Learning:").option("--learn-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; 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) => {
+const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").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("--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 previously generated test code without warning").optionsGroup("Learning:").option("--learn-hub-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; 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) => {
 	const { featureName, specName } = parseSpecPath(specPath);
 	const language = opts.language ?? "auto";
 	const cwd = resolveCwd(opts.cwd);
@@ -15191,9 +15147,9 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 		hubToken: opts.hubToken,
 		hubHeader: opts.hubHeader
 	});
-	const project = opts.profile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
+	const project = opts.hubProfile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
+	if (opts.hubProfile !== void 0) await applyProfileFromOption({
+		profile: opts.hubProfile,
 		project,
 		cwd,
 		hubUrl: opts.hubUrl,
@@ -15205,6 +15161,10 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 		project: "",
 		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)");
+		process.exit(2);
+	}
 	const hubContext = hubClient && project ? {
 		hub: hubClient,
 		project
@@ -15220,7 +15180,7 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 			targetOverride: opts.target,
 			cwd,
 			hubContext,
-			updateAgentPrompt: opts.learnCodegenPrompt ?? false
+			updateAgentPrompt: opts.learnHubCodegenPrompt ?? false
 		});
 	} catch (e) {
 		if (e instanceof SpecLockedError) {
@@ -15259,7 +15219,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-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").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 withCostTally(async () => {
 		try {
 			await runRecord(specPath, opts);
@@ -15279,9 +15239,9 @@ async function runRecord(specPath, opts) {
 		error(`target "${target.id}" does not use a browser recording — run 'ccqa generate ${featureName}/${specName}' instead`);
 		process.exit(2);
 	}
-	const project = opts.profile !== void 0 ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
+	const project = opts.hubProfile !== void 0 ? resolveProject(opts) : void 0;
+	if (opts.hubProfile !== void 0) await applyProfileFromOption({
+		profile: opts.hubProfile,
 		project,
 		cwd: cwdForProfile,
 		hubUrl: opts.hubUrl,
@@ -15303,6 +15263,10 @@ async function runRecord(specPath, opts) {
 		hub: hubClientForTrace,
 		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)");
+		process.exit(2);
+	}
 	const releaseLock = await acquireSpecLock(featureName, specName, "record", cwdForProfile).catch((e) => {
 		if (e instanceof SpecLockedError) {
 			error(e.message);
@@ -15330,11 +15294,11 @@ async function runRecord(specPath, opts) {
 	} finally {
 		await releaseLock();
 	}
-	if (opts.learnTracePrompt && traceResult !== null) {
+	if (opts.learnHubTracePrompt && traceResult !== null) {
 		blank();
 		await updateAgentPrompt({
 			kind: "record",
-			flag: "--learn-trace-prompt",
+			flag: "--learn-hub-trace-prompt",
 			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
 			hubContext,
 			...opts.model ? { model: opts.model } : {},
@@ -15615,7 +15579,7 @@ function specStatus(result, threshold) {
 	return "passed";
 }
 /**
-* Adapts `ccqa drift` results into the shared RunReportData shape so they can
+* Adapts `ccqa audit` results into the shared RunReportData shape so they can
 * be pushed to the hub (`ccqa audit --report-to-hub`) and rendered by the same report
 * UI as `ccqa run`/`ccqa live`. Browser-execution fields (testCounts,
 * evidence, liveRun, ...) don't apply to a drift audit and are always null —
@@ -15664,7 +15628,7 @@ function driftResultsToReport(results, meta) {
 //#endregion
 //#region src/cli/audit.ts
 const DEFAULT_CONCURRENCY = 3;
-const auditCommand = addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Costs one model call; specs it cannot decide are audited rather than skipped.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger `ccqa run --only-audited-clean` reads.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(withUsageErrors(async (specPath, opts) => {
+const auditCommand = addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Costs one model call; specs it cannot decide are audited rather than skipped.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger. A spec it finds drifted answers `blocked` to `ccqa run --only-hub-rerun-needed`, and is not run until the drift clears.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(withUsageErrors(async (specPath, opts) => {
 	await withCostTally(() => runAudit(specPath, opts));
 }));
 async function runAudit(specPath, opts) {
@@ -15723,9 +15687,9 @@ async function runAudit(specPath, opts) {
 }
 /**
 * Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
-* shows up alongside `ccqa run` runs in the hub UI. Best-effort: a missing
-* hub connection warns and returns rather than failing the command (`--report-to-hub`
-* never changes drift's own exit code).
+* shows up alongside `ccqa run` runs in the hub UI. A missing hub connection
+* is a usage error, not a silent skip — a CI job that asked to publish and
+* did not must say so.
 *
 * `resolveHub` is injectable so tests can supply a fake `HubClient` without
 * a real hub connection; it defaults to the real flag/env resolution.
@@ -15734,8 +15698,8 @@ async function pushDriftResults(args, resolveHub = resolveHubClient) {
 	const { results, threshold, cwd, opts, format, baseRef } = args;
 	const hub = resolveHub(opts);
 	if (!hub) {
-		warn("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN) — skipping push");
-		return;
+		error("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
 	}
 	try {
 		const project = resolveProject({
@@ -15812,7 +15776,7 @@ function parseFormat$1(raw) {
 function parseSeverity(raw) {
 	const v = raw ?? "error";
 	if (v === "warn" || v === "error") return v;
-	error(`invalid --severity: ${v} (expected warn|error)`);
+	error(`invalid --exit-on: ${v} (expected warn|error)`);
 	process.exit(2);
 }
 function parseConcurrency(raw) {
@@ -16282,7 +16246,7 @@ function countSpecs(results) {
 * or `red` (the last outcome), which are orthogonal axes.
 *
 * Best-effort — a ledger failure must not fail the push; the ledger is an
-* accelerator for `--failure-analysis=last-green` and re-run selection, not
+* accelerator for `--on-fail-explain` baselines and re-run selection, not
 * part of the run record. Runs without a branch or gitHead can't be placed in
 * the ledger and are skipped.
 *
@@ -16926,7 +16890,7 @@ function createGetLastGreenHandler(storage) {
 /**
 * GET /api/v1/projects/:project/drift
 *
-* Every spec's last `ccqa drift --push` audit, keyed by "feature/spec". No
+* Every spec's last `ccqa audit --report-to-hub` result, keyed by "feature/spec". No
 * `?profile=` — drift asks whether a spec still describes the code, which
 * has nothing to do with which environment is running it, unlike the
 * `/rerun` and `/last-green` endpoints. Merged across every branch (newest
@@ -17110,7 +17074,7 @@ async function loadSpecTargets(perspectives, project) {
 //#endregion
 //#region src/hub/core/rerun.ts
 function computeRerun(input) {
-	const { specs, ledger, log, touchIndex } = input;
+	const { specs, ledger, log, touchIndex, drift } = input;
 	const notEvaluated = log.entries.length === 0 && Object.keys(ledger.run).length === 0 && Object.keys(ledger.green).length === 0;
 	const positionBySha = /* @__PURE__ */ new Map();
 	log.entries.forEach((entry, i) => {
@@ -17135,7 +17099,12 @@ function computeRerun(input) {
 			lastGreen: ledger.green[spec.key] ?? null,
 			lastRed: ledger.red[spec.key] ?? null
 		};
-		out[spec.key] = notEvaluated ? {
+		const blocked = blockedBy(drift, spec.key);
+		out[spec.key] = blocked ? {
+			state: "blocked",
+			blockedReason: blocked,
+			...coords
+		} : notEvaluated ? {
 			state: "notEvaluated",
 			...coords
 		} : {
@@ -17145,6 +17114,21 @@ function computeRerun(input) {
 	}
 	return out;
 }
+/**
+* Why the audit rejects this spec, or null when it does not.
+*
+* Only a finding blocks. A spec with no ledger entry was never audited, and a
+* `UNKNOWN` entry is the audit saying it could not tell — neither is a reason
+* to withhold a run, and treating them as one would stop every newly written
+* spec from ever executing.
+*/
+function blockedBy(drift, key) {
+	switch (drift.specs[key]?.label) {
+		case "TEST_DRIFT": return "testDrift";
+		case "SPEC_CHANGE": return "specChange";
+		default: return null;
+	}
+}
 function verdict(spec, lastRun, log, positionBySha, touchIndex, range) {
 	if (!lastRun) return { state: "neverRun" };
 	if (log.entries.length === 0) return unknown("noDeployLog");
@@ -17187,21 +17171,23 @@ function unknown(reason) {
 /**
 * GET /api/v1/projects/:project/rerun?profile=
 *
-* Per spec: is its last result still trustworthy? Set arithmetic over the spec
+* Per spec: is it worth running, and if not, why? Set arithmetic over the spec
 * ledger, the profile's deploy log and each deploy's per-spec touch verdicts
-* recorded by `ccqa select-specs` (ADR-0010, ADR-0011). The ledger is read
-* across every branch: a run exercises the deployed environment whatever
-* branch its code came from.
+* recorded by `ccqa select-specs` (ADR-0010, ADR-0011), plus the drift ledger —
+* a spec the audit rejected answers `blocked`, because re-running it cannot
+* clear what is wrong with it. The spec ledger is read across every branch: a
+* run exercises the deployed environment whatever branch its code came from.
 */
 function createGetRerunHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const [specs, ledger, log, touchIndex] = await Promise.all([
+		const [specs, ledger, log, touchIndex, drift] = await Promise.all([
 			loadSpecTargets(storage.perspectives, project),
 			storage.ledger.getMerged(project, profile),
 			storage.deploys.getLog(project, profile),
-			storage.deploys.getTouchIndex(project, profile)
+			storage.deploys.getTouchIndex(project, profile),
+			storage.driftLedger.getMerged(project)
 		]);
 		if (specs === null) throw new HttpError(404, "no_perspectives", `no perspectives stored for project "${project}" — push one with \`ccqa perspectives\` before asking which specs need a re-run`);
 		const head = log.entries[log.entries.length - 1];
@@ -17217,7 +17203,8 @@ function createGetRerunHandler(storage) {
 				specs,
 				ledger,
 				log,
-				touchIndex
+				touchIndex,
+				drift
 			})
 		});
 	};
@@ -18028,7 +18015,7 @@ const HTML_BODY = `
           <div style="font-weight:600" data-i18n="session.help.title">How to get this JSON</div>
           <ol class="help-steps">
             <li><span class="step-n">1</span><div class="step-b"><span data-i18n="session.help.step1">Run this in your terminal and log in by hand when the browser opens:</span>
-              <div class="cmd"><code id="session-help-cmd">ccqa session bootstrap &lt;name&gt;</code><button type="button" class="copy" id="session-help-copy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><span data-i18n="common.copy">Copy</span></button></div>
+              <div class="cmd"><code id="session-help-cmd">ccqa hub session capture &lt;name&gt;</code><button type="button" class="copy" id="session-help-copy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><span data-i18n="common.copy">Copy</span></button></div>
             </div></li>
             <li><span class="step-n">2</span><div class="step-b"><span data-i18n="session.help.step2">Open the saved file and paste its contents below:</span>
               <div style="margin-top:5px"><span class="path">.ccqa/sessions/&lt;profile&gt;/&lt;name&gt;.json</span></div>
@@ -18580,6 +18567,7 @@ const CSS = `
      eats the next rule, and a backtick ends the template literal this CSS
      lives in. */
   .sg-drift-found, .sg-needed { background: var(--amber-fill); }
+  .sg-blocked { background: var(--fail); }
   .sg-unknown, .sg-drift-unknown { background: var(--info); }
   .sg-drift-clean, .sg-notneeded { background: var(--pass); }
   .sg-drift-none, .sg-neverrun { background: var(--muted-2); }
@@ -18788,6 +18776,7 @@ const CLIENT_JS = `
       "perspectives.result.ci": "CI",
       "perspectives.rerun.state.needed": "Re-run needed",
       "perspectives.rerun.state.notNeeded": "Not needed",
+      "perspectives.rerun.state.blocked": "Blocked by the audit",
       "perspectives.rerun.state.unknown": "Can't tell",
       "perspectives.rerun.state.neverRun": "Never run",
       "perspectives.rerun.state.notEvaluated": "Not evaluated",
@@ -18800,6 +18789,8 @@ const CLIENT_JS = `
       "perspectives.rerun.touchedUnknown": "a deploy since the last run matched this case",
       "perspectives.rerun.neverRunHint": "no result recorded for this profile yet",
       "perspectives.rerun.notEvaluatedHint": "no run and no deploy has ever been recorded for this profile",
+      "perspectives.rerun.blocked.testDrift": "the generated test no longer matches the code — re-record it",
+      "perspectives.rerun.blocked.specChange": "the spec describes something the code no longer does — a human decides",
       "perspectives.rerun.why.noSelectionInRange": "a deploy in range was recorded without a spec selection",
       "perspectives.rerun.why.selectionUnknown": "the selector could not tell whether this case was affected",
       "perspectives.rerun.why.noDeployLog": "no deploy log for this profile",
@@ -18937,6 +18928,7 @@ const CLIENT_JS = `
       "perspectives.result.ci": "CI",
       "perspectives.rerun.state.needed": "要再実行",
       "perspectives.rerun.state.notNeeded": "不要",
+      "perspectives.rerun.state.blocked": "監査で保留",
       "perspectives.rerun.state.unknown": "判定できない",
       "perspectives.rerun.state.neverRun": "未実行",
       "perspectives.rerun.state.notEvaluated": "未評価",
@@ -18949,6 +18941,8 @@ const CLIENT_JS = `
       "perspectives.rerun.touchedUnknown": "前回実行以降のデプロイがこのケースに一致する変更を行っています",
       "perspectives.rerun.neverRunHint": "このプロファイルでの実行記録がまだありません",
       "perspectives.rerun.notEvaluatedHint": "このプロファイルには実行もデプロイも記録がありません",
+      "perspectives.rerun.blocked.testDrift": "生成されたテストが古くなっています。録り直してください",
+      "perspectives.rerun.blocked.specChange": "spec がコードのやめた動作を書いています。人が判断します",
       "perspectives.rerun.why.noSelectionInRange": "対象範囲に判定を伴わないデプロイがあります",
       "perspectives.rerun.why.selectionUnknown": "影響の有無を判定できませんでした",
       "perspectives.rerun.why.noDeployLog": "このプロファイルのデプロイ記録がありません",
@@ -20154,7 +20148,7 @@ const CLIENT_JS = `
     }
 
     // A drift-kind row's diagnosis lives in analysis regardless of status
-    // (an UNKNOWN-labelled finding below the --severity threshold still
+    // (an UNKNOWN-labelled finding below the --exit-on threshold still
     // "passes" but has something to show); a normal run only ever classifies
     // a failed spec.
     var hasAnalysis = isDrift ? !!r.analysis : r.status === "failed" && r.analysis;
@@ -20989,6 +20983,7 @@ const CLIENT_JS = `
       if (!head) return t("perspectives.rerun.noDeployHead");
       return t("perspectives.rerun.vsDeploy") + " " + shortSha(head.sha) + " · " + relTime(head.at);
     }
+    if (rr.state === "blocked") return rerunReasonText("perspectives.rerun.blocked.", rr.blockedReason || "");
     if (rr.state === "unknown") return rerunReasonText("perspectives.rerun.why.", rr.reason || "");
     return rerunCannotJudge(rr);
   }
@@ -21001,12 +20996,13 @@ const CLIENT_JS = `
   // browser to click through.
 
   // Bar segments in drawing order: what to act on first, then what needs no
-  // action, then what was never measured. "unknown" keeps its own place and
-  // its own colour — folding it into "notNeeded" would turn "we cannot say"
-  // into "all clear", which is the one thing ADR-0010 forbids.
-  var RERUN_ORDER = ["needed", "unknown", "notNeeded", "neverRun", "notEvaluated"];
+  // action, then what was never measured. "blocked" leads because it is the
+  // only state a run cannot clear — someone has to repair the spec. "unknown"
+  // keeps its own place and its own colour: folding it into "notNeeded" would
+  // turn "we cannot say" into "all clear", which is what ADR-0010 forbids.
+  var RERUN_ORDER = ["blocked", "needed", "unknown", "notNeeded", "neverRun", "notEvaluated"];
   var RERUN_SEG_CLASS = {
-    needed: "sg-needed", unknown: "sg-unknown", notNeeded: "sg-notneeded",
+    blocked: "sg-blocked", needed: "sg-needed", unknown: "sg-unknown", notNeeded: "sg-notneeded",
     neverRun: "sg-neverrun", notEvaluated: "sg-noteval"
   };
 
@@ -21016,7 +21012,7 @@ const CLIENT_JS = `
   // state this UI does not know reads as unknown for the same reason: an
   // answer we cannot interpret is not evidence that nothing is needed.
   function rerunComposition(verdicts) {
-    var counts = { needed: 0, unknown: 0, notNeeded: 0, neverRun: 0, notEvaluated: 0 };
+    var counts = { blocked: 0, needed: 0, unknown: 0, notNeeded: 0, neverRun: 0, notEvaluated: 0 };
     verdicts.forEach(function (rr) {
       if (!rr || !rr.state) { counts.notEvaluated += 1; return; }
       var known = Object.prototype.hasOwnProperty.call(counts, rr.state);
@@ -21147,7 +21143,7 @@ const CLIENT_JS = `
   //
   // "unknown" keeps its own state rather than folding into the last result:
   // it means the hub cannot say whether that result still holds, and
-  // --changed=last-run does not re-run it without --include-unknown. Showing
+  // --only-hub-rerun-needed does not re-run it without --only-hub-rerun-needed-with-unknown. Showing
   // it as passed or failed would claim a confidence nothing supports.
   function perspRunState(rr) {
     if (!rr) return null;