ccqa 1.3.0 → 1.4.0

package/dist/bin/ccqa.mjs

@@ -11,10 +11,10 @@ import { basename, dirname, isAbsolute, join, normalize, posix, relative, resolv
 import { parse, stringify } from "yaml";
 import { ZodError, z } from "zod";
 import { execFile, spawn, spawnSync } from "node:child_process";
-import { query } from "@anthropic-ai/claude-agent-sdk";
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { promisify } from "node:util";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { createInterface } from "node:readline";
 import { createInterface as createInterface$1 } from "node:readline/promises";
@@ -679,10 +679,10 @@ function bundledVitestConfigPath() {
 }
 //#endregion
 //#region src/runtime/spawn-vitest.ts
-const require$1 = createRequire(import.meta.url);
+const require$2 = createRequire(import.meta.url);
 function resolveVitestBin() {
-	const pkgPath = require$1.resolve("vitest/package.json");
-	const pkg = require$1(pkgPath);
+	const pkgPath = require$2.resolve("vitest/package.json");
+	const pkg = require$2(pkgPath);
 	const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vitest;
 	if (!binRel) throw new Error(`vitest package.json has no bin entry (resolved at ${pkgPath})`);
 	return resolve(dirname(pkgPath), binRel);
@@ -1194,6 +1194,50 @@ function opt(key, value) {
 	return value ? { [key]: value } : {};
 }
 //#endregion
+//#region src/claude/native-binary.ts
+const require$1 = createRequire(import.meta.url);
+/**
+* The agent SDK launches Claude through a native `claude` binary that ships in
+* a per-platform package (`@anthropic-ai/claude-agent-sdk-<platform>-<cpu>`),
+* declared as an *optional* dependency of the SDK. Optional means a consumer's
+* lockfile can omit it without any install-time error — and then every Claude
+* call fails at runtime with a message that never reaches our logs. Resolving
+* the package up front lets us say so once, in a line that names the fix.
+*
+* ccqa's own package.json repeats these packages in `optionalDependencies` for
+* the same reason: a second declaration gives the resolver another chance to
+* record them. Keep that list's version range in step with the SDK's.
+*/
+function nativeBinaryPackage(platform = process.platform, arch = process.arch, musl = isMusl(platform)) {
+	return `@anthropic-ai/claude-agent-sdk-${platform}-${arch === "arm64" ? "arm64" : "x64"}${platform === "linux" && musl ? "-musl" : ""}`;
+}
+/**
+* musl builds (Alpine and friends) need their own binary. Node doesn't expose
+* the libc flavour directly; the absence of `glibcVersionRuntime` in the
+* process report is the usual proxy.
+*/
+function isMusl(platform) {
+	if (platform !== "linux") return false;
+	return !(process.report?.getReport?.())?.header?.glibcVersionRuntime;
+}
+/**
+* Name of the platform package this host needs, or `null` when it resolves.
+* The per-platform packages have no `exports`, so the manifest is reachable.
+*/
+function missingNativeBinaryPackage(resolve = require$1.resolve) {
+	const pkg = nativeBinaryPackage();
+	try {
+		resolve(`${pkg}/package.json`);
+		return null;
+	} catch {
+		return pkg;
+	}
+}
+/** Advice shown when the binary is absent — the package name plus how to fix it. */
+function missingNativeBinaryMessage(pkg) {
+	return `${pkg} is not installed. The Claude Agent SDK needs it to start Claude on this platform, so every Claude-backed command (run in live mode, drift, diagnose) will fail. It ships as an optional dependency of the SDK, which a lockfile can drop silently: reinstall without omitting optional dependencies, or add it to your project as a direct dependency pinned to the same version as @anthropic-ai/claude-agent-sdk.`;
+}
+//#endregion
 //#region src/claude/invoke.ts
 function resolveModel(explicit) {
 	if (explicit) return explicit;
@@ -1230,8 +1274,20 @@ function resolveEndpointEnv() {
 	}
 	return endpointEnv;
 }
+let nativeBinaryWarned = false;
+/**
+* Warn once per process when the SDK's per-platform native binary is missing:
+* every Claude call is about to fail, and the opaque per-step errors alone are
+* expensive to trace back to a lockfile that dropped an optional dependency.
+*/
+function warnOnceIfNativeBinaryMissing() {
+	if (nativeBinaryWarned) return;
+	nativeBinaryWarned = true;
+	const missing = missingNativeBinaryPackage();
+	if (missing) warn(missingNativeBinaryMessage(missing));
+}
 async function invokeClaudeStreaming(options, onEvent) {
-	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, disableThinking = false, maxTurns, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, relaxAbConstraints = false } = options;
+	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, disableThinking = false, mcpServers, maxTurns, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, relaxAbConstraints = false } = options;
 	const resolvedModel = resolveModel(model);
 	const hasEndpointEnv = Object.keys(resolveEndpointEnv()).length > 0;
 	const mergedEnv = env || hasEndpointEnv ? {
@@ -1253,6 +1309,7 @@ async function invokeClaudeStreaming(options, onEvent) {
 		...resolvedModel ? { model: resolvedModel } : {},
 		...cwd ? { cwd } : {},
 		...mergedEnv ? { env: mergedEnv } : {},
+		...mcpServers ? { mcpServers } : {},
 		...disableBuiltinTools ? { tools: [] } : {},
 		...disableThinking ? { thinking: { type: "disabled" } } : {},
 		hooks: onAbAction || onAbActionFailed ? {
@@ -1312,8 +1369,10 @@ async function invokeClaudeStreaming(options, onEvent) {
 			}] }]
 		} : void 0
 	};
+	warnOnceIfNativeBinaryMissing();
 	let result = "";
 	let isError = false;
+	let errorDetail = null;
 	let cost = {
 		totalCostUsd: null,
 		durationMs: null,
@@ -1336,18 +1395,24 @@ async function invokeClaudeStreaming(options, onEvent) {
 				}
 			}
 			if (msg.type === "result") {
-				result = msg.subtype === "success" ? msg.result : "";
 				isError = msg.is_error ?? false;
+				if (msg.subtype === "success") result = msg.result;
+				else {
+					result = "";
+					errorDetail = `SDK reported ${msg.subtype}`;
+				}
 				cost = extractInvocationCost(msg);
 			}
 		}
 	} catch (err) {
 		isError = true;
-		if (!result) result = err instanceof Error ? err.message : String(err);
+		errorDetail = err instanceof Error ? err.message : String(err);
+		if (!result) result = errorDetail;
 	}
 	return {
 		result,
 		isError,
+		errorDetail,
 		cost
 	};
 }
@@ -2220,171 +2285,6 @@ async function checkSpec(target, opts) {
 	};
 }
 //#endregion
-//#region src/drift/affected.ts
-const execFileP = promisify(execFile);
-/**
-* Resolve the base ref to diff against for `ccqa drift --changed`.
-* Precedence: explicit override > GITHUB_BASE_REF > origin/main.
-*/
-function resolveBaseRef(explicit) {
-	if (explicit && explicit.length > 0) return explicit;
-	const ghBase = process.env["GITHUB_BASE_REF"];
-	if (ghBase && ghBase.length > 0) return ghBase.startsWith("origin/") ? ghBase : `origin/${ghBase}`;
-	return "origin/main";
-}
-/**
-* Run `git diff --name-status base...HEAD` from `cwd` and return one entry per
-* changed file. Renames are reported under their NEW path with status
-* "renamed" — the OLD path is dropped because the spec mapping is against the
-* post-rename layout.
-*
-* Paths are re-rooted to be relative to `cwd`, not the git repo root. In a
-* monorepo where `cwd` is a sub-package (e.g. `apps/foo`), git emits paths
-* relative to the repo root, but specs declare relatedPaths relative to
-* their own package. Changes outside `cwd` are kept under their repo-root
-* path and flagged `outsideCwd` — they only scope a spec in when the spec
-* explicitly declares a repo-root-relative glob, so an unrelated PR can
-* never accidentally match the app-relative globs.
-*/
-async function getChangedFiles(base, cwd) {
-	const [{ stdout: rootOut }, { stdout: diffOut }] = await Promise.all([execFileP("git", ["rev-parse", "--show-toplevel"], { cwd }), execFileP("git", [
-		"diff",
-		"--name-status",
-		"-M",
-		`${base}...HEAD`
-	], {
-		cwd,
-		maxBuffer: 32 * 1024 * 1024
-	})]);
-	return rerootChangedFiles(parseGitDiffOutput(diffOut), rootOut.trim(), cwd);
-}
-/**
-* Convert paths in `entries` from git-repo-root relative to `cwd` relative.
-* Entries outside `cwd` keep their repo-root path and are flagged
-* `outsideCwd`. Exported for unit tests.
-*/
-function rerootChangedFiles(entries, repoRoot, cwd) {
-	const prefix = relative(repoRoot, cwd);
-	if (!prefix) return entries;
-	const out = [];
-	for (const e of entries) {
-		const rel = relative(prefix, e.path);
-		if (rel.startsWith("..") || rel === "") out.push({
-			...e,
-			outsideCwd: true
-		});
-		else out.push({
-			...e,
-			path: rel
-		});
-	}
-	return out;
-}
-function parseGitDiffOutput(stdout) {
-	const out = [];
-	for (const line of stdout.split("\n")) {
-		if (!line.trim()) continue;
-		const parts = line.split("	");
-		const code = parts[0];
-		if (!code) continue;
-		if (code.startsWith("R")) {
-			const newPath = parts[2];
-			if (newPath) out.push({
-				path: newPath,
-				status: "renamed"
-			});
-			continue;
-		}
-		if (code.startsWith("C")) {
-			const newPath = parts[2];
-			if (newPath) out.push({
-				path: newPath,
-				status: "added"
-			});
-			continue;
-		}
-		const path = parts[1];
-		if (!path) continue;
-		switch (code[0]) {
-			case "A":
-				out.push({
-					path,
-					status: "added"
-				});
-				break;
-			case "M":
-			case "T":
-				out.push({
-					path,
-					status: "modified"
-				});
-				break;
-			case "D":
-				out.push({
-					path,
-					status: "deleted"
-				});
-				break;
-			default: out.push({
-				path,
-				status: "modified"
-			});
-		}
-	}
-	return out;
-}
-function stripLeadingDotSlash(s) {
-	return s.startsWith("./") ? s.slice(2) : s;
-}
-const REGEX_CACHE = /* @__PURE__ */ new Map();
-/** Compiles `pattern` to a RegExp, memoized so repeated `--changed` matches don't re-build. */
-function compileGlob(pattern) {
-	const cached = REGEX_CACHE.get(pattern);
-	if (cached) return cached;
-	const compiled = globToRegExp(stripLeadingDotSlash(pattern));
-	REGEX_CACHE.set(pattern, compiled);
-	return compiled;
-}
-function globToRegExp(pattern) {
-	let re = "^";
-	let i = 0;
-	while (i < pattern.length) {
-		const ch = pattern[i];
-		if (ch === "?") {
-			re += "[^/]";
-			i++;
-			continue;
-		}
-		if (ch !== "*") {
-			re += /[.+^${}()|[\]\\]/.test(ch) ? "\\" + ch : ch;
-			i++;
-			continue;
-		}
-		if (pattern[i + 1] !== "*") {
-			re += "[^/]*";
-			i++;
-			continue;
-		}
-		const hasLeadingSlash = re.endsWith("/");
-		const hasTrailingSlash = pattern[i + 2] === "/";
-		if (hasLeadingSlash) re = re.slice(0, -1);
-		if (hasLeadingSlash || hasTrailingSlash) re += "(?:/?.*)?";
-		else re += ".*";
-		i += hasTrailingSlash ? 3 : 2;
-	}
-	return new RegExp(re + "$");
-}
-/**
-* Returns true if `changedPath` is covered by any of `relatedPaths`. An empty
-* `relatedPaths` returns false — callers handle the "unscoped spec" case
-* separately (treat the spec as always-affected) before calling this.
-*/
-function isPathAffectedBy(changedPath, relatedPaths) {
-	const stripped = stripLeadingDotSlash(changedPath);
-	for (const pattern of relatedPaths) if (compileGlob(pattern).test(stripped)) return true;
-	return false;
-}
-//#endregion
 //#region src/drift/auth.ts
 /**
 * Probe whether the host has any credential the Anthropic SDK can pick up:
@@ -3089,6 +2989,10 @@ const ReportSpecResultSchema = z.object({
 	assertions: z.array(ReportAssertionSchema).nullable(),
 	analysis: FailureAnalysisSchema.nullable(),
 	analysisSkipped: z.string().nullable(),
+	analysisBase: z.object({
+		ref: z.string(),
+		sha: z.string()
+	}).nullable().optional(),
 	driftIssues: z.array(DraftIssueSchema).nullable(),
 	failureLogExcerpt: z.string().nullable(),
 	diffExcerpt: z.string().nullable(),
@@ -3097,15 +3001,33 @@ const ReportSpecResultSchema = z.object({
 	artifacts: z.array(ReportArtifactSchema).optional(),
 	liveRun: LiveReportRunSchema.nullable()
 });
+/**
+* Which rule produced the analysis baseline: "explicit" (a value was
+* passed), "github-base-ref" (derived from a pull_request event), or
+* "last-green" (per-spec baselines from the hub ledger — `baseSha` is then
+* null and each analyzed row carries its own `analysisBase`). Lets accuracy
+* numbers be stratified by baseline provenance. Single source of truth —
+* `src/run/git-context.ts`'s `BaseSource` type and the hub's PATCH schema
+* both derive from this.
+*/
+const BaseSourceSchema = z.enum([
+	"explicit",
+	"github-base-ref",
+	"last-green"
+]);
+/** The report envelope's git block; also referenced by the hub's PATCH reportMeta schema. */
+const GitEnvelopeSchema = z.object({
+	head: z.string().nullable(),
+	base: z.string().nullable(),
+	baseSha: z.string().nullable().optional(),
+	baseSource: BaseSourceSchema.nullable().optional()
+});
 const RunReportDataSchema = z.object({
 	schemaVersion: z.literal(1),
 	kind: z.enum(["run", "drift"]).default("run"),
 	createdAt: z.string(),
 	runId: z.string().nullable(),
-	git: z.object({
-		head: z.string().nullable(),
-		base: z.string().nullable()
-	}),
+	git: GitEnvelopeSchema,
 	model: z.string().nullable(),
 	language: z.string().nullable().default(null),
 	promptVersion: z.string(),
@@ -3230,6 +3152,14 @@ function hashTriageUserPrompt(text) {
 }
 //#endregion
 //#region src/report/prompt.ts
+/**
+* Fully-qualified name of the on-demand file-diff tool, as the model calls
+* it. Lives here (not analyze.ts) because the prompt text below references
+* it — one source of truth. The name is the SDK's `mcp__<server>__<tool>`
+* composition of the server ("diff") and tool ("changed_file_diff") that
+* analyze.ts registers; changing either side must keep the two in sync.
+*/
+const CHANGED_FILE_DIFF_TOOL = "mcp__diff__changed_file_diff";
 function buildFailureAnalysisPrompt(input) {
 	const { script, specYaml, failureLog, liveTranscriptExcerpt, diffPatch, changedFiles, baseRef, driftIssues, outputLanguage = "auto", triageUserPrompt, customPrompt } = input;
 	const triageUserPromptBlock = buildTriageUserPromptBlock(triageUserPrompt);
@@ -3253,6 +3183,8 @@ You can call \`Grep\`, \`Glob\`, and \`Read\` against the current repository (po
 - read the changed files in full when the truncated patch is not enough,
 - check whether the element/flow the spec describes still exists in the source.
 
+You can also call \`${CHANGED_FILE_DIFF_TOOL}\` with a file path to fetch that file's diff hunk for this run's base...HEAD range. The inline patch below is scoped to this spec's relatedPaths — files OUTSIDE that scope still appear in "Changed files (name-status)" but their hunks are not inlined. Before blaming (or ruling out) such a file, fetch its diff with this tool; Read only shows you its post-change state, not what changed.
+
 You have **up to 12 tool turns**. Do NOT write, edit, run shell commands, or hit the network.
 
 ## Decision guidance
@@ -3357,19 +3289,45 @@ ${liveTranscriptExcerpt}`);
 //#endregion
 //#region src/report/analyze.ts
 /**
+* In-process MCP server exposing one tool: the diff hunk of a named changed
+* file. The inline patch in the prompt is only the relatedPaths-scoped seed;
+* this is the pull side — the model fetches hunks for files outside that
+* scope (or truncated inside it) only when it decides they matter, so the
+* full diff never has to ride in the prompt. Read-only over data already
+* captured in memory: no shell, no git access granted. The server/tool
+* names must compose to CHANGED_FILE_DIFF_TOOL (prompt.ts), which is how
+* the prompt tells the model to call it.
+*/
+function buildDiffMcpServer(getFileDiff) {
+	return createSdkMcpServer({
+		name: "diff",
+		version: "1.0.0",
+		tools: [tool("changed_file_diff", "Return the unified diff (base...HEAD) of one changed file from this run's diff range. Works for ANY file listed in 'Changed files (name-status)', including files outside the spec's relatedPaths scope whose hunks are not in the inline patch.", { path: z.string().describe("File path exactly as it appears in the name-status list") }, async ({ path }) => {
+			const hunk = getFileDiff(path);
+			if (hunk) info(`  diff tool: ${path}`);
+			return { content: [{
+				type: "text",
+				text: hunk ?? `No diff found for "${path}" in this run's diff range. Check the exact path in the name-status list (paths are relative to the working directory).`
+			}] };
+		})]
+	});
+}
+/**
 * Classify one failing spec into TEST_DRIFT / SPEC_CHANGE / PRODUCT_BUG /
 * UNKNOWN. Same resilience contract as diagnose(): read-only tools, JSON-only
 * final message, and any parse failure degrades to UNKNOWN with confidence 0
 * rather than throwing — the report must always render.
 */
-async function analyzeFailure(input, options = {}) {
+async function analyzeFailure(input, options) {
 	const { result: raw, isError } = await invokeClaudeStreaming({
 		prompt: buildFailureAnalysisPrompt(input),
 		allowedTools: [
 			"Read",
 			"Grep",
-			"Glob"
+			"Glob",
+			CHANGED_FILE_DIFF_TOOL
 		],
+		mcpServers: { diff: buildDiffMcpServer(options.getFileDiff) },
 		silenceBashLog: true,
 		maxTurns: 12,
 		...options.model ? { model: options.model } : {},
@@ -3411,44 +3369,223 @@ function unknownAnalysis(reasoning) {
 		reasoning
 	};
 }
-const LABELS = new Set(PREDICTED_LABELS);
-const SUB_SET = new Set(SUB_DIAGNOSES);
+const LABELS = new Set(PREDICTED_LABELS);
+const SUB_SET = new Set(SUB_DIAGNOSES);
+/**
+* Manual, lenient normalisation (mirrors diagnose's normaliseResult): a
+* missing/extra field should degrade gracefully, not reject the whole
+* prediction — only an unrecognisable label makes the candidate unusable.
+*/
+function normaliseFailureAnalysis(parsed) {
+	if (!isObject(parsed)) return null;
+	const label = parsed["label"];
+	if (typeof label !== "string" || !LABELS.has(label)) return null;
+	const confidence = typeof parsed["confidence"] === "number" ? clamp(parsed["confidence"], 0, 1) : 0;
+	const reasoning = typeof parsed["reasoning"] === "string" ? parsed["reasoning"] : "";
+	const headline = typeof parsed["headline"] === "string" ? parsed["headline"] : "";
+	const recommendation = typeof parsed["recommendation"] === "string" ? parsed["recommendation"] : "";
+	const rawSub = parsed["subDiagnosis"];
+	const subDiagnosis = typeof rawSub === "string" && SUB_SET.has(rawSub) ? rawSub : "NONE";
+	const evidence = [];
+	if (Array.isArray(parsed["evidence"])) for (const item of parsed["evidence"]) {
+		if (!isObject(item)) continue;
+		const detail = typeof item["detail"] === "string" ? item["detail"] : null;
+		if (detail === null) continue;
+		const file = typeof item["file"] === "string" ? item["file"] : void 0;
+		evidence.push(file !== void 0 ? {
+			file,
+			detail
+		} : { detail });
+		if (evidence.length >= 3) break;
+	}
+	return {
+		label,
+		confidence,
+		subDiagnosis,
+		headline,
+		recommendation,
+		evidence,
+		reasoning
+	};
+}
+//#endregion
+//#region src/drift/affected.ts
+const execFileP = promisify(execFile);
+/**
+* GITHUB_BASE_REF holds a bare branch name (e.g. "main"); the local checkout
+* only has it as a remote-tracking ref, so prefix `origin/` unless already
+* qualified. Shared by `ccqa drift`'s resolveBaseRef and `ccqa run`'s
+* resolveAnalysisBase so the rule can't drift between them.
+*/
+function normalizeGithubBaseRef(ref) {
+	return ref.startsWith("origin/") ? ref : `origin/${ref}`;
+}
+/**
+* Resolve the base ref to diff against for `ccqa drift --changed`.
+* Precedence: explicit override > GITHUB_BASE_REF > origin/main.
+*
+* Note: this is the `ccqa drift` rule. `ccqa run` resolves its baseline via
+* `src/run/git-context.ts` instead, which has no origin/main fallback — see
+* the rationale there.
+*/
+function resolveBaseRef(explicit) {
+	if (explicit && explicit.length > 0) return explicit;
+	const ghBase = process.env["GITHUB_BASE_REF"];
+	if (ghBase && ghBase.length > 0) return normalizeGithubBaseRef(ghBase);
+	return "origin/main";
+}
+/**
+* Run `git diff --name-status base...HEAD` from `cwd` and return one entry per
+* changed file. Renames are reported under their NEW path with status
+* "renamed" — the OLD path is dropped because the spec mapping is against the
+* post-rename layout.
+*
+* Paths are re-rooted to be relative to `cwd`, not the git repo root. In a
+* monorepo where `cwd` is a sub-package (e.g. `apps/foo`), git emits paths
+* relative to the repo root, but specs declare relatedPaths relative to
+* their own package. Changes outside `cwd` are kept under their repo-root
+* path and flagged `outsideCwd` — they only scope a spec in when the spec
+* explicitly declares a repo-root-relative glob, so an unrelated PR can
+* never accidentally match the app-relative globs.
+*/
+async function getChangedFiles(base, cwd) {
+	const [{ stdout: rootOut }, { stdout: diffOut }] = await Promise.all([execFileP("git", ["rev-parse", "--show-toplevel"], { cwd }), execFileP("git", [
+		"diff",
+		"--name-status",
+		"-M",
+		`${base}...HEAD`
+	], {
+		cwd,
+		maxBuffer: 32 * 1024 * 1024
+	})]);
+	return rerootChangedFiles(parseGitDiffOutput(diffOut), rootOut.trim(), cwd);
+}
+/**
+* Convert paths in `entries` from git-repo-root relative to `cwd` relative.
+* Entries outside `cwd` keep their repo-root path and are flagged
+* `outsideCwd`. Exported for unit tests.
+*/
+function rerootChangedFiles(entries, repoRoot, cwd) {
+	const prefix = relative(repoRoot, cwd);
+	if (!prefix) return entries;
+	const out = [];
+	for (const e of entries) {
+		const rel = relative(prefix, e.path);
+		if (rel.startsWith("..") || rel === "") out.push({
+			...e,
+			outsideCwd: true
+		});
+		else out.push({
+			...e,
+			path: rel
+		});
+	}
+	return out;
+}
+function parseGitDiffOutput(stdout) {
+	const out = [];
+	for (const line of stdout.split("\n")) {
+		if (!line.trim()) continue;
+		const parts = line.split("	");
+		const code = parts[0];
+		if (!code) continue;
+		if (code.startsWith("R")) {
+			const newPath = parts[2];
+			if (newPath) out.push({
+				path: newPath,
+				status: "renamed"
+			});
+			continue;
+		}
+		if (code.startsWith("C")) {
+			const newPath = parts[2];
+			if (newPath) out.push({
+				path: newPath,
+				status: "added"
+			});
+			continue;
+		}
+		const path = parts[1];
+		if (!path) continue;
+		switch (code[0]) {
+			case "A":
+				out.push({
+					path,
+					status: "added"
+				});
+				break;
+			case "M":
+			case "T":
+				out.push({
+					path,
+					status: "modified"
+				});
+				break;
+			case "D":
+				out.push({
+					path,
+					status: "deleted"
+				});
+				break;
+			default: out.push({
+				path,
+				status: "modified"
+			});
+		}
+	}
+	return out;
+}
+/** Normalize a leading `./` away so diff paths and relatedPaths globs compare. */
+function stripLeadingDotSlash(s) {
+	return s.startsWith("./") ? s.slice(2) : s;
+}
+const REGEX_CACHE = /* @__PURE__ */ new Map();
+/** Compiles `pattern` to a RegExp, memoized so repeated `--changed` matches don't re-build. */
+function compileGlob(pattern) {
+	const cached = REGEX_CACHE.get(pattern);
+	if (cached) return cached;
+	const compiled = globToRegExp(stripLeadingDotSlash(pattern));
+	REGEX_CACHE.set(pattern, compiled);
+	return compiled;
+}
+function globToRegExp(pattern) {
+	let re = "^";
+	let i = 0;
+	while (i < pattern.length) {
+		const ch = pattern[i];
+		if (ch === "?") {
+			re += "[^/]";
+			i++;
+			continue;
+		}
+		if (ch !== "*") {
+			re += /[.+^${}()|[\]\\]/.test(ch) ? "\\" + ch : ch;
+			i++;
+			continue;
+		}
+		if (pattern[i + 1] !== "*") {
+			re += "[^/]*";
+			i++;
+			continue;
+		}
+		const hasLeadingSlash = re.endsWith("/");
+		const hasTrailingSlash = pattern[i + 2] === "/";
+		if (hasLeadingSlash) re = re.slice(0, -1);
+		if (hasLeadingSlash || hasTrailingSlash) re += "(?:/?.*)?";
+		else re += ".*";
+		i += hasTrailingSlash ? 3 : 2;
+	}
+	return new RegExp(re + "$");
+}
 /**
-* Manual, lenient normalisation (mirrors diagnose's normaliseResult): a
-* missing/extra field should degrade gracefully, not reject the whole
-* prediction — only an unrecognisable label makes the candidate unusable.
+* Returns true if `changedPath` is covered by any of `relatedPaths`. An empty
+* `relatedPaths` returns false — callers handle the "unscoped spec" case
+* separately (treat the spec as always-affected) before calling this.
 */
-function normaliseFailureAnalysis(parsed) {
-	if (!isObject(parsed)) return null;
-	const label = parsed["label"];
-	if (typeof label !== "string" || !LABELS.has(label)) return null;
-	const confidence = typeof parsed["confidence"] === "number" ? clamp(parsed["confidence"], 0, 1) : 0;
-	const reasoning = typeof parsed["reasoning"] === "string" ? parsed["reasoning"] : "";
-	const headline = typeof parsed["headline"] === "string" ? parsed["headline"] : "";
-	const recommendation = typeof parsed["recommendation"] === "string" ? parsed["recommendation"] : "";
-	const rawSub = parsed["subDiagnosis"];
-	const subDiagnosis = typeof rawSub === "string" && SUB_SET.has(rawSub) ? rawSub : "NONE";
-	const evidence = [];
-	if (Array.isArray(parsed["evidence"])) for (const item of parsed["evidence"]) {
-		if (!isObject(item)) continue;
-		const detail = typeof item["detail"] === "string" ? item["detail"] : null;
-		if (detail === null) continue;
-		const file = typeof item["file"] === "string" ? item["file"] : void 0;
-		evidence.push(file !== void 0 ? {
-			file,
-			detail
-		} : { detail });
-		if (evidence.length >= 3) break;
-	}
-	return {
-		label,
-		confidence,
-		subDiagnosis,
-		headline,
-		recommendation,
-		evidence,
-		reasoning
-	};
+function isPathAffectedBy(changedPath, relatedPaths) {
+	const stripped = stripLeadingDotSlash(changedPath);
+	for (const pattern of relatedPaths) if (compileGlob(pattern).test(stripped)) return true;
+	return false;
 }
 /**
 * Capture the PR diff used as context for failure analysis. `--relative`
@@ -3563,6 +3700,249 @@ function scopePatchForSpec(patch, relatedPaths, caps = {}) {
 	return parts.join("\n");
 }
 //#endregion
+//#region src/run/diff-provider.ts
+/**
+* Cap on one on-demand file-diff response. Larger than the inline seed's
+* per-file cap (the model explicitly asked for this file), but still bounded
+* so a generated-file hunk can't blow the context — the truncation note
+* points at Read for the file's full current state.
+*/
+const FILE_DIFF_RESPONSE_CAP = 16 * 1024;
+/** Find `path`'s section in a split patch and cap it. Exported for tests. */
+function lookupFileDiff(sections, path) {
+	const normalized = stripLeadingDotSlash(path);
+	const section = sections.find((s) => s.path === normalized);
+	if (!section) return null;
+	if (section.body.length <= 16384) return section.body;
+	return `${section.body.slice(0, FILE_DIFF_RESPONSE_CAP)}\n[truncated: ${section.body.length - FILE_DIFF_RESPONSE_CAP} more chars — Read the file for its full current state]`;
+}
+function createDiffProvider(args) {
+	const { resolveBase, cwd } = args;
+	const captures = /* @__PURE__ */ new Map();
+	let relatedPathsIndex = null;
+	function capture(sha) {
+		const cached = captures.get(sha);
+		if (cached) return cached;
+		const pending = (async () => {
+			const result = await capturePrDiff(sha, cwd);
+			if (!result.ok) return {
+				sections: null,
+				nameStatus: null,
+				error: result.error
+			};
+			const { patch, nameStatus } = result.diff;
+			return {
+				sections: patch.length > 0 ? splitPatchByFile(patch) : [],
+				nameStatus,
+				error: null
+			};
+		})();
+		captures.set(sha, pending);
+		return pending;
+	}
+	/** relatedPaths for every spec, read once from the feature tree. */
+	function relatedPaths() {
+		relatedPathsIndex ??= listFeatureTree(cwd).then((tree) => new Map(tree.flatMap((f) => f.specs.map((s) => [specKey({
+			featureName: f.featureName,
+			specName: s.specName
+		}), s.relatedPaths ?? null]))));
+		return relatedPathsIndex;
+	}
+	return { async forSpec(spec) {
+		const resolved = await resolveBase(spec);
+		if (!resolved.ok) return resolved;
+		const [captured, index] = await Promise.all([capture(resolved.base.sha), relatedPaths()]);
+		const scope = index.get(specKey(spec)) ?? null;
+		const sections = captured.sections;
+		return {
+			ok: true,
+			base: resolved.base,
+			patch: sections ? scopePatchForSpec(sections, scope) : null,
+			nameStatus: captured.nameStatus,
+			error: captured.error,
+			fileDiff: (path) => sections ? lookupFileDiff(sections, path) : null
+		};
+	} };
+}
+//#endregion
+//#region src/run/errors.ts
+/**
+* Usage error (bad flag combination, broken profile, failed `git diff`, …)
+* thrown by the `run` pipeline and the helpers it calls, e.g.
+* `collectChangedSpecs`. `executeRun` never calls `process.exit`, so each
+* host maps this itself: the CLI action catches it and exits with
+* `exitCode`; the hub runner records it as a run-level error.
+*/
+var RunUsageError = class extends Error {
+	exitCode = 2;
+	constructor(message) {
+		super(message);
+		this.name = "RunUsageError";
+	}
+};
+//#endregion
+//#region src/run/git-context.ts
+/** The `--failure-analysis` value that selects per-spec hub-ledger baselines. */
+const LAST_GREEN = "last-green";
+/** Resolve `ref` to a full commit sha, or null when it does not exist locally. */
+async function resolveCommitSha(ref, cwd) {
+	try {
+		const { stdout } = await execFileP("git", [
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`${ref}^{commit}`
+		], { cwd });
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Resolve a `[base]` flag value (from `--failure-analysis [base]` or
+* `--changed [base]`) to a verified baseline, failing fast — before any spec
+* runs — when it cannot be resolved.
+*
+*   - a string value is an explicit ref;
+*   - bare `true` derives the ref from GITHUB_BASE_REF (pull_request events)
+*     and errors outside that context;
+*   - the ref must resolve to a local commit, so a shallow CI checkout that
+*     never fetched the base surfaces here as an actionable error instead of
+*     an empty diff downstream.
+*
+* `flagName` only shapes the error messages.
+*/
+async function resolveAnalysisBase(flagValue, flagName, cwd) {
+	let ref;
+	let source;
+	if (flagValue === "last-green") throw new RunUsageError(`${flagName}=${LAST_GREEN} is not supported — last-green baselines are per-spec and only apply to --failure-analysis`);
+	if (typeof flagValue === "string") {
+		ref = flagValue;
+		source = "explicit";
+	} else {
+		const ghBase = process.env["GITHUB_BASE_REF"];
+		if (!ghBase) throw new RunUsageError(`${flagName} without a base needs GITHUB_BASE_REF (a pull_request workflow); outside that context pass the base explicitly, e.g. ${flagName}=origin/main`);
+		ref = normalizeGithubBaseRef(ghBase);
+		source = "github-base-ref";
+	}
+	const sha = await resolveCommitSha(ref, cwd);
+	if (sha === null) throw new RunUsageError(`${flagName}: '${ref}' is not a resolvable git ref in this checkout. If this is CI, the base may not be fetched (try fetch-depth: 0). If '${ref}' was meant as a spec target, put spec targets before flags or use ${flagName}=<ref>.`);
+	return {
+		ref,
+		sha,
+		source
+	};
+}
+//#endregion
+//#region src/cli/git-branch.ts
+/** Best-effort current branch: CI env vars first, then git, else null. */
+async function detectBranch(cwd) {
+	const fromEnv = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+	if (fromEnv) return fromEnv;
+	try {
+		const { stdout } = await execFileP("git", [
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		], { cwd });
+		const branch = stdout.trim();
+		return branch && branch !== "HEAD" ? branch : null;
+	} catch {
+		return null;
+	}
+}
+/** Best-effort current commit SHA, or null (e.g. not a git repo). */
+async function getGitHead(cwd) {
+	try {
+		const { stdout } = await execFileP("git", ["rev-parse", "HEAD"], { cwd });
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/run/last-green.ts
+/**
+* The repo's default branch name (e.g. "main"), from origin's HEAD ref.
+* Falls back to "main" when origin isn't configured — the lookup then just
+* queries a possibly-empty ledger bucket, which is harmless.
+*/
+async function detectDefaultBranch(cwd) {
+	try {
+		const { stdout } = await execFileP("git", [
+			"symbolic-ref",
+			"--short",
+			"refs/remotes/origin/HEAD"
+		], { cwd });
+		const ref = stdout.trim();
+		return ref.startsWith("origin/") ? ref.slice(7) : ref || "main";
+	} catch {
+		return "main";
+	}
+}
+/**
+* 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
+* hub-backed baselines, so a broken hub connection is a usage error, never a
+* silent no-baseline run.
+*/
+async function fetchLastGreenLedger(hubCtx, profile, cwd) {
+	const [fallbackBranch, detectedBranch] = await Promise.all([detectDefaultBranch(cwd), detectBranch(cwd)]);
+	const branch = detectedBranch ?? fallbackBranch;
+	let entries;
+	try {
+		entries = await hubCtx.hub.getLastGreen(hubCtx.project, {
+			branch,
+			fallbackBranch,
+			...profile ? { profile } : {}
+		});
+	} catch (err) {
+		throw new RunUsageError(`--failure-analysis=${LAST_GREEN}: could not fetch the last-green ledger from the hub: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const n = Object.keys(entries).length;
+	const scope = branch === fallbackBranch ? branch : `${branch} → ${fallbackBranch}`;
+	meta("analysis-base", `${LAST_GREEN} (${n} spec baseline${n === 1 ? "" : "s"}, branch ${scope})`);
+	return entries;
+}
+/**
+* Per-spec baseline resolver for `--failure-analysis=last-green`. 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
+* recorded in its report row. Sha existence checks are memoized per commit.
+*/
+function createLastGreenResolver(entries, cwd) {
+	const shaChecks = /* @__PURE__ */ new Map();
+	const checkSha = (sha) => {
+		const cached = shaChecks.get(sha);
+		if (cached) return cached;
+		const pending = resolveCommitSha(sha, cwd);
+		shaChecks.set(sha, pending);
+		return pending;
+	};
+	return async (spec) => {
+		const entry = entries[specKey(spec)];
+		if (!entry) return {
+			ok: false,
+			skip: "no last-green baseline for this spec on the hub yet (recorded once the spec passes on a pushed run)"
+		};
+		const sha = await checkSha(entry.gitHead);
+		if (!sha) return {
+			ok: false,
+			skip: `last-green commit ${entry.gitHead.slice(0, 12)} is not in this checkout (shallow clone? try fetch-depth: 0)`
+		};
+		return {
+			ok: true,
+			base: {
+				ref: LAST_GREEN,
+				sha,
+				source: "last-green"
+			}
+		};
+	};
+}
+//#endregion
 //#region src/report/github-format.ts
 /**
 * Build GitHub Actions `::error::` annotation lines for every failed spec in
@@ -4520,33 +4900,6 @@ function resolvePromptLocalPath(name, cwd) {
 	return join(cwd ?? process.cwd(), PROMPT_LOCAL_PATHS[name]);
 }
 //#endregion
-//#region src/cli/git-branch.ts
-/** Best-effort current branch: CI env vars first, then git, else null. */
-async function detectBranch(cwd) {
-	const fromEnv = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
-	if (fromEnv) return fromEnv;
-	try {
-		const { stdout } = await execFileP("git", [
-			"rev-parse",
-			"--abbrev-ref",
-			"HEAD"
-		], { cwd });
-		const branch = stdout.trim();
-		return branch && branch !== "HEAD" ? branch : null;
-	} catch {
-		return null;
-	}
-}
-/** Best-effort current commit SHA, or null (e.g. not a git repo). */
-async function getGitHead(cwd) {
-	try {
-		const { stdout } = await execFileP("git", ["rev-parse", "HEAD"], { cwd });
-		return stdout.trim() || null;
-	} catch {
-		return null;
-	}
-}
-//#endregion
 //#region src/cli/hub.ts
 /**
 * `ccqa hub` — the client side of the ccqa hub (a results/secret control
@@ -5101,6 +5454,7 @@ async function runLiveExecutor(input) {
 		const transcriptParts = [];
 		const commandParts = [];
 		let isError = false;
+		let errorDetail = null;
 		let cost = emptyStepCost();
 		try {
 			const result = await invokeClaudeStreaming({
@@ -5120,6 +5474,7 @@ async function runLiveExecutor(input) {
 				}
 			});
 			isError = result.isError;
+			errorDetail = result.errorDetail;
 			cost = {
 				totalCostUsd: result.cost.totalCostUsd,
 				durationApiMs: result.cost.durationApiMs,
@@ -5132,7 +5487,8 @@ async function runLiveExecutor(input) {
 			};
 		} catch (err) {
 			isError = true;
-			transcriptParts.push(`[ccqa] invokeClaudeStreaming threw: ${err instanceof Error ? err.message : String(err)}`);
+			errorDetail = err instanceof Error ? err.message : String(err);
+			transcriptParts.push(`[ccqa] invokeClaudeStreaming threw: ${errorDetail}`);
 		}
 		const transcript = transcriptParts.join("\n");
 		const after = takeScreenshot(input.sessionName, paths.afterPng, { fullPage: true });
@@ -5141,6 +5497,7 @@ async function runLiveExecutor(input) {
 		const { status, reasoning } = judgeStepOutcome({
 			step,
 			isError,
+			errorDetail,
 			judged: findLastStepResult(transcript)
 		});
 		return {
@@ -5219,11 +5576,14 @@ function sumStepCosts(steps) {
 * Kept as a pure helper so the executor loop stays readable and the
 * branches are individually testable.
 */
-function judgeStepOutcome({ step, isError, judged }) {
-	if (isError) return {
-		status: "failed",
-		reasoning: judged?.reasoning ? `agent error; last reasoning: ${judged.reasoning}` : "Claude invocation returned an error"
-	};
+function judgeStepOutcome({ step, isError, errorDetail, judged }) {
+	if (isError) {
+		const detail = errorDetail ? `: ${errorDetail}` : "";
+		return {
+			status: "failed",
+			reasoning: judged?.reasoning ? `agent error${detail}; last reasoning: ${judged.reasoning}` : `Claude invocation returned an error${detail}`
+		};
+	}
 	if (!judged) return {
 		status: "failed",
 		reasoning: "STEP_RESULT missing"
@@ -5469,22 +5829,14 @@ async function runLiveSpecs(specs, opts) {
 	const userPromptBundle = await loadPromptBundleFromHub(opts.hubContext ?? null, "live");
 	if (userPromptBundle !== null) meta("prompt", userPromptBundle.loaded.join(" + "));
 	const userPromptSuffix = userPromptBundle?.text ?? null;
-	const failureAnalysisEnabled = opts.failureAnalysis !== false;
+	const diffProvider = opts.diffProvider ?? null;
+	const failureAnalysisEnabled = diffProvider != null;
 	const driftAuditEnabled = failureAnalysisEnabled && opts.driftAudit !== false;
 	const auth = failureAnalysisEnabled ? driftAuthAvailable() : {
 		ok: false,
 		reason: "disabled"
 	};
 	if (failureAnalysisEnabled && !auth.ok) info(`failure analysis skipped (${auth.reason})`);
-	const baseRef = resolveBaseRef(opts.base);
-	let diff = {
-		ok: false,
-		error: "diff not captured"
-	};
-	if (failureAnalysisEnabled && auth.ok) {
-		diff = await capturePrDiff(baseRef, cwd);
-		if (!diff.ok) info(`failure analysis: source diff unavailable (${diff.error}) — analyzing without diff context`);
-	}
 	const reportDir = opts.reportDir ?? ".";
 	const concurrency = Math.max(1, opts.concurrency ?? 1);
 	const built = await runPool(specs, concurrency, (spec, i) => {
@@ -5506,10 +5858,8 @@ async function runLiveSpecs(specs, opts) {
 			};
 			const row = await buildLiveReportRow(outcome, {
 				auth,
-				diff,
-				baseRef,
+				diffProvider,
 				reportDir,
-				failureAnalysisEnabled,
 				driftAuditEnabled
 			}, opts, cwd);
 			await opts.report?.upsert(row);
@@ -5545,26 +5895,29 @@ async function buildLiveReportRow(r, ctx, opts, cwd) {
 		reportDir: ctx.reportDir
 	});
 	const driftForSpec = ctx.driftAuditEnabled && r.result.status === "failed" ? await runDriftAuditOne(r, opts, cwd) : null;
-	const analysis = ctx.failureAnalysisEnabled && r.result.status === "failed" ? await analyzeOneLiveFailure(r, ctx.diff, ctx.baseRef, driftForSpec, ctx.auth, opts, cwd) : void 0;
+	const analysis = ctx.diffProvider && r.result.status === "failed" ? await analyzeOneLiveFailure(r, ctx.diffProvider, driftForSpec, ctx.auth, opts, cwd) : void 0;
 	return {
 		...base,
 		driftIssues: driftForSpec,
-		...analysisFieldsFor(analysis, r.result.status, ctx.failureAnalysisEnabled)
+		...analysisFieldsFor(analysis, r.result.status)
 	};
 }
 /**
 * Merge analysis-related fields into the report row. The unattempted-failure
 * branch exists so the report distinguishes "we tried and gave up" (auth /
-* spec.yaml missing) from "we deliberately did not run the classifier".
+* spec.yaml missing) from "we deliberately did not run the classifier" —
+* `a` is undefined for a failed spec exactly when analysis was not requested
+* (no diffProvider), so no separate flag is needed.
 */
-function analysisFieldsFor(a, status, failureAnalysisEnabled) {
+function analysisFieldsFor(a, status) {
 	if (a) return {
 		analysis: a.analysis,
 		analysisSkipped: a.analysisSkipped,
 		failureLogExcerpt: a.failureLogExcerpt,
-		diffExcerpt: a.diffExcerpt
+		diffExcerpt: a.diffExcerpt,
+		...a.analysisBase ? { analysisBase: a.analysisBase } : {}
 	};
-	if (!failureAnalysisEnabled && status === "failed") return { analysisSkipped: "skipped by --no-failure-analysis" };
+	if (status === "failed") return { analysisSkipped: "skipped: --failure-analysis not enabled" };
 	return {};
 }
 /**
@@ -5754,11 +6107,13 @@ function logBatchCost(runs) {
 /**
 * Classify one failed live run via `analyzeFailure` — same prompt as the
 * deterministic path (Issue #47), fed the live transcript instead of the
-* vitest log. `auth`, `diff`, and `baseRef` are hoisted once by the caller and
-* shared across specs. Auth-unavailable / no-failed-step degrade to
-* `analysisSkipped` rather than throwing.
+* vitest log. `auth` is hoisted once by the caller; the diff comes from the
+* shared provider, already scoped to this spec's relatedPaths and truncated
+* (the live path used to feed the whole unscoped patch — in a monorepo that
+* ballooned the prompt with unrelated changes). Auth-unavailable /
+* no-failed-step degrade to `analysisSkipped` rather than throwing.
 */
-async function analyzeOneLiveFailure(r, diff, baseRef, driftForSpec, auth, opts, cwd) {
+async function analyzeOneLiveFailure(r, diffProvider, driftForSpec, auth, opts, cwd) {
 	const key = `${r.featureName}/${r.specName}`;
 	if (!auth.ok) return {
 		analysis: null,
@@ -5774,19 +6129,31 @@ async function analyzeOneLiveFailure(r, diff, baseRef, driftForSpec, auth, opts,
 		failureLogExcerpt: null,
 		diffExcerpt: null
 	};
+	const specDiff = await diffProvider.forSpec({
+		featureName: r.featureName,
+		specName: r.specName
+	});
+	if (!specDiff.ok) return {
+		analysis: null,
+		analysisSkipped: specDiff.skip,
+		failureLogExcerpt: excerpt,
+		diffExcerpt: null
+	};
+	if (specDiff.error) info(`failure analysis: source diff unavailable (${specDiff.error}) — analyzing without diff context`);
 	const outcome = await analyzeFailure({
 		liveTranscriptExcerpt: excerpt,
 		specYaml: r.specYaml,
-		diffPatch: diff.ok ? diff.diff.patch : null,
-		changedFiles: diff.ok ? diff.diff.nameStatus : null,
-		baseRef: diff.ok ? baseRef : null,
+		diffPatch: specDiff.patch,
+		changedFiles: specDiff.nameStatus,
+		baseRef: specDiff.base.ref,
 		driftIssues: driftForSpec,
 		...opts.language ? { outputLanguage: opts.language } : {},
 		...opts.triageUserPrompt ? { triageUserPrompt: opts.triageUserPrompt } : {},
 		...opts.customPrompt ? { customPrompt: opts.customPrompt } : {}
 	}, {
 		...opts.model ? { model: opts.model } : {},
-		cwd
+		cwd,
+		getFileDiff: specDiff.fileDiff
 	});
 	const pct = Math.round(outcome.analysis.confidence * 100);
 	const headline = outcome.analysis.headline.trim() || (outcome.analysis.reasoning.split("\n")[0] ?? "").trim();
@@ -5795,7 +6162,11 @@ async function analyzeOneLiveFailure(r, diff, baseRef, driftForSpec, auth, opts,
 		analysis: outcome.analysis,
 		analysisSkipped: null,
 		failureLogExcerpt: excerpt,
-		diffExcerpt: diff.ok ? diff.diff.patch : null
+		diffExcerpt: specDiff.patch,
+		analysisBase: {
+			ref: specDiff.base.ref,
+			sha: specDiff.base.sha
+		}
 	};
 }
 function count(steps, target) {
@@ -8866,27 +9237,12 @@ function stripCodeFences(text) {
 	return m && m[1] !== void 0 ? m[1] : text;
 }
 //#endregion
-//#region src/run/errors.ts
-/**
-* Usage error (bad flag combination, broken profile, failed `git diff`, …)
-* thrown by the `run` pipeline and the helpers it calls, e.g.
-* `collectChangedSpecs`. `executeRun` never calls `process.exit`, so each
-* host maps this itself: the CLI action catches it and exits with
-* `exitCode`; the hub runner records it as a run-level error.
-*/
-var RunUsageError = class extends Error {
-	exitCode = 2;
-	constructor(message) {
-		super(message);
-		this.name = "RunUsageError";
-	}
-};
-//#endregion
 //#region src/cli/changed-specs.ts
 /**
-* Filter specs to those affected by the git diff against the resolved base
-* ref. Powers `ccqa run --changed`; mirrors `ccqa drift --changed` minus the
-* LLM new-file router (kept off here for predictable CI cost).
+* Filter specs to those affected by the git diff against the `--changed
+* [base]` baseline. Powers `ccqa run --changed`; mirrors `ccqa drift
+* --changed` minus the LLM new-file router (kept off here for predictable CI
+* cost).
 *
 * A spec is "affected" when it has no `relatedPaths` (conservatively
 * included), any changed file matches one of its `relatedPaths` globs, or it
@@ -8894,14 +9250,14 @@ var RunUsageError = class extends Error {
 */
 async function collectChangedSpecs(specs, opts) {
 	const { cwd, base } = opts;
-	const baseRef = resolveBaseRef(base);
+	const resolved = await resolveAnalysisBase(base, "--changed", cwd);
 	let changed;
 	try {
-		changed = await getChangedFiles(baseRef, cwd);
+		changed = await getChangedFiles(resolved.sha, cwd);
 	} catch (e) {
-		throw new RunUsageError(`failed to run 'git diff' against ${baseRef}: ${e.message}`);
+		throw new RunUsageError(`failed to run 'git diff' against ${resolved.ref}: ${e.message}`);
 	}
-	meta("changed-base", baseRef);
+	meta("changed-base", `${resolved.ref} (${resolved.sha.slice(0, 12)})`);
 	meta("changed-files", changed.length);
 	return filterAffectedSpecs(specs, changed, cwd);
 }
@@ -8965,6 +9321,27 @@ function dedupeSpecs(specs) {
 async function executeRun(targets, opts) {
 	if (opts.changed && targets.length > 0) throw new RunUsageError("--changed and an explicit spec target cannot be combined");
 	const cwd = opts.cwd ?? process.cwd();
+	const wantsLastGreen = opts.failureAnalysis === LAST_GREEN;
+	const [head, fixedBase] = await Promise.all([getGitHead(cwd), opts.failureAnalysis && !wantsLastGreen ? resolveAnalysisBase(opts.failureAnalysis, "--failure-analysis", cwd) : null]);
+	const git = {
+		head,
+		base: wantsLastGreen ? {
+			ref: LAST_GREEN,
+			sha: null,
+			source: "last-green"
+		} : fixedBase
+	};
+	let diffProvider = null;
+	if (fixedBase) {
+		diffProvider = createDiffProvider({
+			resolveBase: async () => ({
+				ok: true,
+				base: fixedBase
+			}),
+			cwd
+		});
+		meta("analysis-base", `${fixedBase.ref} (${fixedBase.sha.slice(0, 12)}, ${fixedBase.source})`);
+	}
 	let projectForProfile;
 	try {
 		if (opts.profile !== void 0) {
@@ -9000,7 +9377,17 @@ async function executeRun(targets, opts) {
 	} catch {
 		hubCtx = null;
 	}
-	const [customPrompt, triageUserPrompt] = await Promise.all([fetchCustomPrompt(hubCtx), fetchTriageUserPrompt(hubCtx)]);
+	if (wantsLastGreen && hubCtx == null) throw new RunUsageError(`--failure-analysis=${LAST_GREEN} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
+	const ledgerHub = wantsLastGreen ? hubCtx : null;
+	const [customPrompt, triageUserPrompt, ledgerEntries] = await Promise.all([
+		fetchCustomPrompt(hubCtx),
+		fetchTriageUserPrompt(hubCtx),
+		ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.profile, cwd) : null
+	]);
+	if (ledgerEntries) diffProvider = createDiffProvider({
+		resolveBase: createLastGreenResolver(ledgerEntries, cwd),
+		cwd
+	});
 	const triageUserPromptHash = triageUserPrompt ? hashTriageUserPrompt(triageUserPrompt) : null;
 	const enumerateAll = () => listAllSpecsWithSpecFile(cwd);
 	let specs = dedupeSpecs((await Promise.all((targets.length ? targets : [void 0]).map((t) => resolveSpecTargets(t, enumerateAll, cwd)))).flat());
@@ -9008,7 +9395,7 @@ async function executeRun(targets, opts) {
 		const before = specs.length;
 		specs = await collectChangedSpecs(specs, {
 			cwd,
-			base: opts.base
+			base: opts.changed
 		});
 		meta("changed-scoped", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
 	}
@@ -9050,6 +9437,7 @@ async function executeRun(targets, opts) {
 			project: hubCtx.project,
 			...branch ? { branch } : {},
 			...opts.profile ? { profile: opts.profile } : {},
+			...git.head ? { gitHead: git.head } : {},
 			kind: "run"
 		});
 		hubRunId = opened.id;
@@ -9070,11 +9458,7 @@ async function executeRun(targets, opts) {
 		warn(`hub: could not open incremental run (${errMessage(err)}); continuing with local report only`);
 	}
 	const incrementalReport = createIncrementalReport(reportDir, buildReportEnvelope({
-		diff: {
-			ok: false,
-			error: "diff not yet captured"
-		},
-		baseRef: null,
+		git,
 		customPromptVersion: customPrompt?.customPromptVersion ?? null,
 		triageUserPromptHash,
 		opts
@@ -9106,13 +9490,12 @@ async function executeRun(targets, opts) {
 		...opts.language ? { language: opts.language } : {},
 		...opts.out && liveSpecs.length === 1 ? { out: opts.out } : {},
 		cwd,
-		...opts.base ? { base: opts.base } : {},
 		reportDir,
 		...typeof opts.retry === "number" ? { retry: opts.retry } : {},
 		concurrency: opts.concurrency ?? 1,
 		...opts.profile ? { profile: opts.profile } : {},
 		...opts.driftAudit !== false ? { driftAudit: true } : {},
-		...opts.failureAnalysis === false ? { failureAnalysis: false } : {},
+		diffProvider,
 		hubContext: hubCtx,
 		customPrompt,
 		triageUserPrompt,
@@ -9124,7 +9507,7 @@ async function executeRun(targets, opts) {
 	if (externalRows.some((r) => r.status === "failed")) overallExitCode = 1;
 	let report;
 	{
-		const detReport = await analyzeDeterministicSummaries(det.summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt);
+		const detReport = await analyzeDeterministicSummaries(det.summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt, diffProvider);
 		report = await writeUnifiedReport({
 			reportDir,
 			results: [
@@ -9132,8 +9515,7 @@ async function executeRun(targets, opts) {
 				...externalRows,
 				...live.reportResults
 			],
-			diff: detReport.diff,
-			baseRef: detReport.baseRef,
+			git,
 			customPromptVersion: detReport.customPromptVersion,
 			triageUserPromptHash,
 			opts
@@ -9142,8 +9524,7 @@ async function executeRun(targets, opts) {
 		if (hubRunId) {
 			const finalStatus = overallExitCode === 0 ? "passed" : "failed";
 			const reportMeta = buildReportEnvelope({
-				diff: detReport.diff,
-				baseRef: detReport.baseRef,
+				git,
 				customPromptVersion: detReport.customPromptVersion,
 				triageUserPromptHash,
 				opts
@@ -9341,24 +9722,15 @@ function failedSpec(s) {
 * failure analysis when `--report` is on; degrades (no throw) when Claude
 * auth or git diff aren't available. Caller writes the HTML / JSON.
 */
-async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt) {
-	const failureAnalysisEnabled = opts.failureAnalysis !== false;
+async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, customPrompt, triageUserPrompt, diffProvider) {
+	const failureAnalysisEnabled = diffProvider != null;
 	const driftAuditEnabled = failureAnalysisEnabled && opts.driftAudit !== false;
-	const auth = failureAnalysisEnabled || driftAuditEnabled ? driftAuthAvailable() : {
+	const auth = failureAnalysisEnabled ? driftAuthAvailable() : {
 		ok: false,
 		reason: "skipped by flags"
 	};
 	const failed = summaries.filter(failedSpec);
 	if (failureAnalysisEnabled && !auth.ok && failed.length > 0) info(`failure analysis skipped (${auth.reason})`);
-	const baseRef = resolveBaseRef(opts.base);
-	let diff = {
-		ok: false,
-		error: "diff not captured (no failures)"
-	};
-	if (failed.length > 0) {
-		diff = await capturePrDiff(baseRef, cwd);
-		if (!diff.ok) info(`drift-report: source diff unavailable (${diff.error}) — analyzing without diff context`);
-	}
 	const tree = failed.length > 0 ? await listFeatureTree(cwd) : [];
 	const specInfoByKey = new Map(tree.flatMap((f) => f.specs.map((sp) => [`${f.featureName}/${sp.specName}`, sp])));
 	const findSpecInfo = (s) => specInfoByKey.get(`${s.featureName}/${s.specName}`) ?? null;
@@ -9385,9 +9757,9 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 			onSpecStart: (t) => info(`drift audit: ${t.featureName}/${t.specName}`)
 		});
 	}
-	const patchSections = diff.ok && diff.diff.patch.length > 0 ? splitPatchByFile(diff.diff.patch) : null;
 	const allBlocks = await loadAllBlocks(cwd);
 	let printedHeader = false;
+	let warnedDiffUnavailable = false;
 	const results = [];
 	for (const s of summaries) {
 		const assertions = collectAssertions(s);
@@ -9422,14 +9794,23 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 			});
 			continue;
 		}
-		const relatedPaths = findSpecInfo(s)?.relatedPaths ?? null;
-		const diffExcerpt = patchSections ? scopePatchForSpec(patchSections, relatedPaths) : null;
+		const specDiffResult = diffProvider ? await diffProvider.forSpec({
+			featureName: s.featureName,
+			specName: s.specName
+		}) : null;
+		const specDiff = specDiffResult?.ok ? specDiffResult : null;
+		if (specDiff?.error && !warnedDiffUnavailable) {
+			warnedDiffUnavailable = true;
+			info(`failure analysis: source diff unavailable (${specDiff.error}) — analyzing without diff context`);
+		}
+		const diffExcerpt = specDiff?.patch ?? null;
 		const driftResult = driftResults.find((r) => r.target.featureName === s.featureName && r.target.specName === s.specName);
 		const driftIssues = driftResult?.ok ? driftResult.issues : null;
 		const failureLog = buildFailureLog(s);
 		let analysis = null;
 		let analysisSkipped = null;
-		if (!failureAnalysisEnabled) analysisSkipped = "skipped by --no-failure-analysis";
+		if (!specDiffResult) analysisSkipped = "skipped: --failure-analysis not enabled";
+		else if (!specDiffResult.ok) analysisSkipped = specDiffResult.skip;
 		else if (!auth.ok) analysisSkipped = auth.reason;
 		else if (specYaml === null) analysisSkipped = "no spec.yaml found for this spec";
 		else {
@@ -9440,15 +9821,16 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 				specYaml,
 				failureLog,
 				diffPatch: diffExcerpt,
-				changedFiles: diff.ok ? diff.diff.nameStatus : null,
-				baseRef: diff.ok ? baseRef : null,
+				changedFiles: specDiffResult.nameStatus,
+				baseRef: specDiffResult.base.ref,
 				driftIssues,
 				...opts.language ? { outputLanguage: opts.language } : {},
 				...triageUserPrompt ? { triageUserPrompt } : {},
 				...customPrompt ? { customPrompt } : {}
 			}, {
 				...opts.model ? { model: opts.model } : {},
-				cwd
+				cwd,
+				getFileDiff: specDiffResult.fileDiff
 			});
 			analysis = outcome.analysis;
 			if (!printedHeader) {
@@ -9466,6 +9848,10 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 			status: "failed",
 			analysis,
 			analysisSkipped,
+			...specDiff ? { analysisBase: {
+				ref: specDiff.base.ref,
+				sha: specDiff.base.sha
+			} } : {},
 			driftIssues,
 			failureLogExcerpt: failureLog.length > 0 ? failureLog : null,
 			diffExcerpt,
@@ -9475,8 +9861,6 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 	}
 	return {
 		results,
-		diff,
-		baseRef,
 		customPromptVersion: customPrompt?.customPromptVersion ?? null
 	};
 }
@@ -9488,30 +9872,33 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir, cu
 * final report.json stays byte-identical (existing e2e goldens compare it).
 */
 function buildReportEnvelope(args) {
-	const { diff, baseRef, customPromptVersion, triageUserPromptHash, opts } = args;
+	const { git, customPromptVersion, triageUserPromptHash, opts } = args;
 	return {
 		schemaVersion: 1,
 		kind: "run",
 		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 		runId: process.env["GITHUB_RUN_ID"] ?? null,
 		git: {
-			head: diff.ok ? diff.diff.head : null,
-			base: diff.ok ? baseRef : null
+			head: git.head,
+			base: git.base?.ref ?? null,
+			...git.base ? {
+				baseSha: git.base.sha,
+				baseSource: git.base.source
+			} : {}
 		},
 		model: opts.model ?? null,
 		language: opts.language ?? null,
-		promptVersion: "4",
+		promptVersion: "5",
 		customPromptVersion,
 		...triageUserPromptHash !== null ? { triageUserPromptHash } : {}
 	};
 }
 /** Write the unified JSON (+ optional GitHub-annotation) report for one run. Returns the report data. */
 async function writeUnifiedReport(args) {
-	const { reportDir, results, diff, baseRef, customPromptVersion, triageUserPromptHash, opts } = args;
+	const { reportDir, results, git, customPromptVersion, triageUserPromptHash, opts } = args;
 	const data = {
 		...buildReportEnvelope({
-			diff,
-			baseRef,
+			git,
 			customPromptVersion,
 			triageUserPromptHash,
 			opts
@@ -9825,7 +10212,7 @@ 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. Each spec's execution mode comes from its spec.yaml `mode:` field (default deterministic; set `mode: live` to have Claude drive agent-browser live per step). Deterministic specs replay the recorded test.spec.ts under vitest. A structured report (report.json + evidence) is always written; use --push-report to also stream it to a hub.").option("--report [dir]", `Directory for the structured run results (report.json + evidence PNGs) that are always written. Default: ${DEFAULT_REPORT_DIR}/. Pass this only to change the location.`).option("--push-report", "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.").option("--changed", "Restrict execution to specs whose relatedPaths intersect the git diff against --base (or, in CI, $GITHUB_BASE_REF, else origin/main). Cannot be combined with an explicit spec id.").option("--no-failure-analysis", "Skip the per-failure root-cause classification (TEST_DRIFT / SPEC_CHANGE / PRODUCT_BUG). --report only.").option("--no-drift-audit", "Skip the spec↔code drift audit shown in the report. --report only.").option("--base <ref>", "Base ref the source diff is taken against for failure analysis (default: GITHUB_BASE_REF, then origin/main).").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--format <fmt>", "Additional output format alongside HTML when --report is set: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (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. Each spec's execution mode comes from its spec.yaml `mode:` field (default deterministic; set `mode: live` to have Claude drive agent-browser live per step). Deterministic specs replay the recorded test.spec.ts under vitest. A structured report (report.json + evidence) is always written; use --push-report to also stream it to a hub.").option("--report [dir]", `Directory for the structured run results (report.json + evidence PNGs) that are always written. Default: ${DEFAULT_REPORT_DIR}/. Pass this only to change the location.`).option("--push-report", "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.").option("--changed [base]", "Restrict execution to specs whose relatedPaths intersect the git diff against [base]. Without a value the base comes from $GITHUB_BASE_REF (pull_request CI); elsewhere pass it explicitly (e.g. --changed=origin/main). Cannot be combined with an explicit spec id.").option("--failure-analysis [base]", "Classify each failure (TEST_DRIFT / SPEC_CHANGE / PRODUCT_BUG) against the source diff since [base]. Without a value the base comes from $GITHUB_BASE_REF (pull_request CI); elsewhere pass it explicitly (e.g. --failure-analysis=origin/main), or pass 'last-green' to diff each spec against the commit where it last passed (per-spec baselines from the hub; requires a hub connection). Off by default — no Claude calls without it.").option("--no-drift-audit", "With --failure-analysis: skip the spec↔code drift audit shown in the report.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--format <fmt>", "Additional output format alongside HTML when --report is set: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
 	if (REPORT_FORMATS.includes(raw)) return raw;
 	throw new Error(`--format must be one of ${REPORT_FORMATS.join(" | ")}`);
 }, "text").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--no-evidence", `(deterministic only) Skip step-boundary evidence capture (PNG + meta JSON written to ${DEFAULT_REPORT_DIR}/${EVIDENCE_SUBDIR}/ by default).`).option("--retry <n>", "(live only) Retry each failed step up to N more times before recording failure. Default 0.", (raw) => {
@@ -13319,6 +13706,11 @@ z.object({ error: z.object({
 	code: z.string(),
 	message: z.string()
 }) });
+z.object({
+	gitHead: z.string(),
+	runId: z.string(),
+	at: z.string()
+});
 /**
 * A triage-learning job. Grading failing specs in the hub UI produces the
 * "actual cause" labels this reads; the job turns them into an improved
@@ -13434,6 +13826,7 @@ function createPushRunHandler(config) {
 			};
 			await config.storage.artifacts.putDir(run.id, dir);
 			await config.storage.runs.create(run);
+			await updateLastGreenLedger(config.storage, run, report.results);
 			sendJson(ctx.res, 201, run);
 		} finally {
 			await rm(dir, {
@@ -13444,14 +13837,17 @@ function createPushRunHandler(config) {
 	};
 }
 /**
-* POST /api/v1/runs/open?project=&branch=&profile=&kind= — start a "running"
-* run with no report yet. Unlike `POST /runs`, nothing is pushed up front:
-* the caller patches results in as they finish (`PATCH /runs/:id`), so an
-* interrupted run still leaves a partial report on the hub instead of none.
+* POST /api/v1/runs/open?project=&branch=&profile=&kind=&gitHead= — start a
+* "running" run with no report yet. Unlike `POST /runs`, nothing is pushed up
+* front: the caller patches results in as they finish (`PATCH /runs/:id`), so
+* an interrupted run still leaves a partial report on the hub instead of
+* none. `gitHead` (optional) attributes the run to a commit from the start —
+* without it an interrupted run would never learn its commit.
 */
 function createOpenRunHandler(config) {
 	return async (ctx) => {
 		const { project, branch, profile, kind } = parseRunScope(ctx);
+		const gitHead = ctx.url.searchParams.get("gitHead");
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		const run = {
 			id: randomUUID(),
@@ -13466,7 +13862,7 @@ function createOpenRunHandler(config) {
 				passed: 0,
 				failed: 0
 			},
-			gitHead: null,
+			gitHead: gitHead || null,
 			promptVersion: "",
 			ciRunId: null,
 			reportCreatedAt: now,
@@ -13482,10 +13878,7 @@ const PatchRunRequestSchema = z.object({
 	done: z.boolean().optional(),
 	finalStatus: z.enum(["passed", "failed"]).optional(),
 	reportMeta: z.object({
-		git: z.object({
-			head: z.string().nullable(),
-			base: z.string().nullable()
-		}).partial().optional(),
+		git: GitEnvelopeSchema.partial().optional(),
 		model: z.string().nullable().optional(),
 		language: z.string().nullable().optional(),
 		promptVersion: z.string().optional(),
@@ -13509,6 +13902,38 @@ function countSpecs(results) {
 	};
 }
 /**
+* Advance the last-green ledger for every passed spec of a terminal
+* `kind: "run"` run. Spec-level, not run-level: a run with one chronically
+* failing spec still moves the baseline of every spec that did pass.
+* Best-effort — a ledger failure must not fail the push; the ledger is an
+* accelerator for `--failure-analysis=last-green`, not part of the run
+* record. Runs without a branch or gitHead can't be placed in the ledger and
+* are skipped.
+*
+* Ordering caveat (known approximation): `at` is the run's reportCreatedAt —
+* open time for incremental runs, report time for immutable pushes. When two
+* runs on the same branch+profile overlap, "newest at wins" can pick either
+* of the two genuinely-green commits, since the hub has no git ancestry to
+* order them properly. Accepted: CI serializes per branch in practice, and a
+* baseline can only ever point at a commit where the spec really passed.
+*/
+async function updateLastGreenLedger(storage, run, results) {
+	const { gitHead, branch } = run;
+	if (run.kind !== "run" || !gitHead || !branch) return;
+	const passed = results.filter((r) => r.status === "passed");
+	if (passed.length === 0) return;
+	const entries = Object.fromEntries(passed.map((r) => [`${r.feature}/${r.spec}`, {
+		gitHead,
+		runId: run.id,
+		at: run.reportCreatedAt
+	}]));
+	try {
+		await storage.lastGreen.merge(run.project, run.profile ?? "default", branch, entries);
+	} catch (err) {
+		console.error(`hub: last-green ledger update failed for run "${run.id}": ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
 * PATCH /api/v1/runs/:id — incrementally add spec results (and evidence) to a
 * "running" run. Once the run is terminal (`done: true` was sent, or it was
 * pushed immutably via `POST /runs`), further patches are rejected with 409.
@@ -13530,6 +13955,7 @@ function createPatchRunHandler(config) {
 		if (!parsed.success) throw new HttpError(400, "invalid_body", `request body is invalid: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`);
 		const { rows, evidence, done, finalStatus, reportMeta } = parsed.data;
 		let specs = run.specs;
+		let mergedResults = [];
 		await config.storage.artifacts.updateJsonFile(id, "report.json", (current) => {
 			const base = current ?? {
 				schemaVersion: 1,
@@ -13549,7 +13975,9 @@ function createPatchRunHandler(config) {
 				...base,
 				...reportMeta?.git ? { git: {
 					head: reportMeta.git.head ?? base.git.head,
-					base: reportMeta.git.base ?? base.git.base
+					base: reportMeta.git.base ?? base.git.base,
+					baseSha: reportMeta.git.baseSha ?? base.git.baseSha ?? null,
+					baseSource: reportMeta.git.baseSource ?? base.git.baseSource ?? null
 				} } : {},
 				...reportMeta?.model !== void 0 ? { model: reportMeta.model } : {},
 				...reportMeta?.language !== void 0 ? { language: reportMeta.language } : {},
@@ -13559,6 +13987,7 @@ function createPatchRunHandler(config) {
 			};
 			const merged = mergeResults(current?.results ?? [], rows);
 			specs = countSpecs(merged);
+			mergedResults = merged;
 			return {
 				...envelope,
 				results: merged
@@ -13572,6 +14001,7 @@ function createPatchRunHandler(config) {
 			...reportMeta?.promptVersion ? { promptVersion: reportMeta.promptVersion } : {}
 		} : { specs };
 		const updated = await config.storage.runs.update(id, patch);
+		if (done) await updateLastGreenLedger(config.storage, updated, mergedResults);
 		sendJson(ctx.res, 200, updated);
 	};
 }
@@ -13688,9 +14118,11 @@ function parseRunScope(ctx) {
 	};
 }
 /**
-* A branch is a free-form label (e.g. `feature/foo`), stored verbatim and
-* never used to build a filesystem path, so `/` is allowed — only length is
-* bounded. null when the client didn't send one.
+* A branch is a free-form label (e.g. `feature/foo`), so `/` is allowed —
+* only length is bounded (a sanity cap; the last-green ledger separately
+* hash-truncates long percent-encoded names into a safe filename, see
+* paths.ts). Run records store it verbatim. null when the client didn't
+* send one. Exported for the last-green handler.
 */
 function requireBranch(raw) {
 	if (raw === null || raw === "") return null;
@@ -13943,6 +14375,32 @@ function createListProfilesHandler(storage) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/last-green.ts
+/**
+* GET /api/v1/projects/:project/last-green?profile=&branch=&fallbackBranch=
+*
+* Returns the last-green ledger entries for one project/profile, keyed by
+* "feature/spec". `branch` is the caller's current branch; `fallbackBranch`
+* (optional, typically the default branch) is overlaid *under* it, so a PR
+* branch with no greens of its own still inherits the default branch's
+* baselines while its own greens take precedence. One round trip serves the
+* whole run.
+*/
+function createGetLastGreenHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const profile = requireSafeSegment(ctx.url.searchParams.get("profile") ?? "default", "profile");
+		const branch = requireBranch(ctx.url.searchParams.get("branch"));
+		if (!branch) throw new HttpError(400, "missing_param", "branch query parameter is required");
+		const fallbackBranch = requireBranch(ctx.url.searchParams.get("fallbackBranch"));
+		const [primary, fallback] = await Promise.all([storage.lastGreen.get(project, profile, branch), fallbackBranch && fallbackBranch !== branch ? storage.lastGreen.get(project, profile, fallbackBranch) : Promise.resolve({})]);
+		sendJson(ctx.res, 200, { entries: {
+			...fallback,
+			...primary
+		} });
+	};
+}
+//#endregion
 //#region src/hub/api/handlers/prompts.ts
 const MAX_PROMPT_BODY_BYTES = 256 * 1024;
 /** Validate the `:project` route param (prompts are project-scoped, not per-profile). */
@@ -17951,7 +18409,7 @@ function createLearningWorker(deps) {
 		const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const customPrompt = {
 			schemaVersion: 1,
-			basePromptVersion: "4",
+			basePromptVersion: "5",
 			customPromptVersion: `${generatedAt}-c${cases.length}`,
 			generatedAt,
 			guidance
@@ -18070,6 +18528,7 @@ function registerRoutes(router, config, queue) {
 	router.put("/api/v1/runs/:id/triage/actual-causes", createImportActualCausesHandler(storage));
 	router.get("/api/v1/projects", createListProjectsHandler(storage));
 	router.get("/api/v1/projects/:project/profiles", createListProfilesHandler(storage));
+	router.get("/api/v1/projects/:project/last-green", createGetLastGreenHandler(storage));
 	const sessionConfig = {
 		store: storage.sessions,
 		encryptionKey: config.encryptionKey
@@ -18302,6 +18761,10 @@ function perspectivesKindDir(root) {
 function perspectivesPath(root, project) {
 	return join(perspectivesKindDir(root), `${project}.json`);
 }
+function lastGreenPath(root, project, profile, branch) {
+	const encoded = encodeURIComponent(branch);
+	return join(root, "last-green", project, profile, `${encoded.length <= 200 ? encoded : `${encoded.slice(0, 64)}-${createHash("sha256").update(branch).digest("hex").slice(0, 32)}`}.json`);
+}
 //#endregion
 //#region src/hub/core/storage/file/artifact-store.ts
 /**
@@ -18389,6 +18852,25 @@ function createFileJobStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/last-green-store.ts
+function createFileLastGreenStore(root) {
+	return {
+		async get(project, profile, branch) {
+			return await readJson(lastGreenPath(root, project, profile, branch)) ?? {};
+		},
+		async merge(project, profile, branch, entries) {
+			await updateJson(lastGreenPath(root, project, profile, branch), (current) => {
+				const out = { ...current ?? {} };
+				for (const [key, entry] of Object.entries(entries)) {
+					const prev = out[key];
+					if (!prev || prev.at <= entry.at) out[key] = entry;
+				}
+				return out;
+			});
+		}
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/perspectives-store.ts
 /**
 * Defense-in-depth path validation: the HTTP layer already checks the project
@@ -18642,7 +19124,8 @@ function createFileHubStorage(dataDir) {
 		triage: createFileTriageStore(dataDir),
 		prompts: createFilePromptStore(dataDir),
 		perspectives: createFilePerspectivesStore(dataDir),
-		jobs: createFileJobStore(dataDir)
+		jobs: createFileJobStore(dataDir),
+		lastGreen: createFileLastGreenStore(dataDir)
 	};
 }
 //#endregion