gentle-pi 2.1.2 → 2.3.0

package/tests/review-candidate-view.test.ts

@@ -1,17 +1,23 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
+import { gzipSync } from "node:zlib";
 import {
 	CandidateViewRegistry,
 	CandidateViewError,
 	type CandidateGitExecutor,
 	createCandidateView,
+	decodeCandidateContextManifest,
 	deriveChangedPathManifest,
 	digestChangedPathManifest,
 	injectReviewCandidateView,
+	readCandidateContextManifestPage,
 } from "../lib/review-candidate-view.ts";
 
 function git(cwd: string, ...arguments_: string[]): string {
@@ -28,14 +34,153 @@ function repository(t: test.TestContext): string {
 	return cwd;
 }
 
-test("candidate view Git commands have a finite timeout and block materialization before worktree execution", (t) => {
-	const calls: Array<{ arguments: readonly string[]; timeout: number | undefined }> = [];
-	const executor: CandidateGitExecutor = (_file, arguments_, options) => { calls.push({ arguments: arguments_, timeout: options.timeout }); throw Object.assign(new Error("timed out"), { code: "ETIMEDOUT", killed: true }); };
-	assert.throws(() => new CandidateViewRegistry(executor).create({ contributorRoot: repository(t) }), (error: unknown) => error instanceof CandidateViewError && /timed out/.test(error.message));
-	assert.deepEqual(calls, [{ arguments: ["rev-parse", "--git-common-dir"], timeout: 10_000 }]);
+function compactCandidateContextManifest(task: string): { encoded: string; sha256: string } {
+	const match = /Frozen changed scope manifest \(gzip\+base64url\): `([A-Za-z0-9_-]+)`\.\nFrozen changed scope manifest SHA-256: `([0-9a-f]{64})`\./.exec(task);
+	assert.ok(match, "expected a compact candidate context manifest");
+	return { encoded: match[1]!, sha256: match[2]! };
+}
+
+test("candidate view Git commands classify bounded timeouts and block materialization before worktree execution", (t) => {
+	const calls: Array<{ arguments: readonly string[]; timeout: number | undefined; maxBuffer: number | undefined }> = [];
+	const executor: CandidateGitExecutor = (_file, arguments_, options) => { calls.push({ arguments: arguments_, timeout: options.timeout, maxBuffer: options.maxBuffer }); throw Object.assign(new Error("timed out"), { code: "ETIMEDOUT", killed: true }); };
+	let failure: unknown;
+	try {
+		new CandidateViewRegistry(executor).create({ contributorRoot: repository(t) });
+	} catch (error) {
+		failure = error;
+	}
+	assert.ok(failure instanceof CandidateViewError);
+	assert.equal(failure.reason, "candidate-view-timeout");
+	assert.deepEqual((failure as CandidateViewError & { diagnostics?: unknown }).diagnostics, {
+		phase: "candidate-view",
+		category: "timeout",
+		git_subcommand: "rev-parse",
+		timeout_ms: 10_000,
+		max_buffer_bytes: 64 * 1024 * 1024,
+		message: "candidate-view Git command rev-parse timed out after 10000ms; inspect the candidate state before any new START",
+	});
+	assert.deepEqual(calls, [{ arguments: ["rev-parse", "--git-common-dir"], timeout: 10_000, maxBuffer: 64 * 1024 * 1024 }]);
 	assert.equal(calls.some((call) => call.arguments[0] === "worktree"), false);
 });
 
+test("candidate-view Git timeouts use a bounded strict-decimal override with safe fallback", (t) => {
+	const withTimeout = <T>(value: string | undefined, callback: () => T): T => {
+		const previous = process.env.GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS;
+		try {
+			if (value === undefined) delete process.env.GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS;
+			else process.env.GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS = value;
+			return callback();
+		} finally {
+			if (previous === undefined) delete process.env.GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS;
+			else process.env.GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS = previous;
+		}
+	};
+	for (const [name, value, expected] of [
+		["default", undefined, 10_000],
+		["valid override", "45000", 45_000],
+		...(["", "0", "0010", "-1", "1.5", "not-a-number", "120001", "Infinity"] as const).map((value) => [`invalid override ${JSON.stringify(value)}`, value, 10_000] as const),
+	] as const) {
+		const timeouts: Array<number | undefined> = [];
+		let failure: unknown;
+		withTimeout(value, () => {
+			try {
+				new CandidateViewRegistry((_file, _arguments, options) => {
+					timeouts.push(options.timeout);
+					throw Object.assign(new Error("timed out"), { code: "ETIMEDOUT" });
+				}).create({ contributorRoot: repository(t) });
+			} catch (error) {
+				failure = error;
+			}
+		});
+		assert.ok(failure instanceof CandidateViewError, name);
+		assert.equal(timeouts[0], expected, name);
+		assert.equal((failure as CandidateViewError & { diagnostics?: { timeout_ms?: unknown } }).diagnostics?.timeout_ms, expected, name);
+	}
+});
+
+test("explicit base resolution preserves structured for-each-ref output-limit diagnostics", (t) => {
+	const contributorRoot = repository(t);
+	const executor: CandidateGitExecutor = (file, arguments_, options) => {
+		if (arguments_[0] === "for-each-ref") throw Object.assign(new Error("sensitive base-reference output"), { code: "ENOBUFS", killed: true, stderr: Buffer.from("sensitive base-reference output") });
+		return execFileSync(file, arguments_, options);
+	};
+	let failure: unknown;
+	try {
+		new CandidateViewRegistry(executor).create({ contributorRoot, baseRef: "refs/heads/main", committedOnly: true });
+	} catch (error) {
+		failure = error;
+	}
+	assert.ok(failure instanceof CandidateViewError);
+	assert.equal(failure.reason, "candidate-view-output-limit");
+	assert.deepEqual(failure.diagnostics, {
+		phase: "candidate-view",
+		category: "output-limit",
+		git_subcommand: "for-each-ref",
+		timeout_ms: 10_000,
+		max_buffer_bytes: 64 * 1024 * 1024,
+		message: "candidate-view Git command for-each-ref exceeded the 67108864-byte output limit; inspect the candidate state before any new START",
+	});
+	assert.doesNotMatch(failure.message, /sensitive base-reference output/);
+});
+
+test("every synchronous candidate-view Git command receives the explicit 64 MiB output limit", (t) => {
+	const calls: Array<{ arguments: readonly string[]; maxBuffer: number | undefined }> = [];
+	const executor: CandidateGitExecutor = (file, arguments_, options) => {
+		calls.push({ arguments: arguments_, maxBuffer: options.maxBuffer });
+		return execFileSync(file, arguments_, options);
+	};
+	const view = new CandidateViewRegistry(executor).create({ contributorRoot: repository(t) });
+	try {
+		assert.ok(calls.length > 1);
+		assert.ok(calls.every((call) => call.maxBuffer === 64 * 1024 * 1024), JSON.stringify(calls));
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("candidate view classifies both Node synchronous-process output-limit errors ahead of killed state without exposing process output", (t) => {
+	const attemptedOutputBytes = 64 * 1024 * 1024 + 1;
+	for (const code of ["ENOBUFS", "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"]) {
+		let failure: unknown;
+		try {
+			new CandidateViewRegistry((_file, _arguments, options) => {
+				assert.ok((options.maxBuffer ?? 0) < attemptedOutputBytes, code);
+				throw Object.assign(new Error("sensitive stderr and candidate bytes"), { code, killed: true, stderr: Buffer.from("sensitive stderr and candidate bytes") });
+			}).create({ contributorRoot: repository(t) });
+		} catch (error) {
+			failure = error;
+		}
+		assert.ok(failure instanceof CandidateViewError, code);
+		assert.equal(failure.reason, "candidate-view-output-limit", code);
+		assert.deepEqual((failure as CandidateViewError & { diagnostics?: unknown }).diagnostics, {
+			phase: "candidate-view",
+			category: "output-limit",
+			git_subcommand: "rev-parse",
+			timeout_ms: 10_000,
+			max_buffer_bytes: 64 * 1024 * 1024,
+			message: "candidate-view Git command rev-parse exceeded the 67108864-byte output limit; inspect the candidate state before any new START",
+		}, code);
+		assert.doesNotMatch(failure.message, /sensitive stderr|candidate bytes/, code);
+	}
+});
+
+test("candidate Git accepts deterministic output above 1 MiB up to its explicit bound", () => {
+	const row = `:100644 100644 ${"a".repeat(40)} ${"b".repeat(40)} M\0tracked.txt\0`;
+	const copies = Math.ceil((1024 * 1024 + 1) / Buffer.byteLength(row));
+	const output = Buffer.from(row.repeat(copies));
+	assert.ok(output.length > 1024 * 1024);
+	assert.ok(output.length < 64 * 1024 * 1024);
+	const calls: Array<{ maxBuffer: number | undefined }> = [];
+	const manifest = deriveChangedPathManifest("/candidate", "a".repeat(40), "b".repeat(40), (_file, arguments_, options) => {
+		assert.deepEqual(arguments_.slice(0, 2), ["diff", "--raw"]);
+		calls.push({ maxBuffer: options.maxBuffer });
+		return output;
+	});
+	assert.equal(manifest.length, copies);
+	assert.ok(manifest.every((entry) => entry.path === "tracked.txt" && entry.status === "M"));
+	assert.deepEqual(calls, [{ maxBuffer: 64 * 1024 * 1024 }]);
+});
+
 test("committed-only candidate views scope an explicit base to committed changes and exclude dirty worktree files", (t) => {
 	const contributorRoot = repository(t);
 	const baseCommit = git(contributorRoot, "rev-parse", "HEAD");
@@ -170,6 +315,27 @@ function commitFileAfterBase(cwd: string): void {
 	git(cwd, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "committed after base");
 }
 
+// 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. `mktree` with empty input derives that empty
+// tree object-format-aware (sha1 or sha256) without hardcoding the SHA-1 id.
+function emptyTreeOf(cwd: string): string {
+	return execFileSync("git", ["-C", cwd, "mktree"], { encoding: "utf8", input: "" }).trim();
+}
+
+function unbornRepository(t: test.TestContext, stage = true): string {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-candidate-view-unborn-"));
+	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	git(cwd, "init", "-b", "main");
+	git(cwd, "config", "user.name", "Candidate Test");
+	git(cwd, "config", "user.email", "candidate@example.invalid");
+	if (stage) {
+		writeFileSync(join(cwd, "staged.txt"), "first staged\n");
+		git(cwd, "add", "staged.txt");
+	}
+	return cwd;
+}
+
 test("candidate view materializes exact tracked and initially-untracked content while contributor diverges", (t) => {
 	const contributorRoot = repository(t);
 	writeFileSync(join(contributorRoot, "tracked.txt"), "frozen tracked\n");
@@ -187,6 +353,66 @@ test("candidate view materializes exact tracked and initially-untracked content
 	view.cleanup();
 });
 
+test("candidate view preserves staged additions with explicit intended-untracked selection in its private index", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "tracked selection\n");
+	writeFileSync(join(contributorRoot, "staged-addition.txt"), "staged addition\n");
+	git(contributorRoot, "add", "staged-addition.txt");
+	git(contributorRoot, "update-index", "--split-index");
+	writeFileSync(join(contributorRoot, "selected.txt"), "selected\n");
+	writeFileSync(join(contributorRoot, "excluded.txt"), "excluded\n");
+	const indexBefore = readFileSync(join(contributorRoot, ".git", "index"));
+	const all = createCandidateView({ contributorRoot });
+	const excluded = createCandidateView({ contributorRoot, intendedUntracked: [] });
+	const selected = createCandidateView({ contributorRoot, intendedUntracked: ["selected.txt"] });
+	try {
+		assert.deepEqual(all.paths, ["excluded.txt", "selected.txt", "staged-addition.txt", "tracked.txt"]);
+		assert.deepEqual(excluded.paths, ["staged-addition.txt", "tracked.txt"]);
+		assert.deepEqual(selected.paths, ["selected.txt", "staged-addition.txt", "tracked.txt"]);
+		assert.equal(readFileSync(join(selected.root, "staged-addition.txt"), "utf8"), "staged addition\n");
+		assert.equal(lstatSync(join(selected.root, "excluded.txt"), { throwIfNoEntry: false }), undefined);
+		assert.deepEqual(readFileSync(join(contributorRoot, ".git", "index")), indexBefore);
+	} finally {
+		all.cleanup();
+		excluded.cleanup();
+		selected.cleanup();
+	}
+});
+
+test("candidate view skips a shared index that disappears during stat or copy", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "tracked selection\n");
+	writeFileSync(join(contributorRoot, "staged-addition.txt"), "staged addition\n");
+	git(contributorRoot, "add", "staged-addition.txt");
+	git(contributorRoot, "update-index", "--split-index");
+	const sharedIndexName = readdirSync(join(contributorRoot, ".git")).find((name) => /^sharedindex\.[0-9a-f]+$/.test(name));
+	assert.ok(sharedIndexName, "split index must create a shared index fixture");
+	const sharedIndexPath = join(contributorRoot, ".git", sharedIndexName);
+	for (const phase of ["stat", "copy"] as const) {
+		const originalLstatSync = fs.lstatSync;
+		const originalCopyFileSync = fs.copyFileSync;
+		fs.lstatSync = ((path: string | Buffer, options?: Parameters<typeof lstatSync>[1]) => {
+			if (phase === "stat" && path === sharedIndexPath) throw Object.assign(new Error("shared index disappeared"), { code: "ENOENT" });
+			return originalLstatSync(path, options);
+		}) as typeof fs.lstatSync;
+		fs.copyFileSync = ((source: string | Buffer, destination: string | Buffer) => {
+			if (phase === "copy" && source === sharedIndexPath) throw Object.assign(new Error("shared index disappeared"), { code: "ENOENT" });
+			return originalCopyFileSync(source, destination);
+		}) as typeof fs.copyFileSync;
+		syncBuiltinESMExports();
+		let view: ReturnType<typeof createCandidateView> | undefined;
+		try {
+			view = createCandidateView({ contributorRoot, intendedUntracked: [] });
+			assert.equal(view.paths.includes("staged-addition.txt"), true, phase);
+		} finally {
+			fs.lstatSync = originalLstatSync;
+			fs.copyFileSync = originalCopyFileSync;
+			syncBuiltinESMExports();
+			view?.cleanup();
+		}
+	}
+});
+
 test("candidate view recursively protects nested content and worktree metadata, and rejects injected untracked entries", (t) => {
 	const contributorRoot = repository(t);
 	mkdirSync(join(contributorRoot, "nested", "deeper"), { recursive: true });
@@ -231,6 +457,56 @@ test("candidate view registry rejects unsafe, moved, writable, stale, and unsele
 	registry.cleanup(view.token);
 });
 
+test("candidate registry isolates replay, projection, current, and cleanup state by target root plus lineage", (t) => {
+	const rootA = repository(t);
+	const rootB = repository(t);
+	writeFileSync(join(rootA, "tracked.txt"), "candidate A\n");
+	writeFileSync(join(rootB, "tracked.txt"), "candidate B\n");
+	const registry = new CandidateViewRegistry();
+	t.after(() => registry.cleanupAll());
+	const viewA = registry.createOrReuse({ contributorRoot: rootA, replayKey: "same-replay" });
+	const viewB = registry.createOrReuse({ contributorRoot: rootB, replayKey: "same-replay" });
+	assert.notEqual(viewA.token, viewB.token);
+	registry.bindCurrent({ token: viewA.token, lineageId: "same-lineage", selectedLenses: ["review-reliability"] });
+	registry.bindCurrent({ token: viewB.token, lineageId: "same-lineage", selectedLenses: ["review-reliability"] });
+	assert.equal(registry.resolveForLens("same-lineage", "review-reliability", rootA).root, viewA.root);
+	assert.equal(registry.resolveForLens("same-lineage", "review-reliability", rootB).root, viewB.root);
+	assert.equal(registry.resolveForFinalize("same-lineage", rootA).root, viewA.root);
+	assert.equal(registry.resolveForFinalize("same-lineage", rootB).root, viewB.root);
+	writeFileSync(join(rootA, "tracked.txt"), "corrected A\n");
+	writeFileSync(join(rootB, "tracked.txt"), "corrected B\n");
+	const correctedA = registry.createCorrected("same-lineage", rootA, "same-correction-replay");
+	const correctedB = registry.createCorrected("same-lineage", rootB, "same-correction-replay");
+	assert.notEqual(correctedA.token, correctedB.token);
+	registry.promoteCorrected("same-lineage", correctedA.token, rootA);
+	registry.promoteCorrected("same-lineage", correctedB.token, rootB);
+	assert.equal(registry.resolveForFinalize("same-lineage", rootA).root, correctedA.root);
+	assert.equal(registry.resolveForFinalize("same-lineage", rootB).root, correctedB.root);
+	assert.throws(() => registry.resolveForLens("same-lineage", "review-reliability"), /workspaceRoot/);
+	assert.throws(() => registry.resolveWorkspaceRoot("same-lineage"), /workspaceRoot/);
+	registry.cleanupTerminal("same-lineage", "approved", rootB);
+	assert.equal(registry.resolveWorkspaceRoot("same-lineage"), realpathSync(rootA));
+	assert.equal(registry.resolveForFinalize("same-lineage", rootA).root, correctedA.root);
+	registry.cleanupTerminal("same-lineage", "approved", rootA);
+});
+
+test("candidate registry rejects a lineage target whose authorized symlink was replaced", (t) => {
+	const root = repository(t);
+	const replacement = repository(t);
+	const alias = join(tmpdir(), `gentle-pi-candidate-alias-${process.pid}-${Date.now()}`);
+	t.after(() => rmSync(alias, { recursive: true, force: true }));
+	symlinkSync(root, alias, "dir");
+	const registry = new CandidateViewRegistry();
+	t.after(() => registry.cleanupAll());
+	const view = registry.create({ contributorRoot: root });
+	registry.bindCurrent({ token: view.token, lineageId: "symlink-lineage", selectedLenses: ["review-reliability"] });
+	assert.doesNotThrow(() => registry.assertWorkspaceRoot("symlink-lineage", alias));
+	rmSync(alias, { recursive: true, force: true });
+	symlinkSync(replacement, alias, "dir");
+	assert.throws(() => registry.assertWorkspaceRoot("symlink-lineage", alias), /workspaceRoot|bound to/);
+	registry.cleanupTerminal("symlink-lineage", "approved", root);
+});
+
 test("review subagent dispatch rejects missing candidate views and uses the explicitly current overlapping lens", (t) => {
 	const missing = new CandidateViewRegistry();
 	assert.throws(
@@ -270,6 +546,16 @@ test("candidate view cleanup is confined and idempotent", (t) => {
 	assert.equal(lstatSync(view.root, { throwIfNoEntry: false }), undefined);
 });
 
+test("candidate cleanup removes a readonly root when Git reports success without deleting it", (t) => {
+	const registry = new CandidateViewRegistry((file, arguments_, options) =>
+		arguments_[0] === "worktree" && arguments_[1] === "remove" ? "" : execFileSync(file, arguments_, options));
+	const view = registry.create({ contributorRoot: repository(t) });
+	assert.equal(lstatSync(view.root).mode & 0o222, 0);
+	view.cleanup();
+	view.cleanup();
+	assert.equal(lstatSync(view.root, { throwIfNoEntry: false }), undefined);
+});
+
 test("corrected views stay within frozen scope and replace projections only when promoted", (t) => {
 	const contributorRoot = repository(t);
 	writeFileSync(join(contributorRoot, "tracked.txt"), "reviewed\n");
@@ -354,13 +640,16 @@ test("candidate view derives deletion, rename, executable, and symlink scope fro
 	const registry = new CandidateViewRegistry();
 	const view = registry.create({ contributorRoot });
 	try {
-		assert.deepEqual(view.paths, ["deleted.txt", "linked.sh", "renamed.txt", "script.sh"]);
-		assert.deepEqual(view.deletedPaths, ["deleted.txt"]);
+		// The rename source (tracked.txt) is frozen as a deletion next to its
+		// destination: native STATUS projects the rename as both paths
+		// (gentle-pi#518), and the reviewer scope carries the same identity.
+		assert.deepEqual(view.paths, ["deleted.txt", "linked.sh", "renamed.txt", "script.sh", "tracked.txt"]);
+		assert.deepEqual(view.deletedPaths, ["deleted.txt", "tracked.txt"]);
 		assert.deepEqual(view.modes, { "linked.sh": "120000", "renamed.txt": "100644", "script.sh": "100755" });
 		registry.bind({ token: view.token, lineageId: "scope-kinds", selectedLenses: ["review-risk"] });
 		const dispatch = { agent: "review-risk", task: "review", mode: "task" };
 		injectReviewCandidateView(dispatch, registry);
-		assert.match(dispatch.task, /Frozen changed scope by mode: .*"deleted":\["deleted\.txt"\]/);
+		assert.match(dispatch.task, /Frozen changed scope by mode: .*"deleted":\["deleted\.txt","tracked\.txt"\]/);
 		assert.doesNotMatch(dispatch.task, /Frozen paths:|Frozen modes:/);
 		view.verify();
 	} finally {
@@ -368,6 +657,40 @@ test("candidate view derives deletion, rename, executable, and symlink scope fro
 	}
 });
 
+// gentle-pi#518: native STATUS projects every path whose state changed between
+// the frozen trees (Go diffs with --no-renames), so a staged exact rename is
+// its source deletion plus its destination addition. The candidate view must
+// project the same identity or ordinary START is rejected before native
+// admission with candidate-target-projection-drift.
+test("candidate view projects a staged exact rename as its source and destination, matching the native no-renames projection", (t) => {
+	const contributorRoot = repository(t);
+	mkdirSync(join(contributorRoot, "active"));
+	writeFileSync(join(contributorRoot, "active", "document.md"), "line one\nline two\n");
+	git(contributorRoot, "add", "active/document.md");
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "rename base");
+	mkdirSync(join(contributorRoot, "archive"));
+	git(contributorRoot, "mv", "active/document.md", "archive/document.md");
+	writeFileSync(join(contributorRoot, "report.md"), "report\n");
+	git(contributorRoot, "add", "-A");
+	const view = createCandidateView({ contributorRoot });
+	try {
+		const nativeProjection = git(contributorRoot, "diff-tree", "--no-commit-id", "--name-only", "-r", "-z", "--no-renames", view.baseTree, view.candidateTree)
+			.split("\0").filter((path) => path.length > 0).sort();
+		assert.deepEqual(nativeProjection, ["active/document.md", "archive/document.md", "report.md"]);
+		assert.deepEqual(view.paths, nativeProjection);
+		assert.deepEqual(view.deletedPaths, ["active/document.md"]);
+		assert.deepEqual(view.modes, { "archive/document.md": "100644", "report.md": "100644" });
+		const manifest = deriveChangedPathManifest(contributorRoot, view.baseTree, view.candidateTree);
+		assert.deepEqual(manifest.map((entry) => [entry.path, entry.status, entry.deleted]), [
+			["active/document.md", "D", true],
+			["archive/document.md", "A", false],
+			["report.md", "A", false],
+		]);
+	} finally {
+		view.cleanup();
+	}
+});
+
 test("candidate view verifies unchanged tree entries even when they are absent from changed scope", (t) => {
 	const contributorRoot = repository(t);
 	writeFileSync(join(contributorRoot, "unchanged.txt"), "base\n");
@@ -388,15 +711,121 @@ test("candidate view verifies unchanged tree entries even when they are absent f
 	}
 });
 
-test("candidate view fails closed before dispatch when the changed scope itself exceeds 4096 bytes", (t) => {
+test("candidate view compacts an oversized non-ASCII scope losslessly and deterministically", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "deleted.txt"), "delete me\n");
+	git(contributorRoot, "add", "deleted.txt");
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "deletion base");
+	const baseCommit = git(contributorRoot, "rev-parse", "HEAD");
+	const unicodePaths = Array.from({ length: 18 }, (_, index) => `changed-${String(index).padStart(2, "0")}-${"界".repeat(70)}.txt`);
+	for (const path of unicodePaths) writeFileSync(join(contributorRoot, path), "candidate\n");
+	const gitlinkCommit = "0123456789abcdef0123456789abcdef01234567";
+	git(contributorRoot, "add", ...unicodePaths);
+	git(contributorRoot, "update-index", "--add", "--cacheinfo", `160000,${gitlinkCommit},vendor/dependency`);
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "large scope");
+	rmSync(join(contributorRoot, "deleted.txt"));
+	git(contributorRoot, "add", "-u", "--", "deleted.txt");
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "delete scope path");
+	const registry = new CandidateViewRegistry();
+	const view = registry.create({ contributorRoot, baseRef: baseCommit, committedOnly: true });
+	try {
+		registry.bind({ token: view.token, lineageId: "oversized-scope", selectedLenses: ["review-risk"] });
+		const first = { agent: "review-risk", task: "review", mode: "task" };
+		const second = { agent: "review-risk", task: "review", mode: "task" };
+		injectReviewCandidateView(first, registry);
+		injectReviewCandidateView(second, registry);
+		const compact = compactCandidateContextManifest(first.task);
+		assert.deepEqual(compact, compactCandidateContextManifest(second.task));
+		const decoded = decodeCandidateContextManifest(compact.encoded, compact.sha256);
+		assert.deepEqual(decoded.manifest, {
+			version: 1,
+			scopeByMode: { "100644": unicodePaths, "160000": ["vendor/dependency"], deleted: ["deleted.txt"] },
+			gitlinks: { "vendor/dependency": gitlinkCommit },
+		});
+		assert.equal(decoded.sha256, createHash("sha256").update(decoded.bytes).digest("hex"));
+		assert.ok(JSON.stringify(decoded.manifest).length < 4_096, "UTF-16 code units alone must not decide the dispatch bound");
+		assert.ok(decoded.bytes.length > 4_096, "the manifest must retain its full non-ASCII UTF-8 byte sequence");
+		const actorEntries: Array<{ path: string; mode: string; gitlinkObjectId?: string }> = [];
+		let cursor: number | undefined = 0;
+		while (cursor !== undefined) {
+			const page = readCandidateContextManifestPage(compact.encoded, compact.sha256, cursor);
+			actorEntries.push(...page.entries);
+			assert.ok(Buffer.byteLength(JSON.stringify(page), "utf8") <= 16 * 1024);
+			cursor = page.nextCursor;
+		}
+		assert.deepEqual(actorEntries, [
+			...unicodePaths.map((path) => ({ path, mode: "100644" })),
+			{ path: "vendor/dependency", mode: "160000", gitlinkObjectId: gitlinkCommit },
+			{ path: "deleted.txt", mode: "deleted" },
+		]);
+		assert.ok(Buffer.byteLength(first.task, "utf8") <= Buffer.byteLength("review", "utf8") + 4_096);
+		assert.doesNotMatch(first.task, /Frozen changed scope by mode:/);
+		assert.match(first.task, /Call `gentle_review_scope`/);
+		assert.throws(() => decodeCandidateContextManifest(compact.encoded, `${compact.sha256.slice(0, -1)}0`), /integrity/);
+		assert.throws(() => readCandidateContextManifestPage(compact.encoded, compact.sha256, actorEntries.length + 1), /cursor/);
+		const nonCanonicalBytes = Buffer.from(JSON.stringify({ gitlinks: decoded.manifest.gitlinks, scopeByMode: decoded.manifest.scopeByMode, version: 1 }), "utf8");
+		assert.throws(
+			() => decodeCandidateContextManifest(gzipSync(nonCanonicalBytes, { mtime: 0 }).toString("base64url"), createHash("sha256").update(nonCanonicalBytes).digest("hex")),
+			/canonical/,
+		);
+	} finally {
+		registry.cleanup(view.token);
+	}
+});
+
+test("candidate context manifest decoder accepts canonical numeric-looking gitlink paths", () => {
+	const gitlinks = {
+		"10": "0123456789abcdef0123456789abcdef01234567",
+		"2": "89abcdef0123456789abcdef0123456789abcdef",
+	};
+	const bytes = Buffer.from(JSON.stringify({
+		version: 1,
+		scopeByMode: { "160000": ["10", "2"] },
+		gitlinks,
+	}), "utf8");
+	const encoded = gzipSync(bytes, { mtime: 0 }).toString("base64url");
+	assert.deepEqual(decodeCandidateContextManifest(encoded, createHash("sha256").update(bytes).digest("hex")).manifest, {
+		version: 1,
+		scopeByMode: { "160000": ["10", "2"] },
+		gitlinks,
+	});
+});
+
+test("candidate context manifest decoder rejects noncanonical nonnumeric gitlink ordering", () => {
+	const gitlinks = {
+		zeta: "0123456789abcdef0123456789abcdef01234567",
+		alpha: "89abcdef0123456789abcdef0123456789abcdef",
+	};
+	const bytes = Buffer.from(JSON.stringify({
+		version: 1,
+		scopeByMode: { "160000": ["alpha", "zeta"] },
+		gitlinks,
+	}), "utf8");
+	assert.throws(
+		() => decodeCandidateContextManifest(gzipSync(bytes, { mtime: 0 }).toString("base64url"), createHash("sha256").update(bytes).digest("hex")),
+		/canonical/,
+	);
+});
+
+test("candidate context manifest decoder rejects noncanonical gzip transport for verified bytes", () => {
+	const bytes = Buffer.from(JSON.stringify({ version: 1, scopeByMode: { "100644": ["file.ts"] }, gitlinks: {} }), "utf8");
+	const sha256 = createHash("sha256").update(bytes).digest("hex");
+	const canonical = gzipSync(bytes, { mtime: 0 });
+	const noncanonical = Buffer.from(canonical);
+	noncanonical[4] = (noncanonical[4]! + 1) & 0xff;
+	assert.throws(() => decodeCandidateContextManifest(noncanonical.toString("base64url"), sha256), /canonical/);
+});
+
+test("candidate view fails closed when an incompressible compact scope exceeds 4096 UTF-8 bytes", (t) => {
 	const contributorRoot = repository(t);
 	for (let index = 0; index < 80; index += 1) {
-		writeFileSync(join(contributorRoot, `changed-${String(index).padStart(3, "0")}-${"x".repeat(80)}.txt`), "candidate\n");
+		const entropy = createHash("sha512").update(`candidate-scope-${index}`).digest("hex");
+		writeFileSync(join(contributorRoot, `changed-${String(index).padStart(3, "0")}-${entropy}.txt`), "candidate\n");
 	}
 	const registry = new CandidateViewRegistry();
 	const view = registry.create({ contributorRoot });
 	try {
-		registry.bind({ token: view.token, lineageId: "oversized-scope", selectedLenses: ["review-risk"] });
+		registry.bind({ token: view.token, lineageId: "incompressible-scope", selectedLenses: ["review-risk"] });
 		assert.throws(
 			() => injectReviewCandidateView({ agent: "review-risk", task: "review", mode: "task" }, registry),
 			/candidate view context exceeds the bounded dispatch contract/,
@@ -562,6 +991,30 @@ test("candidate views freeze gitlinks as immutable metadata without materializin
 	}
 });
 
+test("native projection reconstruction retains its selected untracked subset", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "tracked selection\n");
+	writeFileSync(join(contributorRoot, "selected.txt"), "selected\n");
+	writeFileSync(join(contributorRoot, "excluded.txt"), "excluded\n");
+	const source = new CandidateViewRegistry();
+	const selected = source.create({ contributorRoot, intendedUntracked: ["selected.txt"] });
+	const restored = new CandidateViewRegistry();
+	try {
+		const view = restored.restoreForFinalizeFromNative("selected-native", contributorRoot, {
+			baseTree: selected.baseTree,
+			currentCandidateTree: selected.candidateTree,
+			paths: selected.paths,
+			intendedUntracked: ["selected.txt"],
+			projection: "workspace",
+		});
+		assert.deepEqual(view.paths, ["selected.txt", "tracked.txt"]);
+		assert.equal(lstatSync(join(view.root, "excluded.txt"), { throwIfNoEntry: false }), undefined);
+		view.cleanup();
+	} finally {
+		selected.cleanup();
+	}
+});
+
 test("native projections reconstruct symlink, intended-untracked, and gitlink identity from Git objects", (t) => {
 	const contributorRoot = repository(t);
 	const baseTree = git(contributorRoot, "rev-parse", "HEAD^{tree}");
@@ -690,6 +1143,229 @@ test("fresh registries restore only one exact authoritative reviewing candidate
 	}
 });
 
+interface CandidateViewRegistryInternals {
+	records: Map<string, unknown>;
+	bindRecord: (token: string, lineageId: string, selectedLenses: readonly unknown[]) => unknown;
+}
+
+function bindingFailureRegistry(t: test.TestContext): { registry: CandidateViewRegistry; materializedRoot: () => string | undefined; internals: CandidateViewRegistryInternals } {
+	let root: string | undefined;
+	const registry = new CandidateViewRegistry((file, arguments_, options) => {
+		if (arguments_[0] === "worktree" && arguments_[1] === "add") root = arguments_[arguments_.indexOf("--no-checkout") + 1];
+		return execFileSync(file, arguments_, options);
+	});
+	t.after(() => registry.cleanupAll());
+	return { registry, materializedRoot: () => root, internals: registry as unknown as CandidateViewRegistryInternals };
+}
+
+test("failed authoritative restores remove the inserted registry record and readonly worktree", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "reviewing\n");
+	const source = new CandidateViewRegistry();
+	const frozen = source.create({ contributorRoot });
+	const state = {
+		lineageId: "restore-bind-failure",
+		contributorRoot,
+		baseCommit: frozen.baseCommit,
+		baseTree: frozen.baseTree,
+		candidateTree: frozen.candidateTree,
+		paths: frozen.paths,
+		modes: frozen.modes,
+		deletedPaths: frozen.deletedPaths,
+		selectedLenses: ["review-reliability"],
+	};
+	const { registry, materializedRoot, internals } = bindingFailureRegistry(t);
+	const originalBindRecord = internals.bindRecord;
+	internals.bindRecord = (token) => {
+		assert.equal(internals.records.has(token), true, "the failure must occur after insertion");
+		throw new CandidateViewError("test-only bind failure");
+	};
+	try {
+		assert.throws(
+			() => registry.restoreCurrentFromAuthoritativeReviewingStates(contributorRoot, [state]),
+			CandidateViewError,
+		);
+	} finally {
+		internals.bindRecord = originalBindRecord;
+		source.cleanup(frozen.token);
+	}
+	assert.equal(internals.records.size, 0);
+	assert.ok(materializedRoot(), "the restore must have created a candidate worktree");
+	assert.equal(existsSync(materializedRoot()!), false);
+});
+
+test("failed finalize restores remove the inserted registry record and readonly worktree", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "candidate\n");
+	const source = new CandidateViewRegistry();
+	const frozen = source.create({ contributorRoot });
+	const { registry, materializedRoot, internals } = bindingFailureRegistry(t);
+	const originalBindRecord = internals.bindRecord;
+	internals.bindRecord = (token) => {
+		assert.equal(internals.records.has(token), true, "the failure must occur after insertion");
+		throw new CandidateViewError("test-only bind failure");
+	};
+	try {
+		assert.throws(
+			() => registry.restoreForFinalizeFromNative("finalize-bind-failure", contributorRoot, {
+				baseTree: frozen.baseTree,
+				currentCandidateTree: frozen.candidateTree,
+				paths: frozen.paths,
+				intendedUntracked: [],
+				projection: "workspace",
+			}),
+			CandidateViewError,
+		);
+	} finally {
+		internals.bindRecord = originalBindRecord;
+		source.cleanup(frozen.token);
+	}
+	assert.equal(internals.records.size, 0);
+	assert.ok(materializedRoot(), "the restore must have created a candidate worktree");
+	assert.equal(existsSync(materializedRoot()!), false);
+});
+
+function materializationFailureRegistry(t: test.TestContext, failureAt: number): { registry: CandidateViewRegistry; roots: () => readonly string[]; removalAttempts: (root: string) => number; internals: CandidateViewRegistryInternals } {
+	const roots: string[] = [];
+	const removalAttempts = new Map<string, number>();
+	let materializations = 0;
+	let failPending = true;
+	const registry = new CandidateViewRegistry((file, arguments_, options) => {
+		if (arguments_[0] === "worktree" && arguments_[1] === "add") {
+			const root = arguments_[arguments_.indexOf("--no-checkout") + 1];
+			assert.equal(typeof root, "string", "worktree add must name its candidate root");
+			roots.push(root);
+			materializations += 1;
+		}
+		if (arguments_[0] === "worktree" && arguments_[1] === "remove") {
+			const root = arguments_[arguments_.indexOf("--force") + 1];
+			assert.equal(typeof root, "string", "worktree remove must name its candidate root");
+			removalAttempts.set(root, (removalAttempts.get(root) ?? 0) + 1);
+		}
+		if (failPending && materializations === failureAt && options.cwd === roots.at(-1) && arguments_[0] === "read-tree") {
+			failPending = false;
+			throw Object.assign(new Error("test-only materialization failure"), { status: 1 });
+		}
+		return execFileSync(file, arguments_, options);
+	});
+	t.after(() => registry.cleanupAll());
+	return { registry, roots: () => roots, removalAttempts: (root) => removalAttempts.get(root) ?? 0, internals: registry as unknown as CandidateViewRegistryInternals };
+}
+
+test("finalize restore removes a registered projection when its first materialization fails and retries cleanly", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "candidate\n");
+	const source = new CandidateViewRegistry();
+	const frozen = source.create({ contributorRoot });
+	const lineageId = "finalize-materialization-failure";
+	const descriptor = {
+		baseTree: frozen.baseTree,
+		currentCandidateTree: frozen.candidateTree,
+		paths: frozen.paths,
+		intendedUntracked: [],
+		projection: "workspace" as const,
+	};
+	const baselineWorktrees = git(contributorRoot, "worktree", "list", "--porcelain");
+	const { registry, roots, internals } = materializationFailureRegistry(t, 1);
+	try {
+		assert.throws(() => registry.restoreForFinalizeFromNative(lineageId, contributorRoot, descriptor), CandidateViewError);
+		assert.equal(registry.hasProjection(lineageId, contributorRoot), false);
+		assert.equal(internals.records.size, 0);
+		assert.equal(git(contributorRoot, "worktree", "list", "--porcelain"), baselineWorktrees);
+		assert.equal(existsSync(roots()[0]!), false);
+
+		const restored = registry.restoreForFinalizeFromNative(lineageId, contributorRoot, descriptor);
+		assert.equal(registry.resolveForFinalize(lineageId, contributorRoot).token, restored.token);
+		registry.cleanup(restored.token);
+	} finally {
+		source.cleanup(frozen.token);
+	}
+});
+
+test("finalize restore does not re-remove its first fallback record when the empty-untracked retry materialization fails", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "candidate\n");
+	writeFileSync(join(contributorRoot, "excluded.txt"), "excluded\n");
+	const source = new CandidateViewRegistry();
+	const frozen = source.create({ contributorRoot, intendedUntracked: [] });
+	const lineageId = "finalize-fallback-materialization-failure";
+	const descriptor = {
+		baseTree: frozen.baseTree,
+		currentCandidateTree: frozen.candidateTree,
+		paths: frozen.paths,
+		intendedUntracked: [],
+		projection: "workspace" as const,
+	};
+	const baselineWorktrees = git(contributorRoot, "worktree", "list", "--porcelain");
+	const { registry, roots, removalAttempts, internals } = materializationFailureRegistry(t, 2);
+	try {
+		assert.throws(() => registry.restoreForFinalizeFromNative(lineageId, contributorRoot, descriptor), CandidateViewError);
+		assert.equal(removalAttempts(roots()[0]!), 1, "the first mismatched record must receive exactly one physical worktree removal");
+		assert.equal(registry.hasProjection(lineageId, contributorRoot), false);
+		assert.equal(internals.records.size, 0);
+		assert.equal(git(contributorRoot, "worktree", "list", "--porcelain"), baselineWorktrees);
+		assert.equal(existsSync(roots()[0]!), false);
+		assert.equal(existsSync(roots()[1]!), false);
+
+		const restored = registry.restoreForFinalizeFromNative(lineageId, contributorRoot, descriptor);
+		assert.equal(registry.resolveForFinalize(lineageId, contributorRoot).token, restored.token);
+		registry.cleanup(restored.token);
+	} finally {
+		source.cleanup(frozen.token);
+	}
+});
+
+test("dispatch restore removes a registered projection when materialization fails and records the hydration failure before retrying", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "candidate\n");
+	const source = new CandidateViewRegistry();
+	const frozen = source.create({ contributorRoot });
+	const lineageId = "dispatch-materialization-failure";
+	const descriptor = {
+		baseTree: frozen.baseTree,
+		currentCandidateTree: frozen.candidateTree,
+		paths: frozen.paths,
+		intendedUntracked: [],
+		projection: "workspace" as const,
+	};
+	const baselineWorktrees = git(contributorRoot, "worktree", "list", "--porcelain");
+	const { registry, roots, internals } = materializationFailureRegistry(t, 1);
+	try {
+		let failure: unknown;
+		try {
+			registry.restoreCurrentForDispatchFromNative(lineageId, contributorRoot, descriptor, ["review-reliability"]);
+		} catch (error) {
+			failure = error;
+		}
+		assert.ok(failure instanceof CandidateViewError);
+		assert.equal(registry.hasProjection(lineageId, contributorRoot), false);
+		assert.equal(registry.hasCurrentBinding(contributorRoot), false);
+		assert.equal(internals.records.size, 0);
+		assert.equal(git(contributorRoot, "worktree", "list", "--porcelain"), baselineWorktrees);
+		assert.equal(existsSync(roots()[0]!), false);
+		assert.deepEqual(registry.lastDispatchHydrationFailure(contributorRoot), {
+			lineageId,
+			reason: failure.reason,
+			message: failure.message,
+		});
+
+		registry.restoreCurrentForDispatchFromNative(lineageId, contributorRoot, descriptor, ["review-reliability"]);
+		const restored = registry.resolveCurrentForLens("review-reliability", contributorRoot);
+		assert.equal(registry.lastDispatchHydrationFailure(contributorRoot), undefined);
+		registry.cleanup(restored.token);
+	} finally {
+		source.cleanup(frozen.token);
+	}
+});
+
+test("candidate root resolution drift is exposed as a typed candidate-view error", () => {
+	const missingRoot = join(tmpdir(), `gentle-pi-missing-root-${process.pid}-${Date.now()}`);
+	assert.throws(
+		() => new CandidateViewRegistry().hasCurrentBinding(missingRoot),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "contributor-root-unresolvable",
+	);
+});
+
 test("live candidate drift blocks dispatch before candidate text can be injected", (t) => {
 	const contributorRoot = repository(t);
 	writeFileSync(join(contributorRoot, "tracked.txt"), "reviewed\n");
@@ -1039,3 +1715,213 @@ test("a projection labeled workspace but derived as a genuinely committed range
 		(error: unknown) => error instanceof CandidateViewError && error.reason === "projection-kind-drift",
 	);
 });
+
+test("candidate view treats an unborn staged repository base as Git's empty tree without needing HEAD^{commit}", (t) => {
+	const contributorRoot = unbornRepository(t);
+	const view = createCandidateView({ contributorRoot });
+	try {
+		const emptyTree = emptyTreeOf(contributorRoot);
+		assert.equal(view.baseTree, emptyTree);
+		assert.equal(view.baseCommit, "HEAD");
+		assert.equal(view.committedOnly, false);
+		assert.notEqual(view.candidateTree, emptyTree);
+		assert.deepEqual(view.paths, ["staged.txt"]);
+		assert.deepEqual(view.deletedPaths, []);
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("candidate view of an unborn repository with no content yields an empty candidate scope instead of a misleading base-ref failure", (t) => {
+	const contributorRoot = unbornRepository(t, false);
+	const view = createCandidateView({ contributorRoot });
+	try {
+		const emptyTree = emptyTreeOf(contributorRoot);
+		assert.equal(view.baseTree, emptyTree);
+		assert.equal(view.candidateTree, emptyTree);
+		assert.equal(view.baseCommit, "HEAD");
+		assert.deepEqual(view.paths, []);
+		assert.deepEqual(view.deletedPaths, []);
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("candidate view materializes an unborn staged repository without mutating the contributor index or creating a phantom commit", (t) => {
+	const contributorRoot = unbornRepository(t);
+	const indexBefore = readFileSync(join(contributorRoot, ".git", "index"));
+	const view = createCandidateView({ contributorRoot });
+	try {
+		// No phantom commit: HEAD stays unborn and no refs exist.
+		assert.throws(() => git(contributorRoot, "rev-parse", "--verify", "HEAD"), /fatal/i);
+		assert.equal(git(contributorRoot, "rev-list", "--all").length, 0);
+		// Contributor's real index is untouched; materialization uses a private index file.
+		assert.deepEqual(readFileSync(join(contributorRoot, ".git", "index")), indexBefore);
+		// The materialized candidate carries the staged content, isolated from the contributor tree.
+		assert.equal(readFileSync(join(view.root, "staged.txt"), "utf8"), "first staged\n");
+		assert.deepEqual(view.paths, ["staged.txt"]);
+	} finally {
+		view.cleanup();
+	}
+	// Cleanup removed the orphan worktree; no worktree lingers and no commit appeared.
+	assert.equal(git(contributorRoot, "worktree", "list").split("\n").filter((line) => line.includes("gentle-ai-candidate")).length, 0);
+	assert.equal(git(contributorRoot, "rev-list", "--all").length, 0);
+});
+
+test("candidate view fails closed for a detached HEAD pointing at a missing commit, not an unborn empty tree", (t) => {
+	const contributorRoot = unbornRepository(t);
+	// Detach HEAD to a non-existent object id. This is a corrupt/missing-object
+	// existing HEAD state, not a valid unborn symbolic HEAD, so it must fail
+	// closed rather than producing an empty-tree unborn candidate.
+	writeFileSync(join(contributorRoot, ".git", "HEAD"), "0".repeat(40));
+	let failure: unknown;
+	try {
+		createCandidateView({ contributorRoot });
+	} catch (error) {
+		failure = error;
+	}
+	assert.ok(failure instanceof CandidateViewError, "a detached missing HEAD must fail closed");
+	assert.notEqual((failure as CandidateViewError).reason, undefined);
+	assert.ok((failure as CandidateViewError).reason !== "base-ref-moved");
+});
+
+test("candidate view fails closed when symbolic HEAD target ref exists but points to a missing object, not unborn", (t) => {
+	const contributorRoot = repository(t);
+	// Break the main ref: it exists (show-ref --exists returns 0) but points to
+	// a missing object. This is a broken symbolic HEAD, not a valid unborn repo.
+	writeFileSync(join(contributorRoot, ".git", "refs", "heads", "main"), `${"0".repeat(40)}\n`);
+	let failure: unknown;
+	try {
+		createCandidateView({ contributorRoot });
+	} catch (error) {
+		failure = error;
+	}
+	assert.ok(failure instanceof CandidateViewError, "a broken symbolic HEAD must fail closed, not unborn");
+});
+
+test("candidate view probe does not convert a ref-existence probe timeout into an unborn empty-tree base", (t) => {
+	const contributorRoot = unbornRepository(t);
+	const executor: CandidateGitExecutor = (file, args, options) => {
+		if (args[0] === "rev-parse" && args.includes("--quiet")) throw Object.assign(new Error("timed out"), { code: "ETIMEDOUT", killed: true });
+		return execFileSync(file, args, options);
+	};
+	let failure: unknown;
+	try {
+		new CandidateViewRegistry(executor).create({ contributorRoot });
+	} catch (error) {
+		failure = error;
+	}
+	assert.ok(failure instanceof CandidateViewError, "ref-existence probe timeout must fail closed");
+	assert.equal((failure as CandidateViewError).reason, "candidate-view-timeout");
+});
+
+test("candidate view fails closed when the unborn ref probe exits with an unexpected status instead of treating it as unborn", (t) => {
+	const contributorRoot = unbornRepository(t);
+	// Only status 1 means "ref absent" (valid unborn). Any other nonzero status
+	// (128, etc.) signals corruption or an I/O failure and must fail closed,
+	// never masquerade as an unborn empty-tree base.
+	const executor: CandidateGitExecutor = (file, args, options) => {
+		if (args[0] === "rev-parse" && args.includes("--quiet")) throw Object.assign(new Error("fatal: probe failed"), { status: 128 });
+		return execFileSync(file, args, options);
+	};
+	let failure: unknown;
+	try {
+		new CandidateViewRegistry(executor).create({ contributorRoot });
+	} catch (error) {
+		failure = error;
+	}
+	assert.ok(failure instanceof CandidateViewError, "an unexpected unborn probe status must fail closed, not unborn");
+	assert.equal((failure as CandidateViewError).reason, "candidate-view-git-failure");
+});
+
+test("candidate view treats an unborn sha256 repository base as the repository-native sha256 empty tree", (t) => {
+	const contributorRoot = mkdtempSync(join(tmpdir(), "gentle-pi-candidate-view-unborn-sha256-"));
+	t.after(() => rmSync(contributorRoot, { recursive: true, force: true }));
+	try {
+		git(contributorRoot, "init", "--object-format=sha256", "-b", "main");
+	} catch {
+		t.skip("installed git does not support `git init --object-format=sha256`");
+		return;
+	}
+	git(contributorRoot, "config", "user.name", "Candidate Test");
+	git(contributorRoot, "config", "user.email", "candidate@example.invalid");
+	writeFileSync(join(contributorRoot, "staged.txt"), "first staged\n");
+	git(contributorRoot, "add", "staged.txt");
+	const view = createCandidateView({ contributorRoot });
+	try {
+		const emptyTree = emptyTreeOf(contributorRoot);
+		assert.equal(emptyTree.length, 64, "a sha256 repository must derive a 64-hex empty tree, not the hardcoded SHA-1 id");
+		assert.equal(view.baseTree, emptyTree);
+		assert.equal(view.baseCommit, "HEAD");
+		assert.equal(view.committedOnly, false);
+		assert.notEqual(view.candidateTree, emptyTree);
+		assert.deepEqual(view.paths, ["staged.txt"]);
+		assert.deepEqual(view.deletedPaths, []);
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("candidate view unborn worktree falls back when --orphan is unsupported, preserving isolation, no phantom commit, and contributor immutability", (t) => {
+	const contributorRoot = unbornRepository(t);
+	const indexBefore = readFileSync(join(contributorRoot, ".git", "index"));
+	// Intercept --orphan with status 129 (Git < 2.42 unknown option).
+	const executor: CandidateGitExecutor = (file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add" && args.includes("--orphan")) throw Object.assign(new Error("unknown option"), { status: 129 });
+		return execFileSync(file, args, options);
+	};
+	const view = new CandidateViewRegistry(executor).create({ contributorRoot });
+	try {
+		assert.equal(readFileSync(join(view.root, "staged.txt"), "utf8"), "first staged\n");
+		assert.deepEqual(view.paths, ["staged.txt"]);
+		assert.equal(view.baseTree, emptyTreeOf(contributorRoot));
+		// No phantom commit; contributor index untouched.
+		assert.throws(() => git(contributorRoot, "rev-parse", "--verify", "HEAD"), /fatal/i);
+		assert.equal(git(contributorRoot, "rev-list", "--all").length, 0);
+		assert.deepEqual(readFileSync(join(contributorRoot, ".git", "index")), indexBefore);
+	} finally {
+		view.cleanup();
+	}
+	assert.equal(git(contributorRoot, "worktree", "list").split("\n").filter((line) => line.includes("gentle-ai-candidate")).length, 0);
+	assert.equal(git(contributorRoot, "rev-list", "--all").length, 0);
+});
+
+test("candidate view unborn worktree propagates a non-usage --orphan failure instead of falling back", (t) => {
+	const contributorRoot = unbornRepository(t);
+	// A non-129 status must not trigger the fallback.
+	const calls: string[][] = [];
+	const executor: CandidateGitExecutor = (file, args, options) => {
+		calls.push([...args]);
+		if (args[0] === "worktree" && args[1] === "add" && args.includes("--orphan")) throw Object.assign(new Error("genuine failure"), { status: 128 });
+		return execFileSync(file, args, options);
+	};
+	let failure: unknown;
+	try { new CandidateViewRegistry(executor).create({ contributorRoot }); } catch (error) { failure = error; }
+	assert.ok(failure instanceof CandidateViewError, "a non-usage --orphan failure must propagate");
+	assert.equal((failure as CandidateViewError).reason, "candidate-view-git-failure");
+	assert.ok(!calls.some((args) => args[0] === "commit-tree"), "the fallback must not create a temporary commit");
+	assert.ok(!calls.some((args) => args[0] === "worktree" && args.includes("--detach")), "the fallback must not add a detached worktree");
+});
+
+test("candidate view cleans up a partially registered unborn fallback worktree when a later step fails", (t) => {
+	const contributorRoot = unbornRepository(t);
+	// Force the --orphan path to take the pre-2.42 fallback, then fail the
+	// symbolic-ref rewrite that follows `worktree add --no-checkout --detach`.
+	// The worktree is already registered with Git at that point; the cleanup
+	// boundary must remove both the registered worktree and its directory.
+	const executor: CandidateGitExecutor = (file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add" && args.includes("--orphan")) throw Object.assign(new Error("unknown option"), { status: 129 });
+		if (args[0] === "symbolic-ref") throw Object.assign(new Error("symbolic-ref failed"), { status: 1 });
+		return execFileSync(file, args, options);
+	};
+	let failure: unknown;
+	try { new CandidateViewRegistry(executor).create({ contributorRoot }); } catch (error) { failure = error; }
+	assert.ok(failure instanceof CandidateViewError, "the symbolic-ref failure must propagate");
+	assert.equal((failure as CandidateViewError).reason, "candidate-view-git-failure");
+	// No registered/admin worktree remains.
+	assert.equal(git(contributorRoot, "worktree", "list").split("\n").filter((line) => line.includes("gentle-ai-candidate")).length, 0);
+	// No candidate directory remains under the candidate-view parent.
+	const parent = join(realpathSync(git(contributorRoot, "rev-parse", "--path-format=absolute", "--git-common-dir")), "gentle-ai", "candidate-views");
+	const leftover = existsSync(parent) ? readdirSync(parent).filter((entry) => lstatSync(join(parent, entry)).isDirectory()) : [];
+	assert.deepEqual(leftover, [], "no candidate directory remains after a partial unborn fallback failure");
+});