gentle-pi 2.1.2 → 2.2.0

package/lib/review-candidate-view.ts

@@ -4,10 +4,51 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
 
 const REVIEW_LENS = ["review-risk", "review-resilience", "review-readability", "review-reliability"] as const;
 export type ReviewLens = (typeof REVIEW_LENS)[number];
 const CANDIDATE_GIT_TIMEOUT_MS = 10_000;
+const CANDIDATE_GIT_TIMEOUT_MAX_MS = 120_000;
+const CANDIDATE_GIT_TIMEOUT_ENV = "GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS";
+const CANDIDATE_GIT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+// Candidate views may materialize full repository trees. Large repositories can
+// raise this bounded deadline without creating an unbounded child process.
+function resolveCandidateGitTimeoutMs(environment: NodeJS.ProcessEnv = process.env): number {
+	const value = environment[CANDIDATE_GIT_TIMEOUT_ENV];
+	if (value === undefined || !/^[1-9]\d*$/.test(value)) return CANDIDATE_GIT_TIMEOUT_MS;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed <= CANDIDATE_GIT_TIMEOUT_MAX_MS
+		? parsed
+		: CANDIDATE_GIT_TIMEOUT_MS;
+}
+
+function isCandidateGitTimeoutMs(value: number): boolean {
+	return Number.isSafeInteger(value) && value > 0 && value <= CANDIDATE_GIT_TIMEOUT_MAX_MS;
+}
+const CANDIDATE_VIEW_DIAGNOSTIC_PHASE = "candidate-view";
+const CANDIDATE_VIEW_GIT_FAILURE_CATEGORY = {
+	TIMEOUT: "timeout",
+	OUTPUT_LIMIT: "output-limit",
+	GIT_FAILURE: "git-failure",
+} as const;
+export type CandidateViewGitFailureCategory = (typeof CANDIDATE_VIEW_GIT_FAILURE_CATEGORY)[keyof typeof CANDIDATE_VIEW_GIT_FAILURE_CATEGORY];
+const CANDIDATE_GIT_SUBCOMMAND = {
+	ADD: "add",
+	CHECKOUT_INDEX: "checkout-index",
+	DIFF: "diff",
+	FOR_EACH_REF: "for-each-ref",
+	LOG: "log",
+	LS_FILES: "ls-files",
+	LS_TREE: "ls-tree",
+	READ_TREE: "read-tree",
+	REV_PARSE: "rev-parse",
+	WORKTREE: "worktree",
+	WRITE_TREE: "write-tree",
+	OTHER: "other",
+} as const;
+type CandidateGitSubcommand = (typeof CANDIDATE_GIT_SUBCOMMAND)[keyof typeof CANDIDATE_GIT_SUBCOMMAND];
 
 export type CandidateGitExecutor = (file: string, arguments_: readonly string[], options: ExecFileSyncOptions) => string | Buffer;
 const defaultCandidateGitExecutor: CandidateGitExecutor = (file, arguments_, options) => execFileSync(file, arguments_, options);
@@ -16,6 +57,20 @@ const CONTROLLER_CANDIDATE_VIEW_HEADING = "## Controller-owned candidate view";
 const MAX_SUBAGENT_TASK_LENGTH = 16_384;
 const MAX_SUBAGENT_CONTEXT_LENGTH = 4_096;
 const MAX_CANDIDATE_CONTEXT_LENGTH = 4_096;
+const MAX_CANDIDATE_CONTEXT_MANIFEST_BYTES = 1024 * 1024;
+const MAX_CANDIDATE_SCOPE_PAGE_BYTES = 16 * 1024;
+const MAX_CANDIDATE_SCOPE_PAGE_ENTRIES = 128;
+const CANDIDATE_CONTEXT_MANIFEST = {
+	VERSION: 1,
+} as const;
+const CANDIDATE_CONTEXT_MODE = {
+	REGULAR: "100644",
+	EXECUTABLE: "100755",
+	SYMLINK: "120000",
+	GITLINK: "160000",
+	DELETED: "deleted",
+} as const;
+export type CandidateContextMode = (typeof CANDIDATE_CONTEXT_MODE)[keyof typeof CANDIDATE_CONTEXT_MODE];
 const SUBAGENT_RUN_KEYS = new Set(["agent", "agents", "task", "context", "mode"]);
 
 interface CandidateTreeEntry {
@@ -71,6 +126,33 @@ export interface CandidateView {
 	cleanup(): void;
 }
 
+export interface CandidateContextManifest {
+	version: typeof CANDIDATE_CONTEXT_MANIFEST.VERSION;
+	scopeByMode: Readonly<Record<string, readonly string[]>>;
+	gitlinks: Readonly<Record<string, string>>;
+}
+
+export interface DecodedCandidateContextManifest {
+	manifest: CandidateContextManifest;
+	bytes: Buffer;
+	sha256: string;
+}
+
+export interface CandidateContextPageEntry {
+	path: string;
+	mode: CandidateContextMode;
+	gitlinkObjectId?: string;
+}
+
+export interface CandidateContextPage {
+	version: typeof CANDIDATE_CONTEXT_MANIFEST.VERSION;
+	sha256: string;
+	cursor: number;
+	totalPaths: number;
+	entries: readonly CandidateContextPageEntry[];
+	nextCursor?: number;
+}
+
 export interface FrozenCandidateProjection {
 	contributorRoot: string;
 	baseCommit: string;
@@ -130,22 +212,96 @@ export interface NativeCandidateProjectionDescriptor {
 	providerManifestHashVerified?: true;
 }
 
+export interface CandidateViewDiagnostic {
+	phase: typeof CANDIDATE_VIEW_DIAGNOSTIC_PHASE;
+	category: CandidateViewGitFailureCategory;
+	git_subcommand: CandidateGitSubcommand;
+	timeout_ms: number;
+	max_buffer_bytes: number;
+	message: string;
+}
+
 export class CandidateViewError extends Error {
 	readonly reason: string;
-	constructor(message: string, reason = "candidate-view-invalid") {
+	readonly diagnostics?: CandidateViewDiagnostic;
+	constructor(message: string, reason = "candidate-view-invalid", diagnostics?: CandidateViewDiagnostic) {
 		super(message);
 		this.name = "CandidateViewError";
 		this.reason = reason;
+		this.diagnostics = diagnostics === undefined ? undefined : sanitizeCandidateViewDiagnostic(diagnostics);
+	}
+}
+
+function candidateGitSubcommand(arguments_: readonly string[]): CandidateGitSubcommand {
+	switch (arguments_[0]) {
+		case CANDIDATE_GIT_SUBCOMMAND.ADD: return CANDIDATE_GIT_SUBCOMMAND.ADD;
+		case CANDIDATE_GIT_SUBCOMMAND.CHECKOUT_INDEX: return CANDIDATE_GIT_SUBCOMMAND.CHECKOUT_INDEX;
+		case CANDIDATE_GIT_SUBCOMMAND.DIFF: return CANDIDATE_GIT_SUBCOMMAND.DIFF;
+		case CANDIDATE_GIT_SUBCOMMAND.FOR_EACH_REF: return CANDIDATE_GIT_SUBCOMMAND.FOR_EACH_REF;
+		case CANDIDATE_GIT_SUBCOMMAND.LOG: return CANDIDATE_GIT_SUBCOMMAND.LOG;
+		case CANDIDATE_GIT_SUBCOMMAND.LS_FILES: return CANDIDATE_GIT_SUBCOMMAND.LS_FILES;
+		case CANDIDATE_GIT_SUBCOMMAND.LS_TREE: return CANDIDATE_GIT_SUBCOMMAND.LS_TREE;
+		case CANDIDATE_GIT_SUBCOMMAND.READ_TREE: return CANDIDATE_GIT_SUBCOMMAND.READ_TREE;
+		case CANDIDATE_GIT_SUBCOMMAND.REV_PARSE: return CANDIDATE_GIT_SUBCOMMAND.REV_PARSE;
+		case CANDIDATE_GIT_SUBCOMMAND.WORKTREE: return CANDIDATE_GIT_SUBCOMMAND.WORKTREE;
+		case CANDIDATE_GIT_SUBCOMMAND.WRITE_TREE: return CANDIDATE_GIT_SUBCOMMAND.WRITE_TREE;
+		default: return CANDIDATE_GIT_SUBCOMMAND.OTHER;
 	}
 }
 
+function candidateGitDiagnosticMessage(category: CandidateViewGitFailureCategory, subcommand: CandidateGitSubcommand, timeoutMs: number): string {
+	if (category === CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.TIMEOUT) return `candidate-view Git command ${subcommand} timed out after ${timeoutMs}ms; inspect the candidate state before any new START`;
+	if (category === CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.OUTPUT_LIMIT) return `candidate-view Git command ${subcommand} exceeded the ${CANDIDATE_GIT_MAX_BUFFER_BYTES}-byte output limit; inspect the candidate state before any new START`;
+	return `candidate-view Git command ${subcommand} failed; inspect the candidate state before any new START`;
+}
+
+function candidateGitDiagnostic(category: CandidateViewGitFailureCategory, arguments_: readonly string[], timeoutMs: number): CandidateViewDiagnostic {
+	const git_subcommand = candidateGitSubcommand(arguments_);
+	return Object.freeze({
+		phase: CANDIDATE_VIEW_DIAGNOSTIC_PHASE,
+		category,
+		git_subcommand,
+		timeout_ms: timeoutMs,
+		max_buffer_bytes: CANDIDATE_GIT_MAX_BUFFER_BYTES,
+		message: candidateGitDiagnosticMessage(category, git_subcommand, timeoutMs),
+	});
+}
+
+function sanitizeCandidateViewDiagnostic(diagnostics: CandidateViewDiagnostic): CandidateViewDiagnostic | undefined {
+	const { phase, category, git_subcommand, timeout_ms, max_buffer_bytes, message } = diagnostics;
+	if (
+		phase !== CANDIDATE_VIEW_DIAGNOSTIC_PHASE ||
+		!Object.values(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY).includes(category) ||
+		!Object.values(CANDIDATE_GIT_SUBCOMMAND).includes(git_subcommand) ||
+		!isCandidateGitTimeoutMs(timeout_ms) ||
+		max_buffer_bytes !== CANDIDATE_GIT_MAX_BUFFER_BYTES ||
+		message !== candidateGitDiagnosticMessage(category, git_subcommand, timeout_ms)
+	) return undefined;
+	return Object.freeze({ phase, category, git_subcommand, timeout_ms, max_buffer_bytes, message });
+}
+
+function candidateGitFailure(category: CandidateViewGitFailureCategory, arguments_: readonly string[], timeoutMs: number): CandidateViewError {
+	const diagnostics = candidateGitDiagnostic(category, arguments_, timeoutMs);
+	return new CandidateViewError(diagnostics.message, `candidate-view-${category}`, diagnostics);
+}
+
 function candidateGit(cwd: string, arguments_: readonly string[], env: NodeJS.ProcessEnv, encoding: "utf8" | "buffer", executor: CandidateGitExecutor): string | Buffer {
+	const timeoutMs = resolveCandidateGitTimeoutMs(env);
 	try {
-		return executor("git", arguments_, { cwd, encoding, env, stdio: ["ignore", "pipe", "pipe"], timeout: CANDIDATE_GIT_TIMEOUT_MS, windowsHide: true });
+		return executor("git", arguments_, {
+			cwd,
+			encoding,
+			env,
+			stdio: ["ignore", "pipe", "pipe"],
+			timeout: timeoutMs,
+			maxBuffer: CANDIDATE_GIT_MAX_BUFFER_BYTES,
+			windowsHide: true,
+		});
 	} catch (error) {
-		const detail = error as NodeJS.ErrnoException & { stderr?: Buffer; killed?: boolean };
-		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw new CandidateViewError(`candidate view Git operation timed out after ${CANDIDATE_GIT_TIMEOUT_MS}ms`);
-		throw new CandidateViewError(`candidate view Git operation failed: ${detail.stderr?.toString("utf8").trim() || detail.message || "unknown Git error"}`);
+		const detail = error as NodeJS.ErrnoException & { killed?: boolean };
+		if (detail.code === "ENOBUFS" || detail.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.OUTPUT_LIMIT, arguments_, timeoutMs);
+		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.TIMEOUT, arguments_, timeoutMs);
+		throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.GIT_FAILURE, arguments_, timeoutMs);
 	}
 }
 
@@ -348,11 +504,11 @@ function assertManifestMatchesGit(descriptor: NativeCandidateProjectionDescripto
 	}
 }
 
-function deriveChangedScope(cwd: string, baseCommit: string, candidateTree: string, entries: readonly CandidateTreeEntry[], executor: CandidateGitExecutor): CandidateViewScope {
+function deriveChangedScope(cwd: string, baseTree: string, candidateTree: string, entries: readonly CandidateTreeEntry[], executor: CandidateGitExecutor): CandidateViewScope {
 	const present = new Map(entries.map((entry) => [entry.path, entry]));
 	const paths = new Set<string>();
 	const deleted = new Set<string>();
-	const tokens = gitPathTokens(cwd, ["diff", "--name-status", "-z", "--no-ext-diff", "--find-renames=100%", baseCommit, candidateTree], executor);
+	const tokens = gitPathTokens(cwd, ["diff", "--name-status", "-z", "--no-ext-diff", "--find-renames=100%", baseTree, candidateTree], executor);
 	for (let index = 0; index < tokens.length;) {
 		const status = tokens[index++]?.toString("ascii");
 		if (status === undefined || !/^(?:[AMDT]|R[0-9]{3})$/.test(status)) throw new CandidateViewError("candidate scope Git output contains an unsafe status");
@@ -468,8 +624,60 @@ function explicitBaseRefCandidates(cwd: string, selector: string, env: NodeJS.Pr
 	return [...new Set(candidates)].filter((candidate) => refs.has(candidate));
 }
 
+// Runs a probe command that may exit nonzero as an expected signal (absent
+// ref, detached HEAD). Returns the exit status and trimmed stdout. Timeout,
+// output-limit, and unexpected Git failures propagate as sanitized
+// CandidateViewError diagnostics, same as candidateGit.
+function probeCandidateGit(cwd: string, arguments_: readonly string[], env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): { status: number; stdout: string } {
+	const timeoutMs = resolveCandidateGitTimeoutMs(env);
+	try {
+		const stdout = executor("git", arguments_, {
+			cwd, encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"],
+			timeout: timeoutMs, maxBuffer: CANDIDATE_GIT_MAX_BUFFER_BYTES, windowsHide: true,
+		}) as string;
+		return { status: 0, stdout: stdout.trim() };
+	} catch (error) {
+		const detail = error as NodeJS.ErrnoException & { killed?: boolean; status?: number; stdout?: string | Buffer };
+		if (detail.code === "ENOBUFS" || detail.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.OUTPUT_LIMIT, arguments_, timeoutMs);
+		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.TIMEOUT, arguments_, timeoutMs);
+		if (typeof detail.status === "number") return { status: detail.status, stdout: typeof detail.stdout === "string" ? detail.stdout.trim() : "" };
+		throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.GIT_FAILURE, arguments_, timeoutMs);
+	}
+}
+
+// An unborn repository's HEAD is a symbolic ref to a branch with no commits.
+// `symbolic-ref --quiet HEAD` exits nonzero for a detached HEAD (not unborn).
+// `rev-parse --verify --quiet <ref>` distinguishes a valid unborn (status 1,
+// ref absent) from a broken symbolic ref (exit 0, ref OID text exists even
+// when the object is missing). Any other status (128, etc.) signals
+// corruption or an I/O failure, so it fails closed instead of masquerading as
+// an unborn repository.
+function isUnbornSymbolicHead(cwd: string, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): boolean {
+	const symbolic = probeCandidateGit(cwd, ["symbolic-ref", "--quiet", "HEAD"], env, executor);
+	if (symbolic.status !== 0) return false;
+	const refProbeArguments = ["rev-parse", "--verify", "--quiet", symbolic.stdout];
+	const refProbe = probeCandidateGit(cwd, refProbeArguments, env, executor);
+	if (refProbe.status === 1) return true;
+	if (refProbe.status === 0) return false;
+	throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.GIT_FAILURE, refProbeArguments, resolveCandidateGitTimeoutMs(env));
+}
+
+// Derives Git's repository-native empty tree without hardcoding the SHA-1 id,
+// so a sha256 repository derives its own empty-tree object id. `mktree` with
+// ignored stdin reads empty input and writes the empty tree object.
+function resolveEmptyTree(cwd: string, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): string {
+	return git(cwd, ["mktree"], env, executor);
+}
+
 function resolveCandidateBase(cwd: string, baseRef: string | undefined, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): ResolvedCandidateBase {
 	const selector = baseRef ?? "HEAD";
+	// An unborn repository has a symbolic HEAD pointing at a branch with no
+	// commits yet. Its review base is Git's repository-native empty tree, not a
+	// missing or malformed commit. Only the default/HEAD selector is entitled to
+	// the empty-tree base; a detached HEAD over a missing commit stays fail-closed.
+	if (selector === "HEAD" && isUnbornSymbolicHead(cwd, env, executor)) {
+		return { commit: "HEAD", tree: resolveEmptyTree(cwd, env, executor) };
+	}
 	try {
 		if (baseRef !== undefined) {
 			const candidates = explicitBaseRefCandidates(cwd, selector, env, executor);
@@ -484,7 +692,7 @@ function resolveCandidateBase(cwd: string, baseRef: string | undefined, env: Nod
 		if (tree !== confirmedTree) throw new CandidateViewError("candidate base tree changed during resolution", "base-ref-moved");
 		return { commit: confirmedCommit, tree: confirmedTree };
 	} catch (error) {
-		if (error instanceof CandidateViewError && (error.reason === "base-ref-ambiguous" || error.reason === "base-ref-moved" || error.reason === "base-ref-unresolvable")) throw error;
+		if (error instanceof CandidateViewError && (error.diagnostics !== undefined || error.reason === "base-ref-ambiguous" || error.reason === "base-ref-moved" || error.reason === "base-ref-unresolvable")) throw error;
 		throw new CandidateViewError("candidate base reference is unresolvable", "base-ref-unresolvable");
 	}
 }
@@ -519,6 +727,37 @@ function checkoutMaterializedEntries(root: string, entries: readonly CandidateTr
 	flush();
 }
 
+// Creates an unborn worktree (symbolic HEAD pointing at a branch with no
+// commits, no ref written, no phantom commit). Git 2.42+ supports --orphan
+// directly; older Git lacks the flag and reports an unsupported-option usage
+// error (exit status 129). Only that exact status triggers the fallback: a
+// temporary empty-tree commit seeds a detached --no-checkout worktree, then
+// a symbolic-ref rewrite makes HEAD unborn. The temporary commit is never
+// referenced by any ref and is GC-able, so it is not a phantom commit. The
+// fallback uses a deterministic author/committer identity and timestamp in a
+// copied environment so it does not depend on user.name/user.email or the
+// ambient date. Contributor HEAD, branch, refs, and index are never touched.
+function addUnbornWorktree(cwd: string, root: string, branch: string, env: NodeJS.ProcessEnv, executor: CandidateGitExecutor): void {
+	const primary = probeCandidateGit(cwd, ["worktree", "add", "--orphan", "-b", branch, root], env, executor);
+	if (primary.status === 0) return;
+	// Only the unsupported-option usage status (129, pre-2.42 Git lacking --orphan)
+	// triggers the fallback. Every other status propagates as a git-failure.
+	if (primary.status !== 129 || existsSync(root)) throw candidateGitFailure(CANDIDATE_VIEW_GIT_FAILURE_CATEGORY.GIT_FAILURE, ["worktree", "add", "--orphan", "-b", branch, root], resolveCandidateGitTimeoutMs(env));
+	const fallbackEnv = {
+		...env,
+		GIT_AUTHOR_NAME: "gentle-ai-candidate",
+		GIT_AUTHOR_EMAIL: "gentle-ai-candidate@example.invalid",
+		GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z",
+		GIT_COMMITTER_NAME: "gentle-ai-candidate",
+		GIT_COMMITTER_EMAIL: "gentle-ai-candidate@example.invalid",
+		GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z",
+	};
+	const emptyTree = git(cwd, ["mktree"], fallbackEnv, executor);
+	const tempCommit = git(cwd, ["commit-tree", "-m", "gentle-ai-candidate", emptyTree], fallbackEnv, executor);
+	git(cwd, ["worktree", "add", "--no-checkout", "--detach", root, tempCommit], env, executor);
+	git(root, ["symbolic-ref", "HEAD", `refs/heads/${branch}`], env, executor);
+}
+
 function materializeCandidateView(request: CreateCandidateViewRequest, executor: CandidateGitExecutor): CandidateViewRecord {
 	const contributorRoot = realpathSync(request.contributorRoot);
 	if (!lstatSync(contributorRoot).isDirectory()) throw new CandidateViewError("contributor root is not a directory");
@@ -536,17 +775,32 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 	const environment = { ...process.env, GIT_INDEX_FILE: indexPath };
 	try {
 		const baseCommit = base.commit;
-		git(contributorRoot, ["read-tree", candidateCommit.commit], environment, executor);
+		const unborn = baseCommit === "HEAD";
+		// For an unborn repository the base tree is Git's empty tree, so seed the
+		// private candidate index from `--empty` instead of a non-existent commit.
+		if (unborn) git(contributorRoot, ["read-tree", "--empty"], environment, executor);
+		else git(contributorRoot, ["read-tree", candidateCommit.commit], environment, executor);
 		if (!committedOnly) git(contributorRoot, ["add", "-A"], environment, executor);
 		const candidateTree = git(contributorRoot, ["write-tree"], environment, executor);
 		const root = join(parent, randomUUID());
-		git(contributorRoot, ["worktree", "add", "--detach", "--no-checkout", root, candidateCommit.commit], process.env, executor);
+		// The worktree is created under the same try/catch cleanup boundary as
+		// the read-tree materialization that follows. addUnbornWorktree's
+		// fallback path can register a worktree with `worktree add` and then
+		// fail on a later step (for example `symbolic-ref`); moving creation
+		// here ensures any such partial registration is removed by the catch
+		// below instead of leaking a registered/admin worktree and directory.
 		try {
+			// An unborn repository has no commit to detach a worktree at. addUnbornWorktree
+			// creates an orphan worktree (unborn branch, no commit, no ref) to host the
+			// materialized candidate tree without a phantom commit, with a fallback for
+			// Git versions older than 2.42 that do not support --orphan.
+			if (unborn) addUnbornWorktree(contributorRoot, root, `gentle-ai-candidate-${randomUUID()}`, process.env, executor);
+			else git(contributorRoot, ["worktree", "add", "--detach", "--no-checkout", root, candidateCommit.commit], process.env, executor);
 			git(root, ["read-tree", candidateTree], process.env, executor);
 			const tree = parseTree(root, candidateTree, executor);
 			checkoutMaterializedEntries(root, tree.entries, executor);
 			const entries = tree.entries.map((entry) => ({ ...entry, contentHash: entryContentHash(root, entry) }));
-			const scope = deriveChangedScope(contributorRoot, baseCommit, candidateTree, [...tree.entries, ...tree.gitlinks], executor);
+			const scope = deriveChangedScope(contributorRoot, base.tree, candidateTree, [...tree.entries, ...tree.gitlinks], executor);
 			for (const gitlink of tree.gitlinks) if (lstatSync(join(root, gitlink.path), { throwIfNoEntry: false })) throw new CandidateViewError("candidate view materialized a metadata-only gitlink");
 			makeReadonly(root, entries);
 			return { token: basename(root), root: realpathSync(root), parent, contributorRoot, commonDir: canonicalCommonDir, baseCommit, baseTree: base.tree, candidateTree, committedOnly, entries, gitlinks: tree.gitlinks, scope, gitExecutor: executor };
@@ -603,6 +857,11 @@ export class CandidateViewRegistry {
 	private readonly projections = new Map<string, FrozenCandidateProjection>();
 	private readonly replays = new Map<string, string>();
 	private current: { lineageId: string; token: string } | undefined;
+	// The last dispatch-binding hydration that was attempted and failed. A
+	// swallowed hydration failure is its own defect (field report 2026-08-16):
+	// without it the later dispatch refusal claims no binding was ever
+	// available instead of naming the attempt and its typed cause.
+	private lastHydrationFailure: { lineageId: string; reason: string; message: string } | undefined;
 
 	create(request: CreateCandidateViewRequest): CandidateView {
 		return this.createOrReuse(request);
@@ -833,6 +1092,37 @@ export class CandidateViewRegistry {
 		});
 	}
 
+	/**
+	 * Re-derives this lineage's FINALIZE binding from the provider's own
+	 * projection, replacing a binding this session is still holding.
+	 *
+	 * Field defect (Engram #12547): once a bounded correction is admitted, the
+	 * candidate identity legitimately moves, and the provider issues its
+	 * finalize transition for that corrected target. A session that started the
+	 * review still holds the START-time immutable reviewer view, so comparing
+	 * it against the corrected projection reads as drift and no receipt is ever
+	 * minted — while a fresh process, which restores from the native descriptor,
+	 * finalizes the very same lineage successfully. This makes the in-session
+	 * path behave like that already-correct fresh-process path.
+	 *
+	 * This is a re-derivation, not a relaxation: the replacement is
+	 * materialized from Git and must match the provider descriptor exactly
+	 * (base tree, projection kind, changed-path manifest), and the caller still
+	 * asserts the binding afterwards. The immutable reviewer view is retired
+	 * here on purpose — the lenses that consumed it finished before the
+	 * correction.
+	 */
+	rebindForFinalizeFromNative(lineageId: string, contributorRoot: string, descriptor: NativeCandidateProjectionDescriptor): CandidateView {
+		const staleToken = this.lineages.get(lineageId);
+		const stale = staleToken === undefined ? undefined : this.records.get(staleToken);
+		this.projections.delete(lineageId);
+		if (stale !== undefined) {
+			this.remove(stale);
+			this.forget(stale);
+		}
+		return this.restoreForFinalizeFromNative(lineageId, contributorRoot, descriptor);
+	}
+
 	restoreForFinalizeFromNative(lineageId: string, contributorRoot: string, descriptor: NativeCandidateProjectionDescriptor): CandidateView {
 		this.restoreProjectionFromNative(lineageId, contributorRoot, descriptor);
 		const projection = this.resolveProjection(lineageId, contributorRoot);
@@ -851,6 +1141,46 @@ export class CandidateViewRegistry {
 		}
 	}
 
+	/**
+	 * Mirrors the START-time dispatch registration for a lineage this
+	 * controller never started (live defect 2026-08-16: a successor created
+	 * by native `review recover` exists only in native authority). The
+	 * authoritative STATUS descriptor supplies the frozen projection; the
+	 * live candidate is re-materialized and must match it exactly before the
+	 * dispatch-facing current binding is established with the provider-named
+	 * pending lenses.
+	 */
+	restoreCurrentForDispatchFromNative(lineageId: string, contributorRoot: string, descriptor: NativeCandidateProjectionDescriptor, selectedLenses: readonly string[]): void {
+		if (this.current !== undefined) throw new CandidateViewError("candidate view already has a current lineage binding", "current-binding-already-established");
+		try {
+			const lenses = this.validateSelectedLenses(selectedLenses);
+			this.restoreProjectionFromNative(lineageId, contributorRoot, descriptor);
+			const projection = this.resolveProjection(lineageId, contributorRoot);
+			const record = materializeCandidateView({ contributorRoot, baseRef: projection.baseCommit, committedOnly: projection.committedOnly }, this.gitExecutor);
+			try {
+				if (record.baseTree !== projection.baseTree || record.candidateTree !== projection.candidateTree || JSON.stringify(record.scope.paths) !== JSON.stringify(projection.paths)) {
+					throw new CandidateViewError("live candidate does not match the native frozen projection");
+				}
+				this.records.set(record.token, record);
+				this.bindRecord(record.token, lineageId, lenses);
+				this.current = { lineageId, token: record.token };
+			} catch (error) {
+				this.projections.delete(lineageId);
+				this.records.delete(record.token);
+				this.remove(record);
+				throw error;
+			}
+			this.lastHydrationFailure = undefined;
+		} catch (error) {
+			this.lastHydrationFailure = {
+				lineageId,
+				reason: error instanceof CandidateViewError ? error.reason : "candidate-view-invalid",
+				message: error instanceof Error ? error.message : String(error),
+			};
+			throw error;
+		}
+	}
+
 	resolveProjection(lineageId: string, contributorRoot: string): FrozenCandidateProjection {
 		const projection = this.projections.get(lineageId);
 		if (!projection || realpathSync(contributorRoot) !== projection.contributorRoot) {
@@ -868,10 +1198,24 @@ export class CandidateViewRegistry {
 	}
 
 	currentLineageId(): string {
-		if (this.current === undefined) throw new CandidateViewError("review subagent dispatch has no current controller-owned candidate view lineage binding", "current-binding-missing");
+		if (this.current === undefined) {
+			const failure = this.lastHydrationFailure;
+			if (failure !== undefined) {
+				throw new CandidateViewError(
+					`review subagent dispatch has no current controller-owned candidate view lineage binding: hydration for lineage ${failure.lineageId} was attempted from authoritative native status and failed (${failure.reason}): ${failure.message}`,
+					"current-binding-hydration-failed",
+				);
+			}
+			throw new CandidateViewError("review subagent dispatch has no current controller-owned candidate view lineage binding", "current-binding-missing");
+		}
 		return this.current.lineageId;
 	}
 
+	/** The last failed dispatch-binding hydration, for controller envelopes. */
+	lastDispatchHydrationFailure(): Readonly<{ lineageId: string; reason: string; message: string }> | undefined {
+		return this.lastHydrationFailure;
+	}
+
 	resolveCurrentForLens(lens: string): CandidateView {
 		return this.resolveCurrentForLenses([lens])[0]!;
 	}
@@ -986,22 +1330,187 @@ function hasCandidateContextConflict(text: string, views: readonly CandidateView
 		|| views.some((view) => text.includes(view.root) || text.includes(view.candidateTree));
 }
 
-function candidateContextBlock(lineageId: string, agents: readonly ReviewLens[], view: CandidateView): string {
+function compareCanonicalStrings(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function canonicalStringMap(value: Readonly<Record<string, string>>): Record<string, string> {
+	// Plain objects enumerate integer-like keys numerically; canonical round trips intentionally preserve that ordering.
+	return Object.fromEntries(Object.entries(value).sort(([left], [right]) => compareCanonicalStrings(left, right)));
+}
+
+function candidateScopeByMode(view: CandidateView): Record<string, string[]> {
 	const grouped = new Map<string, string[]>();
+	const deletedPaths = new Set(view.deletedPaths);
 	for (const path of view.paths) {
-		const group = view.deletedPaths.includes(path) ? "deleted" : view.modes[path];
+		const group = deletedPaths.has(path) ? "deleted" : view.modes[path];
 		if (group === undefined) throw new CandidateViewError("candidate view scope omits a changed path mode");
 		const paths = grouped.get(group) ?? [];
 		paths.push(path);
 		grouped.set(group, paths);
 	}
-	const scope = Object.fromEntries([...grouped.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+	return Object.fromEntries(
+		[...grouped.entries()]
+			.sort(([left], [right]) => compareCanonicalStrings(left, right))
+			.map(([mode, paths]) => [mode, paths.sort(compareCanonicalStrings)]),
+	);
+}
+
+function isCandidateContextMode(value: string): boolean {
+	return (Object.values(CANDIDATE_CONTEXT_MODE) as readonly string[]).includes(value);
+}
+
+function isCanonicalStringArray(value: unknown): value is readonly string[] {
+	return Array.isArray(value)
+		&& value.length > 0
+		&& value.every((item) => typeof item === "string" && isSafeCandidatePath(item))
+		&& value.every((item, index, items) => index === 0 || compareCanonicalStrings(items[index - 1]!, item) < 0);
+}
+
+function hasCanonicalRecordOrder(value: Readonly<Record<string, unknown>>): boolean {
+	const normalized = Object.fromEntries(Object.entries(value).sort(([left], [right]) => compareCanonicalStrings(left, right)));
+	return JSON.stringify(value) === JSON.stringify(normalized);
+}
+
+function invalidCandidateContextManifest(message: string): never {
+	throw new CandidateViewError(message, "candidate-context-manifest-invalid");
+}
+
+function validateCandidateContextManifest(value: unknown, bytes: Buffer): CandidateContextManifest {
+	if (!isRecord(value)) return invalidCandidateContextManifest("candidate context manifest has an invalid structure");
+	const keys = Object.keys(value);
+	const expectedKeys = ["version", "scopeByMode", "gitlinks"];
+	if (keys.length !== expectedKeys.length || !expectedKeys.every((key) => keys.includes(key))) {
+		return invalidCandidateContextManifest("candidate context manifest has an invalid structure");
+	}
+	if (JSON.stringify(keys) !== JSON.stringify(expectedKeys)) return invalidCandidateContextManifest("candidate context manifest is not canonical");
+	if (value.version !== CANDIDATE_CONTEXT_MANIFEST.VERSION || !isRecord(value.scopeByMode) || !isRecord(value.gitlinks)) {
+		return invalidCandidateContextManifest("candidate context manifest has an invalid structure");
+	}
+	const scopeByMode = value.scopeByMode;
+	if (!hasCanonicalRecordOrder(scopeByMode)) return invalidCandidateContextManifest("candidate context manifest is not canonical");
+	const scopePaths = new Set<string>();
+	for (const [mode, paths] of Object.entries(scopeByMode)) {
+		if (!isCandidateContextMode(mode) || !isCanonicalStringArray(paths)) return invalidCandidateContextManifest("candidate context manifest has an invalid scope");
+		for (const path of paths) {
+			if (scopePaths.has(path)) return invalidCandidateContextManifest("candidate context manifest has duplicate scope paths");
+			scopePaths.add(path);
+		}
+	}
+	const gitlinks = value.gitlinks;
+	if (!hasCanonicalRecordOrder(gitlinks)) return invalidCandidateContextManifest("candidate context manifest is not canonical");
+	for (const [path, objectId] of Object.entries(gitlinks)) {
+		if (!isSafeCandidatePath(path) || typeof objectId !== "string" || !isCanonicalObjectId(objectId)) {
+			return invalidCandidateContextManifest("candidate context manifest has an invalid gitlink map");
+		}
+	}
+	const gitlinkPaths = scopeByMode["160000"];
+	const canonicalGitlinkPaths = Object.keys(gitlinks).sort(compareCanonicalStrings);
+	if (
+		(gitlinkPaths === undefined && canonicalGitlinkPaths.length !== 0)
+		|| (gitlinkPaths !== undefined && JSON.stringify(canonicalGitlinkPaths) !== JSON.stringify(gitlinkPaths))
+	) return invalidCandidateContextManifest("candidate context manifest gitlinks do not match its scope");
+	const manifest: CandidateContextManifest = {
+		version: CANDIDATE_CONTEXT_MANIFEST.VERSION,
+		scopeByMode: scopeByMode as Readonly<Record<string, readonly string[]>>,
+		gitlinks: gitlinks as Readonly<Record<string, string>>,
+	};
+	if (!Buffer.from(JSON.stringify(manifest), "utf8").equals(bytes)) {
+		return invalidCandidateContextManifest("candidate context manifest is not canonical");
+	}
+	return manifest;
+}
+
+export function decodeCandidateContextManifest(encoded: string, sha256: string): DecodedCandidateContextManifest {
+	if (encoded.length > MAX_CANDIDATE_CONTEXT_LENGTH || !/^[A-Za-z0-9_-]+$/.test(encoded) || !/^[0-9a-f]{64}$/.test(sha256)) {
+		throw new CandidateViewError("candidate context manifest encoding is invalid", "candidate-context-manifest-invalid");
+	}
+	let bytes: Buffer;
+	try {
+		bytes = gunzipSync(Buffer.from(encoded, "base64url"), { maxOutputLength: MAX_CANDIDATE_CONTEXT_MANIFEST_BYTES });
+	} catch {
+		throw new CandidateViewError("candidate context manifest cannot be decompressed", "candidate-context-manifest-invalid");
+	}
+	const actualSha256 = createHash("sha256").update(bytes).digest("hex");
+	if (actualSha256 !== sha256) throw new CandidateViewError("candidate context manifest integrity check failed", "candidate-context-manifest-integrity");
+	const text = bytes.toString("utf8");
+	if (!Buffer.from(text, "utf8").equals(bytes)) return invalidCandidateContextManifest("candidate context manifest is not valid UTF-8");
+	if (gzipSync(bytes, { mtime: 0 }).toString("base64url") !== encoded) {
+		return invalidCandidateContextManifest("candidate context manifest transport is not canonical");
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		if (error instanceof CandidateViewError) throw error;
+		return invalidCandidateContextManifest("candidate context manifest is not valid JSON");
+	}
+	return { manifest: validateCandidateContextManifest(value, bytes), bytes, sha256: actualSha256 };
+}
+
+export function readCandidateContextManifestPage(encoded: string, sha256: string, cursor = 0): CandidateContextPage {
+	if (!Number.isSafeInteger(cursor) || cursor < 0) throw new CandidateViewError("candidate context manifest cursor is invalid", "candidate-context-cursor-invalid");
+	const decoded = decodeCandidateContextManifest(encoded, sha256);
+	const entries = Object.entries(decoded.manifest.scopeByMode).flatMap(([mode, paths]) => paths.map((path): CandidateContextPageEntry => ({
+		path,
+		mode: mode as CandidateContextMode,
+		...(mode === CANDIDATE_CONTEXT_MODE.GITLINK ? { gitlinkObjectId: decoded.manifest.gitlinks[path]! } : {}),
+	})));
+	if (cursor > entries.length) throw new CandidateViewError("candidate context manifest cursor exceeds the changed scope", "candidate-context-cursor-invalid");
+	const pageEntries: CandidateContextPageEntry[] = [];
+	for (let index = cursor; index < entries.length && pageEntries.length < MAX_CANDIDATE_SCOPE_PAGE_ENTRIES; index += 1) {
+		const candidateEntries = [...pageEntries, entries[index]!];
+		const candidatePage: CandidateContextPage = {
+			version: CANDIDATE_CONTEXT_MANIFEST.VERSION,
+			sha256: decoded.sha256,
+			cursor,
+			totalPaths: entries.length,
+			entries: candidateEntries,
+			...(cursor + candidateEntries.length < entries.length ? { nextCursor: cursor + candidateEntries.length } : {}),
+		};
+		if (Buffer.byteLength(JSON.stringify(candidatePage), "utf8") > MAX_CANDIDATE_SCOPE_PAGE_BYTES) {
+			if (pageEntries.length === 0) throw new CandidateViewError("candidate context manifest path exceeds the bounded actor response", "candidate-context-page-too-large");
+			break;
+		}
+		pageEntries.push(entries[index]!);
+	}
+	return {
+		version: CANDIDATE_CONTEXT_MANIFEST.VERSION,
+		sha256: decoded.sha256,
+		cursor,
+		totalPaths: entries.length,
+		entries: pageEntries,
+		...(cursor + pageEntries.length < entries.length ? { nextCursor: cursor + pageEntries.length } : {}),
+	};
+}
+
+function candidateContextPreamble(lineageId: string, agents: readonly ReviewLens[], view: CandidateView, scopeSemantics: string): string {
+	return `\n\n${CONTROLLER_CANDIDATE_VIEW_HEADING}\nController-owned review lineage: \`${lineageId}\`.\nAuthorized review actors: ${agents.join(", ")}.\nRead ONLY the absolute frozen candidate view at \`${view.root}\`.\nFrozen candidate tree: \`${view.candidateTree}\`.\nScope semantics: ${scopeSemantics}`;
+}
+
+function compactCandidateContextBlock(lineageId: string, agents: readonly ReviewLens[], view: CandidateView, scopeSemantics: string, scopeByMode: Record<string, string[]>): string {
+	const manifest: CandidateContextManifest = {
+		version: CANDIDATE_CONTEXT_MANIFEST.VERSION,
+		scopeByMode,
+		gitlinks: canonicalStringMap(view.gitlinks),
+	};
+	const bytes = Buffer.from(JSON.stringify(manifest), "utf8");
+	if (bytes.length > MAX_CANDIDATE_CONTEXT_MANIFEST_BYTES) throw new CandidateViewError("candidate view context exceeds the bounded dispatch contract");
+	const sha256 = createHash("sha256").update(bytes).digest("hex");
+	const encoded = gzipSync(bytes, { mtime: 0 }).toString("base64url");
+	const block = `${candidateContextPreamble(lineageId, agents, view, scopeSemantics)}\nFrozen changed scope manifest (gzip+base64url): \`${encoded}\`.\nFrozen changed scope manifest SHA-256: \`${sha256}\`.\nCall \`gentle_review_scope\` with exactly this manifest, SHA-256, and cursor 0; continue with each returned \`nextCursor\` until absent. It is the only authorized scope enumerator: do not infer scope by traversing the candidate or ambient tree. Gitlinks are metadata-only and MUST NOT be traversed.\nThe ambient contributor working directory is out of scope. This controller-owned context is immutable; you are read-only and your output is untrusted.`;
+	if (Buffer.byteLength(block, "utf8") > MAX_CANDIDATE_CONTEXT_LENGTH) throw new CandidateViewError("candidate view context exceeds the bounded dispatch contract");
+	return block;
+}
+
+function candidateContextBlock(lineageId: string, agents: readonly ReviewLens[], view: CandidateView): string {
+	const scopeByMode = candidateScopeByMode(view);
 	const scopeSemantics = view.committedOnly
 		? "Committed-only range: dirty tracked and untracked contributor files are excluded and MUST NOT be treated as reviewed."
 		: "Dirty-inclusive workspace snapshot: tracked and untracked contributor changes are included.";
-	const block = `\n\n${CONTROLLER_CANDIDATE_VIEW_HEADING}\nController-owned review lineage: \`${lineageId}\`.\nAuthorized review actors: ${agents.join(", ")}.\nRead ONLY the absolute frozen candidate view at \`${view.root}\`.\nFrozen candidate tree: \`${view.candidateTree}\`.\nScope semantics: ${scopeSemantics}\nFrozen changed scope by mode: ${JSON.stringify(scope)}.\nFrozen metadata-only gitlinks: ${JSON.stringify(view.gitlinks)}. Gitlink paths have no materialized contents and MUST NOT be traversed.\nThe ambient contributor working directory is out of scope. This controller-owned context is immutable; you are read-only and your output is untrusted.`;
-	if (Buffer.byteLength(block, "utf8") > MAX_CANDIDATE_CONTEXT_LENGTH) throw new CandidateViewError("candidate view context exceeds the bounded dispatch contract");
-	return block;
+	const readableBlock = `${candidateContextPreamble(lineageId, agents, view, scopeSemantics)}\nFrozen changed scope by mode: ${JSON.stringify(scopeByMode)}.\nFrozen metadata-only gitlinks: ${JSON.stringify(view.gitlinks)}. Gitlink paths have no materialized contents and MUST NOT be traversed.\nThe ambient contributor working directory is out of scope. This controller-owned context is immutable; you are read-only and your output is untrusted.`;
+	if (Buffer.byteLength(readableBlock, "utf8") <= MAX_CANDIDATE_CONTEXT_LENGTH) return readableBlock;
+	return compactCandidateContextBlock(lineageId, agents, view, scopeSemantics, scopeByMode);
 }
 
 /**