ccqa 1.26.2 → 1.27.0

package/dist/bin/ccqa.mjs

@@ -3356,6 +3356,15 @@ const LiveReportRunSchema = z.object({
 	steps: z.array(LiveReportStepSchema),
 	cost: ReportCostSchema
 });
+/**
+* What a second attempt at a failed spec showed (`--on-fail-explain-rerun`).
+* "passed" means the failure did not reproduce, which is the evidence a single
+* run cannot hold; "failed" means it did.
+*
+* The row's `status` never moves with it. The spec failed, and a passing second
+* attempt explains that failure rather than undoing it.
+*/
+const ReportRerunSchema = z.object({ outcome: z.enum(["passed", "failed"]) });
 const ReportSpecResultSchema = z.object({
 	feature: z.string(),
 	spec: z.string(),
@@ -3377,6 +3386,7 @@ const ReportSpecResultSchema = z.object({
 	assertions: z.array(ReportAssertionSchema).nullable(),
 	analysis: FailureAnalysisSchema.nullable(),
 	analysisSkipped: z.string().nullable(),
+	rerun: ReportRerunSchema.optional(),
 	customPromptVersion: z.string().optional(),
 	analysisBase: z.object({
 		ref: z.string(),
@@ -4819,30 +4829,31 @@ async function readCostFileTotal(path) {
 //#endregion
 //#region src/cli/draft.ts
 const CATEGORY_LABEL = DRAFT_CATEGORY_LABEL;
-const draftCommand = addLanguageOption(new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a spec.yaml with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("-y, --yes", "Apply each generated patch without asking [y/N]", false)).action(withUsageErrors(async (specPath, opts) => {
+const draftCommand = addLanguageOption(new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a spec.yaml with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("-y, --yes", "Apply each generated patch without asking [y/N]", false).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.")).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("draft", () => runDraftCli(specPath, opts));
 }));
 async function runDraftCli(specPath, opts) {
-	await ensureCcqaDir();
+	const cwd = resolveCwd(opts.cwd);
+	await ensureCcqaDir(cwd);
 	let featureName;
 	let specName;
 	let prefilledIntent = null;
 	if (specPath) ({featureName, specName} = parseSpecPath(specPath));
 	else {
-		const { naming, intent } = await proposeNaming(opts);
+		const { naming, intent } = await proposeNaming(opts, cwd);
 		featureName = naming.featureName;
 		specName = naming.specName;
 		prefilledIntent = intent;
 	}
-	await runDraft(featureName, specName, opts, prefilledIntent);
+	await runDraft(featureName, specName, opts, cwd, prefilledIntent);
 }
-async function runDraft(featureName, specName, opts, prefilledIntent) {
+async function runDraft(featureName, specName, opts, cwd, prefilledIntent) {
 	header("draft", `${featureName}/${specName}`);
 	const ja = useJapanesePrompts(opts.language);
 	const oneShot = opts.instruction !== void 0;
 	let useIntentOnce = prefilledIntent !== null && !oneShot;
 	while (true) {
-		const existing = await tryReadSpecFile(featureName, specName);
+		const existing = await tryReadSpecFile(featureName, specName, cwd);
 		const isFirstRun = existing === null;
 		let userInput;
 		if (oneShot) userInput = opts.instruction ?? "";
@@ -4860,7 +4871,9 @@ async function runDraft(featureName, specName, opts, prefilledIntent) {
 			existing,
 			userInput: userInput.trim(),
 			autoApply: opts.yes === true,
-			language: opts.language
+			language: opts.language,
+			model: opts.model,
+			cwd
 		});
 		if (oneShot) process.exit(turnResult.hasError && !turnResult.applied ? 1 : 0);
 		blank();
@@ -4872,9 +4885,9 @@ async function runDraft(featureName, specName, opts, prefilledIntent) {
 	}
 }
 async function runOneTurn(input) {
-	const { featureName, specName, existing, userInput, autoApply, language } = input;
+	const { featureName, specName, existing, userInput, autoApply, language, model, cwd } = input;
 	const isFirstRun = existing === null;
-	const systemPrompt = buildDraftSystemPrompt(await loadAvailableBlocks()) + languageDirective(language);
+	const systemPrompt = buildDraftSystemPrompt(await loadAvailableBlocks(cwd)) + languageDirective(language);
 	const userPrompt = buildDraftPrompt({
 		mode: isFirstRun ? "create" : "refine",
 		existing: existing ?? "",
@@ -4891,7 +4904,9 @@ async function runOneTurn(input) {
 			"Grep",
 			"Glob"
 		],
-		silenceBashLog: true
+		silenceBashLog: true,
+		...model ? { model } : {},
+		cwd
 	}, (msg) => {
 		if (msg.type !== "assistant") return;
 		for (const block of msg.message.content ?? []) if (block.type === "tool_use") toolCounts[block.name] = (toolCounts[block.name] ?? 0) + 1;
@@ -4953,7 +4968,7 @@ async function runOneTurn(input) {
 			applied: false
 		};
 	}
-	meta("saved", await saveSpecFile(featureName, specName, report.patch));
+	meta("saved", await saveSpecFile(featureName, specName, report.patch, cwd));
 	return {
 		hasError,
 		applied: true
@@ -5028,7 +5043,7 @@ function writeFinding(issue) {
 	process.stdout.write(`      ${issue.message}\n`);
 	if (issue.detail) process.stdout.write(`      └ ${issue.detail.replace(/\n/g, "\n        ")}\n`);
 }
-async function proposeNaming(opts) {
+async function proposeNaming(opts, cwd) {
 	const ja = useJapanesePrompts(opts.language);
 	const oneShot = opts.instruction !== void 0;
 	const intent = oneShot ? opts.instruction ?? "" : await prompt(ja ? "何をテストしたいですか? > " : "What do you want to test? > ");
@@ -5036,7 +5051,7 @@ async function proposeNaming(opts) {
 		error("intent required to propose a feature/spec name");
 		process.exit(1);
 	}
-	const tree = await listFeatureTree();
+	const tree = await listFeatureTree(cwd);
 	const treeForPrompt = tree.map((f) => ({
 		featureName: f.featureName,
 		specs: f.specs.map((s) => ({ specName: s.specName }))
@@ -5050,7 +5065,9 @@ async function proposeNaming(opts) {
 			"Read",
 			"Grep",
 			"Glob"
-		]
+		],
+		...opts.model ? { model: opts.model } : {},
+		cwd
 	}, () => {});
 	if (isError) {
 		error("Claude failed during naming");
@@ -6346,6 +6363,131 @@ async function readGeneratedTestSources(ref, cwd) {
 	}
 	return parts.join("\n\n");
 }
+//#endregion
+//#region src/run/explain-rerun.ts
+/**
+* `ccqa run --on-fail-explain-rerun`: run a failed spec a second time and let
+* the result settle what one run cannot.
+*
+* `ENVIRONMENT` is the only cause with no artifact to read — a service that is
+* down, an expired credential, a timing race. When the log names it the
+* classifier can call it, and when it does not the honest answer is `UNKNOWN`
+* (ADR-0016). The evidence that would settle either is whether a second
+* attempt at the same commit passes, and this phase is what collects it.
+*
+* It runs after the classification, on the rows it produced, because `auto`
+* keys off the label. The second attempt is discarded except for its verdict:
+* it is not a row of this run, it is why one of the rows is red.
+*/
+const EXPLAIN_RERUN_MODES = [
+	"auto",
+	"always",
+	"never"
+];
+/**
+* The labels a second attempt can settle. `UNKNOWN` is the refusal the feature
+* exists to turn into an answer; `ENVIRONMENT` is rerun to confirm, since a
+* failure that reproduces is not the timing race that reading alone cannot
+* rule out.
+*/
+const RERUNNABLE_LABELS = ["UNKNOWN", "ENVIRONMENT"];
+/** Evidence sentences the rerun writes onto the row, in the classifier's own currency. */
+const DID_NOT_REPRODUCE = "a second attempt at the same commit passed: the failure is not reproducible";
+const REPRODUCED = "a second attempt at the same commit failed too: the failure is reproducible";
+/**
+* Confidence for a label the rerun settled. High, because the observation is
+* direct rather than read out of a diff — but short of certainty, since "did
+* not reproduce" is still an inference about the first attempt.
+*/
+const RERUN_SETTLED_CONFIDENCE = .95;
+/** Whether this row is one `mode` asks for a second attempt at. */
+function wantsRerun(row, mode) {
+	if (mode === "never" || row.status !== "failed" || row.analysis === null) return false;
+	return mode === "always" || RERUNNABLE_LABELS.includes(row.analysis.label);
+}
+/**
+* Rerun the failures `mode` selects and fold each verdict into its row.
+* Returns every row in the order given; the ones not rerun pass through
+* untouched.
+*
+* A rerun that throws leaves its row as the classifier left it, named in a
+* warning: a second attempt that never ran has established nothing, and
+* pretending otherwise is the one thing this phase must not do.
+*/
+async function rerunExplainedFailures(rows, opts) {
+	const eligible = rows.filter((row) => wantsRerun(row, opts.mode));
+	if (eligible.length === 0) return [...rows];
+	const budget = opts.maxSpecs ?? eligible.length;
+	const skipped = eligible.slice(budget);
+	emitRaw(`\n${C$1.cyan}${C$1.bold}──────── failure rerun ────────${C$1.reset}\n\n`);
+	const applied = /* @__PURE__ */ new Map();
+	for (const row of eligible.slice(0, budget)) {
+		const key = `${row.feature}/${row.spec}`;
+		info(`rerun: ${key}`);
+		let outcome;
+		try {
+			outcome = await opts.execute({
+				featureName: row.feature,
+				specName: row.spec
+			});
+		} catch (err) {
+			warn(`rerun failed to execute ${key} (${errMessage(err)}); its label stands as first classified`);
+			continue;
+		}
+		const next = applyRerun(row, outcome);
+		applied.set(key, next);
+		printRerun(key, outcome, next);
+	}
+	if (skipped.length > 0) warn(`--on-fail-explain-rerun-max-specs ${budget} reached: not rerun, so their labels stand as first classified — ` + skipped.map((row) => `${row.feature}/${row.spec}`).join(", "));
+	return rows.map((row) => applied.get(`${row.feature}/${row.spec}`) ?? row);
+}
+/**
+* Fold one verdict into its row. The row stays failed either way — the spec
+* failed, and what the rerun changes is why.
+*
+* A failure that did not reproduce is environmental, so the label says so.
+* One that did reproduce names no artifact it did not name before, so the
+* label stands: ADR-0016 asks a label to be earned, and "not a flake" earns
+* none of the three that point at something in the repository. What was
+* learned lands in the evidence instead, where a human triaging the row reads
+* it.
+*/
+function applyRerun(row, outcome) {
+	const analysis = row.analysis;
+	if (analysis === null) return {
+		...row,
+		rerun: { outcome }
+	};
+	const evidence = [...analysis.evidence, { detail: outcome === "passed" ? DID_NOT_REPRODUCE : REPRODUCED }];
+	if (outcome === "failed" || !RERUNNABLE_LABELS.includes(analysis.label)) return {
+		...row,
+		analysis: {
+			...analysis,
+			evidence
+		},
+		rerun: { outcome }
+	};
+	return {
+		...row,
+		analysis: {
+			...analysis,
+			label: "ENVIRONMENT",
+			confidence: RERUN_SETTLED_CONFIDENCE,
+			headline: "the failure did not reproduce on a second attempt",
+			recommendation: "treat the first attempt as environmental (a transient service, credential, seed-data or timing problem); nothing in the repository is implicated.",
+			reasoning: `${analysis.reasoning}\n\n${DID_NOT_REPRODUCE}`.trim(),
+			evidence
+		},
+		rerun: { outcome }
+	};
+}
+/** One rerun spec's line in the rerun block: what happened, and where it left the label. */
+function printRerun(key, outcome, row) {
+	const icon = outcome === "passed" ? `${C$1.green}✔${C$1.reset}` : `${C$1.red}✖${C$1.reset}`;
+	const what = outcome === "passed" ? "did not reproduce" : "reproduced";
+	const label = row.analysis?.label;
+	emitRaw(`${icon} ${C$1.bold}${key}${C$1.reset} → ${what}${label ? ` ${C$1.dim}(${label})${C$1.reset}` : ""}\n`);
+}
 /**
 * Capture the PR diff used as context for failure analysis. `--relative`
 * re-roots paths to `cwd` and drops changes outside it, so a monorepo
@@ -9184,6 +9326,93 @@ function isStorageStateShape(state) {
 	return typeof state === "object" && state !== null && Array.isArray(state.cookies) && Array.isArray(state.origins);
 }
 //#endregion
+//#region src/runtime/env-scrub.ts
+/**
+* Build a list of `[envValue, "${VAR}"]` pairs for every `${VAR}` reference
+* mentioned in the spec OR in any of its expanded (block-inlined) steps.
+* Used at trace time to scrub recorded Claude-text outputs so a value the
+* spec author intentionally threaded through `process.env` is preserved as
+* `${VAR}` in `ir.json` rather than baked in as the concrete
+* trace-time value.
+*
+* Why we walk `spec.steps` AND `expanded`:
+*   - `spec.steps` carries the spec's own `instruction` / `expected` + each
+*     include's raw `params` (which may themselves be `${ENV}` refs).
+*   - `expanded` carries the inlined block-internal steps, whose
+*     `instruction` / `expected` may *also* contain `${ENV}` refs that
+*     don't go through include params.
+*
+* Only refs whose env value is currently non-empty land in the map —
+* scrubbing against an empty string would corrupt unrelated empty strings
+* in the action stream. Names whose env is unset are returned via
+* `unresolved` so the caller can warn the user.
+*
+* Longer values sort first so a `${SHORT}` whose value is a substring of a
+* `${LONG}` value doesn't clobber the longer one.
+*
+* `title` is deliberately NOT scanned — it never reaches the recorded action
+* stream.
+*/
+function buildSpecEnvScrub(spec, expanded) {
+	const refNames = /* @__PURE__ */ new Set();
+	for (const step of spec.steps) if (isIncludeStep(step)) for (const v of Object.values(step.params ?? {})) collect(v, refNames);
+	else {
+		collect(step.instruction, refNames);
+		collect(step.expected, refNames);
+	}
+	for (const step of expanded) {
+		collect(step.instruction, refNames);
+		collect(step.expected, refNames);
+	}
+	const map = [];
+	const unresolved = [];
+	for (const name of refNames) {
+		const value = process.env[name];
+		if (typeof value === "string" && value.length > 0) map.push([value, "${" + name + "}"]);
+		else unresolved.push(name);
+	}
+	map.sort((a, b) => b[0].length - a[0].length);
+	return {
+		map,
+		unresolved
+	};
+}
+function collect(value, into) {
+	for (const name of iterEnvRefNames(value)) into.add(name);
+}
+/** Shorter than this, a value is no secret and matches inside ordinary words. */
+const MIN_PROSE_SCRUB_LENGTH = 4;
+/** Long enough to clear the length bar, still ordinary prose / JSON. */
+const COMMON_PROSE_VALUES = new Set([
+	"true",
+	"false",
+	"null",
+	"none",
+	"undefined"
+]);
+/**
+* Scrub map for a live run, built like {@link buildSpecEnvScrub} but without
+* the values that read as ordinary text (`"1"`, `"true"`). A live step records
+* paragraphs of model prose, so replacing every occurrence of such a value
+* would cost more meaning than it protects; record scrubs single command
+* lines, where the same trade favours keeping them.
+*/
+function buildLiveEnvScrubMap(spec, expanded) {
+	return buildSpecEnvScrub(spec, expanded).map.filter(([value]) => value.length >= MIN_PROSE_SCRUB_LENGTH && !COMMON_PROSE_VALUES.has(value.toLowerCase()));
+}
+/**
+* Replace every occurrence of an env value with its `${VAR}` placeholder in
+* `text`. **Caller invariant**: the map must be sorted longest-value-first
+* so a shorter value doesn't shadow a longer one that contains it as a
+* substring. `buildSpecEnvScrub` upholds this; hand-built maps should too.
+*/
+function scrubEnvValues(text, scrubMap) {
+	if (scrubMap.length === 0) return text;
+	let out = text;
+	for (const [value, placeholder] of scrubMap) if (out.includes(value)) out = out.replaceAll(value, placeholder);
+	return out;
+}
+//#endregion
 //#region src/claude/agent-browser-invoke.ts
 function agentBrowserInvokeBase(input) {
 	return {
@@ -9446,7 +9675,7 @@ async function runLiveExecutor(input) {
 			info(`  retry ${attempt}/${retries} for ${step$1.id}`);
 		}
 		const outcome = lastOutcome;
-		stepResults.push({
+		const recorded = scrubLiveStepText({
 			stepId: step$1.id,
 			source: step$1.source,
 			instruction: step$1.instruction,
@@ -9459,10 +9688,11 @@ async function runLiveExecutor(input) {
 			durationMs: Date.now() - stepStartedAt,
 			cost: outcome.cost,
 			commands: outcome.commands
-		});
-		if (outcome.status === "passed") step("STEP_DONE", step$1.id, outcome.reasoning);
+		}, input.envScrubMap);
+		stepResults.push(recorded);
+		if (outcome.status === "passed") step("STEP_DONE", step$1.id, recorded.reasoning);
 		else {
-			step("ASSERTION_FAILED", step$1.id, outcome.reasoning);
+			step("ASSERTION_FAILED", step$1.id, recorded.reasoning);
 			overallFailed = true;
 		}
 	}
@@ -9502,7 +9732,8 @@ async function runLiveExecutor(input) {
 		const transcript = transcriptParts.join("\n");
 		const after = takeScreenshot(input.sessionName, paths.afterPng, { fullPage: true });
 		if (!after.ok) warn(`screenshot (after, ${step.id}) failed: ${after.error}`);
-		await writeFile(paths.logTxt, transcript || "(no assistant text captured)", "utf-8");
+		const scrubbed = scrubEnvValues(transcript, input.envScrubMap);
+		await writeFile(paths.logTxt, scrubbed || "(no assistant text captured)", "utf-8");
 		const { status, reasoning } = judgeStepOutcome({
 			step,
 			isError,
@@ -9604,6 +9835,18 @@ function judgeStepOutcome({ step, isError, errorDetail, judged }) {
 		reasoning: judged.stepId === step.id ? baseReason : `(stepId mismatch: model wrote ${judged.stepId}) ${baseReason}`
 	};
 }
+/**
+* Scrub the strings a step carries that the model authored: its verdict prose
+* and the commands it issued. `instruction` / `expected` are copied from the
+* spec, which keeps `${VAR}` symbolic, so they need nothing.
+*/
+function scrubLiveStepText(step, scrubMap) {
+	return {
+		...step,
+		reasoning: scrubEnvValues(step.reasoning, scrubMap),
+		commands: step.commands.map((c) => scrubEnvValues(c, scrubMap))
+	};
+}
 function buildSkippedStep(step, reason) {
 	return {
 		stepId: step.id,
@@ -10015,6 +10258,7 @@ async function runOneSpec(args) {
 	}
 	const spec = parseTestSpec(specContent);
 	const expanded = expandSpec(spec, { blocks: await loadAllBlocks(cwd) });
+	const envScrubMap = buildLiveEnvScrubMap(spec, expanded);
 	meta("spec", spec.title);
 	meta("steps", expanded.length);
 	const includes = collectIncludedBlockNames(spec);
@@ -10053,6 +10297,7 @@ async function runOneSpec(args) {
 			runId,
 			runDir,
 			sessionName,
+			envScrubMap,
 			statePath,
 			verifyUrl,
 			systemPromptSuffix: userPromptSuffix,
@@ -12565,6 +12810,7 @@ async function executeRun(targets, opts) {
 	const forExecution = opts.dryRun !== true;
 	const cwd = opts.cwd ?? process.cwd();
 	const wantsLastGreen = opts.onFailExplain === true && opts.onFailExplainBase === void 0;
+	const rerunMode = opts.onFailExplain === true ? opts.onFailExplainRerun ?? "never" : "never";
 	const [head, fixedBase] = await Promise.all([getGitHead(cwd), forExecution && opts.onFailExplain && opts.onFailExplainBase !== void 0 ? resolveAnalysisBase(opts.onFailExplainBase, "--on-fail-explain-base", cwd) : null]);
 	const git = {
 		head,
@@ -12736,6 +12982,7 @@ async function executeRun(targets, opts) {
 		if (opts.liveArtifactsDir) warn(`--live-artifacts-dir 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 (opts.onFailExplainRerun !== void 0 && rerunMode === "never" && opts.onFailExplainRerun !== "never") warn("--on-fail-explain-rerun is ignored: without --on-fail-explain nothing is classified, so a second attempt would settle nothing");
 	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();
 	if (opts.dryRun) {
@@ -12817,7 +13064,7 @@ async function executeRun(targets, opts) {
 		...opts.language ? { language: opts.language } : {},
 		report: incrementalReport
 	});
-	const live = await runLiveSpecs(liveSpecs, {
+	const liveOpts = {
 		...opts.model ? { model: opts.model } : {},
 		...opts.language ? { language: opts.language } : {},
 		...opts.liveArtifactsDir && liveSpecs.length === 1 ? { out: opts.liveArtifactsDir } : {},
@@ -12833,7 +13080,8 @@ async function executeRun(targets, opts) {
 		triageUserPrompt,
 		...opts.teardown ? { teardown: opts.teardown } : {},
 		report: incrementalReport
-	});
+	};
+	const live = await runLiveSpecs(liveSpecs, liveOpts);
 	let overallExitCode = det.exitCode !== 0 ? 1 : 0;
 	if (live.failedCount > 0) overallExitCode = 1;
 	if (externalRows.some((r) => r.status === "failed")) overallExitCode = 1;
@@ -12851,11 +13099,23 @@ async function executeRun(targets, opts) {
 		const analyzedExternalRows = await analyzeExternalRows(externalRows, analysisRun);
 		report = await writeUnifiedReport({
 			reportDir,
-			results: [
+			results: await rerunExplainedFailures([
 				...detResults,
 				...analyzedExternalRows,
 				...live.reportResults
-			],
+			], {
+				mode: rerunMode,
+				maxSpecs: opts.onFailExplainRerunMaxSpecs ?? null,
+				execute: createRerunExecutor({
+					detSpecs,
+					liveSpecs,
+					dispatch,
+					liveOpts,
+					opts,
+					cwd,
+					resources
+				})
+			}),
 			git,
 			customPromptVersion,
 			triageUserPromptHash,
@@ -13135,6 +13395,68 @@ async function analyzeDeterministicSummaries(summaries, cwd, reportDir, { pass }
 	return results;
 }
 /**
+* How `--on-fail-explain-rerun` re-executes one spec: on the same path that
+* just ran it, with the same inputs, so the second attempt answers the same
+* question the first did.
+*
+* Everything it writes goes to a throwaway report directory. The failed run's
+* screenshots and artifacts are the record of what happened, and a rerun that
+* shares their paths would overwrite them with a different attempt's — the
+* external runner and the live adapter both recreate a spec's directories.
+* Nothing here upserts a row or classifies: the attempt is evidence about the
+* run's row, not a row of its own.
+*/
+function createRerunExecutor(ctx) {
+	const detKeys = new Set(ctx.detSpecs.map(specKey));
+	const liveKeys = new Set(ctx.liveSpecs.map(specKey));
+	return async (ref) => {
+		const key = specKey(ref);
+		const scratch = await mkdtemp(join(tmpdir(), "ccqa-rerun-"));
+		try {
+			if (detKeys.has(key)) {
+				const summary = await runOneDeterministicSpec(ref, 0, {
+					cwd: ctx.cwd,
+					tmpDir: scratch,
+					vitestConfig: await resolveVitestConfig(ctx.cwd),
+					captureOutput: false,
+					reportDir: scratch,
+					captureEvidence: false
+				});
+				return summary !== null && !failedSpec(summary) ? "passed" : "failed";
+			}
+			if (liveKeys.has(key)) {
+				const { report: _streamed, ...liveOpts } = ctx.liveOpts;
+				return (await runLiveSpecs([ref], {
+					...liveOpts,
+					reportDir: scratch,
+					diffProvider: null,
+					concurrency: 1
+				})).failedCount > 0 ? "failed" : "passed";
+			}
+			const group = ctx.dispatch.external.find((g) => g.specs.some((s) => specKey(s) === key));
+			if (group === void 0) throw new Error(`${key} has no execution path to re-run`);
+			const [row] = await group.runner.run([ref], {
+				cwd: ctx.cwd,
+				reportDir: scratch,
+				concurrency: 1,
+				resources: ctx.resources,
+				...ctx.opts.model ? { model: ctx.opts.model } : {},
+				...ctx.opts.language ? { language: ctx.opts.language } : {},
+				targetId: group.targetId,
+				targetConfig: group.targetConfig,
+				stepEvidence: group.stepEvidence,
+				onSpecComplete: async () => {}
+			});
+			return row?.status === "passed" ? "passed" : "failed";
+		} finally {
+			await rm(scratch, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+/**
 * Build the report envelope — every `RunReportData` field except `results`.
 * Extracted so the incremental writer (which flushes report.json after each
 * spec) and the final batch write share one source of truth for these fields.
@@ -13434,7 +13756,10 @@ const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command(
 	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) => {
+}, 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.").option("--on-fail-explain-rerun <when>", "With --on-fail-explain: run a failed spec a second time so the classifier can tell a flake from a real failure. 'auto' reruns the failures whose label turns on it (UNKNOWN, ENVIRONMENT), 'always' every classified failure, 'never' (default) none. A second attempt that passes labels the row ENVIRONMENT; the spec still counts as failed. Costs a full spec execution each — live specs included.", (raw) => {
+	if (EXPLAIN_RERUN_MODES.includes(raw)) return raw;
+	throw new Error(`--on-fail-explain-rerun must be one of ${EXPLAIN_RERUN_MODES.join(" | ")}`);
+}, "never").option("--on-fail-explain-rerun-max-specs <n>", "Rerun at most N specs, in report order; the rest are named in the run summary and keep the label they were first given. Default: no cap. The knob for an environment having a bad day, where the alternative is turning the reruns off entirely.", parseRerunMaxSpecs).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-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) => {
@@ -13449,6 +13774,12 @@ function parseConcurrency$1(raw) {
 	}
 	return n;
 }
+/** Parse --on-fail-explain-rerun-max-specs: a positive integer. Zero is `--on-fail-explain-rerun never`. */
+function parseRerunMaxSpecs(raw) {
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n < 1) throw new Error(`--on-fail-explain-rerun-max-specs must be a positive integer, got "${raw}" (for none, pass --on-fail-explain-rerun never)`);
+	return n;
+}
 /** Header label shown after `ccqa run`: the lone target, a count, or how they were selected. */
 function headerTarget(targets, opts) {
 	if (targets.length === 1) return targets[0];
@@ -14270,73 +14601,6 @@ function isPassiveAction(action) {
 	return action === "snapshot" || action === "wait" || action === "assert";
 }
 //#endregion
-//#region src/runtime/env-scrub.ts
-/**
-* Build a list of `[envValue, "${VAR}"]` pairs for every `${VAR}` reference
-* mentioned in the spec OR in any of its expanded (block-inlined) steps.
-* Used at trace time to scrub recorded Claude-text outputs so a value the
-* spec author intentionally threaded through `process.env` is preserved as
-* `${VAR}` in `ir.json` rather than baked in as the concrete
-* trace-time value.
-*
-* Why we walk `spec.steps` AND `expanded`:
-*   - `spec.steps` carries the spec's own `instruction` / `expected` + each
-*     include's raw `params` (which may themselves be `${ENV}` refs).
-*   - `expanded` carries the inlined block-internal steps, whose
-*     `instruction` / `expected` may *also* contain `${ENV}` refs that
-*     don't go through include params.
-*
-* Only refs whose env value is currently non-empty land in the map —
-* scrubbing against an empty string would corrupt unrelated empty strings
-* in the action stream. Names whose env is unset are returned via
-* `unresolved` so the caller can warn the user.
-*
-* Longer values sort first so a `${SHORT}` whose value is a substring of a
-* `${LONG}` value doesn't clobber the longer one.
-*
-* `title` is deliberately NOT scanned — it never reaches the recorded action
-* stream.
-*/
-function buildSpecEnvScrub(spec, expanded) {
-	const refNames = /* @__PURE__ */ new Set();
-	for (const step of spec.steps) if (isIncludeStep(step)) for (const v of Object.values(step.params ?? {})) collect(v, refNames);
-	else {
-		collect(step.instruction, refNames);
-		collect(step.expected, refNames);
-	}
-	for (const step of expanded) {
-		collect(step.instruction, refNames);
-		collect(step.expected, refNames);
-	}
-	const map = [];
-	const unresolved = [];
-	for (const name of refNames) {
-		const value = process.env[name];
-		if (typeof value === "string" && value.length > 0) map.push([value, "${" + name + "}"]);
-		else unresolved.push(name);
-	}
-	map.sort((a, b) => b[0].length - a[0].length);
-	return {
-		map,
-		unresolved
-	};
-}
-function collect(value, into) {
-	for (const name of iterEnvRefNames(value)) into.add(name);
-}
-/**
-* Replace every occurrence of an env value with its `${VAR}` placeholder in
-* `text`. **Caller invariant**: the map must be sorted longest-value-first
-* so a shorter value doesn't shadow a longer one that contains it as a
-* substring. `buildSpecEnvScrub` upholds this; hand-built maps should too.
-*/
-function scrubEnvValues(text, scrubMap) {
-	if (scrubMap.length === 0) return text;
-	let out = text;
-	for (const [value, placeholder] of scrubMap) if (out.includes(value)) out = out.replaceAll(value, placeholder);
-	return out;
-}
-//#endregion
 //#region src/runtime/literal-scrub.ts
 /**
 * Patterns are listed in roughly descending confidence — a hit on `clock-hms`
@@ -17132,6 +17396,32 @@ function mergeBucket(into, from) {
 	}
 }
 //#endregion
+//#region src/hub/core/retention.ts
+/**
+* Drop everything past the newest `maxRuns` of the (project, branch) that
+* `run` belongs to, taking each evicted run's artifacts and triage records
+* with it.
+*
+* Runs at a terminal state trigger this, rather than a sweep at startup: the
+* hub whose disk grows is the one written to constantly and never restarted,
+* which is exactly the one a startup sweep never fires on.
+*
+* Best-effort like the ledger updates it runs beside — a lost sweep costs
+* disk, while failing the push it hangs off would cost the run.
+*/
+async function sweepRunRetention(storage, run, maxRuns) {
+	try {
+		const group = (await storage.runs.list({ project: run.project })).filter((r) => r.branch === run.branch && r.status !== "running");
+		for (const evicted of group.slice(maxRuns)) {
+			await storage.runs.delete(evicted.id);
+			await storage.artifacts.delete(evicted.id);
+			await storage.triage.deleteAll(evicted.id);
+		}
+	} catch (err) {
+		console.error(`hub: run retention sweep failed for "${run.project}": ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+//#endregion
 //#region src/hub/api/validate.ts
 /**
 * Validators for the request parameters handlers read straight off the wire:
@@ -17195,6 +17485,7 @@ const DEFAULT_MAX_PUSH_BYTES = 32 * 1024 * 1024;
 */
 function createPushRunHandler(config) {
 	const maxPushBytes = config.maxPushBytes ?? DEFAULT_MAX_PUSH_BYTES;
+	const maxRunsPerBranch = config.maxRunsPerBranch ?? 200;
 	return async (ctx) => {
 		const { project, branch, profile, kind, deployedSha } = parseRunScope(ctx);
 		const body = await readBody(ctx.req, maxPushBytes);
@@ -17246,6 +17537,7 @@ function createPushRunHandler(config) {
 			await config.storage.runs.create(run);
 			await updateSpecLedger(config.storage, run, report.results);
 			await updateDriftLedger(config.storage, run, report.results);
+			await sweepRunRetention(config.storage, run, maxRunsPerBranch);
 			sendJson(ctx.res, 201, run);
 		} finally {
 			await rm(dir, {
@@ -17485,6 +17777,7 @@ async function deployHeadMovedDuringRun(storage, run) {
 */
 function createPatchRunHandler(config) {
 	const maxPushBytes = config.maxPushBytes ?? DEFAULT_MAX_PUSH_BYTES;
+	const maxRunsPerBranch = config.maxRunsPerBranch ?? 200;
 	return async (ctx) => {
 		const id = ctx.params.id;
 		const run = await getRunOr404(config.storage, id);
@@ -17548,7 +17841,10 @@ function createPatchRunHandler(config) {
 		};
 		const updated = await config.storage.runs.update(id, patch);
 		await updateDriftLedger(config.storage, updated, mergedResults);
-		if (done) await updateSpecLedger(config.storage, updated, mergedResults);
+		if (done) {
+			await updateSpecLedger(config.storage, updated, mergedResults);
+			await sweepRunRetention(config.storage, updated, maxRunsPerBranch);
+		}
 		sendJson(ctx.res, 200, updated);
 	};
 }
@@ -19699,6 +19995,8 @@ const CSS = `
   /* which generation target ran the spec (agent-browser / playwright / runn) */
   .badge-target { display: inline-flex; align-items: center; padding: 2px 8px; border-radius: var(--radius-sm); font-size: 11px; font-family: var(--mono); background: var(--surface-3); color: var(--muted); border: 1px solid var(--border); }
   .chip { display: inline-flex; align-items: center; padding: 1px 8px; border-radius: 6px; background: var(--surface-3); border: 1px solid var(--border); color: var(--fg-dim); font-size: 12px; font-family: var(--mono); white-space: nowrap; }
+  .chip.icon-chip { gap: 5px; padding-left: 6px; }
+  .chip.icon-chip svg { width: 12px; height: 12px; flex: none; opacity: .7; }
   /* Below .chip in source order so these override its background/border/color
      when combined as class="chip drift-count-chip" (same specificity — source
      order decides). One amber look for every drift label chip — a label chip
@@ -20184,6 +20482,7 @@ const CLIENT_JS = `
       "detail.back": "Runs", "detail.specs": "Specs",
       "detail.download": "Download artifacts",
       "detail.triage": "Triage",
+      "detail.notKept": "This run is no longer kept — the hub keeps only the most recent runs of each branch.",
       "meta.branch": "Branch", "meta.specs": "Specs", "meta.cost": "Cost",
       "meta.created": "Created", "meta.passed": "passed", "meta.profile": "Profile",
       "meta.drift": "Drift",
@@ -20347,6 +20646,7 @@ const CLIENT_JS = `
       "detail.back": "実行", "detail.specs": "スペック",
       "detail.download": "アーティファクトをダウンロード",
       "detail.triage": "トリアージ",
+      "detail.notKept": "この実行はもう保持されていません — ハブは各ブランチの直近の実行だけを保持します。",
       "meta.branch": "ブランチ", "meta.specs": "スペック", "meta.cost": "コスト",
       "meta.created": "作成", "meta.passed": "合格", "meta.profile": "プロファイル",
       "meta.drift": "ドリフト",
@@ -20637,7 +20937,9 @@ const CLIENT_JS = `
         // A reverse proxy can answer with non-JSON (an HTML 502 page) — fall
         // back to the status line instead of a JSON-parse error message.
         return res.json().catch(function () { return null; }).then(function (b) {
-          throw new Error((b && b.error && b.error.message) || (res.status + " " + res.statusText));
+          var err = new Error((b && b.error && b.error.message) || (res.status + " " + res.statusText));
+          err.status = res.status;
+          throw err;
         });
       }
       return res.status === 204 ? null : res.json();
@@ -20857,6 +21159,45 @@ const CLIENT_JS = `
     return svg;
   }
 
+  function svgCircle(cx, cy, r) {
+    var c = document.createElementNS(SVG_NS, "circle");
+    c.setAttribute("cx", cx);
+    c.setAttribute("cy", cy);
+    c.setAttribute("r", r);
+    return c;
+  }
+
+  /** A fork in a line — the conventional git-branch glyph. */
+  function svgBranch() {
+    var svg = svgIcon();
+    svg.appendChild(svgPath("M6 3v12"));
+    svg.appendChild(svgCircle("18", "6", "3"));
+    svg.appendChild(svgCircle("6", "18", "3"));
+    svg.appendChild(svgPath("M18 9a9 9 0 0 1-9 9"));
+    return svg;
+  }
+
+  /** Stacked racks — a profile names a deployed environment, not a code path. */
+  function svgProfile() {
+    var svg = svgIcon();
+    svg.appendChild(svgPath("M4 4h16v6H4zM4 14h16v6H4z"));
+    svg.appendChild(svgPath("M8 7h.01M8 17h.01"));
+    return svg;
+  }
+
+  /**
+   * A chip whose glyph says which field it is. Two of these sit side by side on
+   * every run, so without one they read as two unlabelled words. The title is
+   * the fallback for anyone the glyph does not reach.
+   */
+  function iconChip(icon, text, label) {
+    var chip = el("span", "chip icon-chip");
+    chip.title = label;
+    chip.appendChild(icon);
+    chip.appendChild(document.createTextNode(text));
+    return chip;
+  }
+
   // Round caps so the "i"/"!" dot (a zero-length segment) actually paints as a
   // filled dot instead of vanishing under a butt cap at small sizes.
   function svgRounded() {
@@ -21112,8 +21453,8 @@ const CLIENT_JS = `
       var sub = el("div", "subline");
       sub.appendChild(ciBadge(r));
       sub.appendChild(kindChip(r.kind));
-      sub.appendChild(el("span", "chip", r.branch || "—"));
-      if (r.profile) sub.appendChild(el("span", "chip", r.profile));
+      sub.appendChild(iconChip(svgBranch(), r.branch || "—", t("meta.branch")));
+      if (r.profile) sub.appendChild(iconChip(svgProfile(), r.profile, t("meta.profile")));
       if (r.kind === "drift") {
         var rowDrift = driftSummary(r);
         if (rowDrift) driftChips(rowDrift).forEach(function (chip) { sub.appendChild(chip); });
@@ -21995,12 +22336,10 @@ const CLIENT_JS = `
 
   // ── run detail: orchestration ───────────────────────────────────────
 
-  function detailError(what) {
-    return function (err) {
-      var e = document.getElementById("detail-error");
-      e.hidden = false;
-      e.textContent = what + ": " + err.message;
-    };
+  function detailError(msg) {
+    var e = document.getElementById("detail-error");
+    e.hidden = false;
+    e.textContent = msg;
   }
 
   function openRunDetail(runId) {
@@ -22016,9 +22355,17 @@ const CLIENT_JS = `
     document.getElementById("detail-spec-count").textContent = "";
     document.getElementById("triage-summary").textContent = "";
 
+    // Retention drops a run but never the ledger entries pointing at it, so a
+    // Perspectives link can outlive its target. That 404 is the whole story of
+    // the page, so it speaks for the report's failure too.
+    var runGone = false;
+
     apiFetch("/api/v1/runs/" + encodeURIComponent(runId)).then(function (run) {
       renderRunHead(run);
-    }).catch(detailError("Error loading run"));
+    }).catch(function (err) {
+      runGone = err.status === 404;
+      detailError(runGone ? t("detail.notKept") : "Error loading run: " + err.message);
+    });
 
     apiFetch("/api/v1/runs/" + encodeURIComponent(runId) + "/report").then(function (report) {
       // Draw the spec cards first from the report alone, then re-draw once
@@ -22034,7 +22381,9 @@ const CLIENT_JS = `
       loadTriage(runId, isDrift, function (loaded) {
         renderSpecCards(runId, report.results, loaded, isDrift);
       });
-    }).catch(detailError("Error loading report"));
+    }).catch(function (err) {
+      if (!runGone) detailError("Error loading report: " + err.message);
+    });
   }
 
   // ── learning jobs ────────────────────────────────────────────────────
@@ -24436,14 +24785,17 @@ function registerRoutes(router, config, queue) {
 		ctx.res.setHeader("Cache-Control", "no-cache");
 		ctx.res.end(renderHubUi());
 	});
+	const retention = config.maxRunsPerBranch != null ? { maxRunsPerBranch: config.maxRunsPerBranch } : {};
 	router.post("/api/v1/runs", createPushRunHandler({
 		storage,
-		...config.maxPushBytes ? { maxPushBytes: config.maxPushBytes } : {}
+		...config.maxPushBytes ? { maxPushBytes: config.maxPushBytes } : {},
+		...retention
 	}));
 	router.post("/api/v1/runs/open", createOpenRunHandler({ storage }));
 	router.patch("/api/v1/runs/:id", createPatchRunHandler({
 		storage,
-		...config.maxPushBytes != null ? { maxPushBytes: config.maxPushBytes } : {}
+		...config.maxPushBytes != null ? { maxPushBytes: config.maxPushBytes } : {},
+		...retention
 	}));
 	router.get("/api/v1/runs", createListRunsHandler(storage));
 	router.get("/api/v1/runs/:id", createGetRunHandler(storage));
@@ -24557,12 +24909,14 @@ async function writeJson(path, value) {
 * update concurrently.
 */
 const updateChains = /* @__PURE__ */ new Map();
-async function updateJson(path, mutate) {
-	const next = (updateChains.get(path) ?? Promise.resolve()).catch(() => {}).then(async () => {
-		const updated = mutate(await readJson(path));
-		await writeJson(path, updated);
-		return updated;
-	});
+/**
+* Queue `work` behind whatever is already in flight for `path`. A delete takes
+* the same chain as the updates it removes: `writeJson` recreates the parent
+* directory, so an unordered delete would be silently undone by an update that
+* was already queued.
+*/
+async function serialize(path, work) {
+	const next = (updateChains.get(path) ?? Promise.resolve()).catch(() => {}).then(work);
 	updateChains.set(path, next);
 	try {
 		return await next;
@@ -24570,6 +24924,13 @@ async function updateJson(path, mutate) {
 		if (updateChains.get(path) === next) updateChains.delete(path);
 	}
 }
+async function updateJson(path, mutate) {
+	return await serialize(path, async () => {
+		const updated = mutate(await readJson(path));
+		await writeJson(path, updated);
+		return updated;
+	});
+}
 /** Read a raw file, returning `null` when it doesn't exist. */
 async function readBytesOrNull(path) {
 	try {
@@ -24820,6 +25181,10 @@ function createFileArtifactStore(root) {
 		async updateJsonFile(runId, relPath, mutate) {
 			assertSafeRelPath(relPath);
 			await updateJson(join(artifactsRunDir(root, runId), relPath), mutate);
+		},
+		async delete(runId) {
+			const dir = artifactsRunDir(root, runId);
+			await serialize(join(dir, "report.json"), () => removePath(dir));
 		}
 	};
 }
@@ -25080,6 +25445,9 @@ function createFileRunStore(root) {
 				};
 			});
 		},
+		async delete(id) {
+			await serialize(runMetaPath(root, id), () => removePath(runDir(root, id)));
+		},
 		async list({ project, branch, status, kinds, since, until, limit }) {
 			const ids = await listSubdirsOrEmpty(runsDir(root));
 			const inWindow = windowFilter({
@@ -25234,6 +25602,10 @@ function createFileTriageStore(root) {
 				return (current ?? []).filter((r) => !(r.feature === feature && r.spec === spec));
 			});
 		},
+		async deleteAll(runId) {
+			const path = triagePath(root, runId);
+			await serialize(path, () => removePath(path));
+		},
 		async list(runId) {
 			return await readJson(triagePath(root, runId)) ?? [];
 		}
@@ -25275,7 +25647,7 @@ function createHubStorage(config) {
 }
 //#endregion
 //#region src/cli/serve.ts
-const serveCommand = new Command("serve").description("Start the ccqa hub: a small control-plane HTTP server that aggregates CI run results, sessions, variables, and triage records. It does not execute tests — CI/local `ccqa run` produces reports and `ccqa hub push` uploads them here. Any HTTP client (docs/hub-api.md) can talk to it.").option("--port <n>", "TCP port to listen on.", "8787").option("--data-dir <path>", "Directory to store runs, sessions, and variables in.", "./ccqa-hub-data").option("--allow-origin <origin>", "CORS-allowed origin for browser clients (repeatable). Omit for no cross-origin access.", (val, prev) => [...prev, val], []).option("--max-push-mb <n>", "Reject pushed report bundles larger than this (MB). Default 32.", parsePositiveInt).action(async (opts) => {
+const serveCommand = new Command("serve").description("Start the ccqa hub: a small control-plane HTTP server that aggregates CI run results, sessions, variables, and triage records. It does not execute tests — CI/local `ccqa run` produces reports and `ccqa hub push` uploads them here. Any HTTP client (docs/hub-api.md) can talk to it.").option("--port <n>", "TCP port to listen on.", "8787").option("--data-dir <path>", "Directory to store runs, sessions, and variables in.", "./ccqa-hub-data").option("--allow-origin <origin>", "CORS-allowed origin for browser clients (repeatable). Omit for no cross-origin access.", (val, prev) => [...prev, val], []).option("--max-push-mb <n>", "Reject pushed report bundles larger than this (MB). Default 32.", parsePositiveInt).option("--max-runs-per-branch <n>", "Keep this many runs per project and branch; older ones are deleted with their artifacts and grades. Default 200.", parsePositiveInt).action(async (opts) => {
 	await runServe(opts);
 });
 function parsePositiveInt(raw) {
@@ -25310,7 +25682,8 @@ async function runServe(opts) {
 		token,
 		encryptionKey,
 		allowedOrigins: opts.allowOrigin ?? [],
-		...opts.maxPushMb ? { maxPushBytes: opts.maxPushMb * 1024 * 1024 } : {}
+		...opts.maxPushMb ? { maxPushBytes: opts.maxPushMb * 1024 * 1024 } : {},
+		...opts.maxRunsPerBranch ? { maxRunsPerBranch: opts.maxRunsPerBranch } : {}
 	});
 	const requestedPort = Number(opts.port);
 	if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
@@ -25327,6 +25700,7 @@ async function runServe(opts) {
 		header("serve", `port ${boundPort}`);
 		meta("data-dir", dataDir);
 		meta("encryption", encryptionKey ? "enabled" : "disabled (no CCQA_HUB_ENCRYPTION_KEY)");
+		meta("run retention", `${opts.maxRunsPerBranch ?? 200} per project/branch`);
 		const auth = driftAuthAvailable();
 		meta("triage learning", auth.ok ? "available" : `unavailable (${auth.reason} — learning jobs will fail)`);
 		if (opts.allowOrigin && opts.allowOrigin.length > 0) meta("cors", opts.allowOrigin.join(", "));

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

@@ -533,6 +533,12 @@ declare const ReportSpecResultSchema: z.ZodObject<{
     }>>;
   }, z.core.$strip>>;
   analysisSkipped: z.ZodNullable<z.ZodString>;
+  rerun: z.ZodOptional<z.ZodObject<{
+    outcome: z.ZodEnum<{
+      passed: "passed";
+      failed: "failed";
+    }>;
+  }, z.core.$strip>>;
   customPromptVersion: z.ZodOptional<z.ZodString>;
   analysisBase: z.ZodOptional<z.ZodNullable<z.ZodObject<{
     ref: z.ZodString;
@@ -711,6 +717,12 @@ declare const RunReportDataSchema: z.ZodObject<{
       }>>;
     }, z.core.$strip>>;
     analysisSkipped: z.ZodNullable<z.ZodString>;
+    rerun: z.ZodOptional<z.ZodObject<{
+      outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+      }>;
+    }, z.core.$strip>>;
     customPromptVersion: z.ZodOptional<z.ZodString>;
     analysisBase: z.ZodOptional<z.ZodNullable<z.ZodObject<{
       ref: z.ZodString;

package/dist/package.json

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

package/package.json

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