gentle-pi 2.1.2 → 2.2.0

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

@@ -1,17 +1,21 @@
 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 { 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 +32,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 +313,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");
@@ -388,15 +552,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/,
@@ -1039,3 +1309,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");
+});