gentle-pi 2.4.0 → 2.6.0

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

@@ -1,16 +1,18 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
+import childProcess from "node:child_process";
 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 { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import test from "node:test";
 import { gzipSync } from "node:zlib";
 import {
 	CandidateViewRegistry,
 	CandidateViewError,
+	hasExpectedExecutableBits,
 	type CandidateGitExecutor,
 	createCandidateView,
 	decodeCandidateContextManifest,
@@ -18,7 +20,9 @@ import {
 	digestChangedPathManifest,
 	injectReviewCandidateView,
 	readCandidateContextManifestPage,
+	type NativeCandidateProjectionDescriptor,
 } from "../lib/review-candidate-view.ts";
+import { assertCandidateOwnerParent, assertTrustedWindowsOwner, prepareCandidateOwnerParent, setWindowsAclAuthorityForTesting, validatePrivateWindowsDacl, validatePrivateWindowsOwner, WindowsDaclValidationError, WindowsOwnerValidationError } from "../lib/review-candidate-view-owner.ts";
 
 function git(cwd: string, ...arguments_: string[]): string {
 	return execFileSync("git", arguments_, { cwd, encoding: "utf8" }).trim();
@@ -26,7 +30,10 @@ function git(cwd: string, ...arguments_: string[]): string {
 
 function repository(t: test.TestContext): string {
 	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-candidate-view-"));
-	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	t.after(() => {
+		if (process.platform !== "win32") execFileSync("chmod", ["-R", "u+rwx", cwd]);
+		rmSync(cwd, { recursive: true, force: true });
+	});
 	git(cwd, "init", "-b", "main");
 	writeFileSync(join(cwd, "tracked.txt"), "base\n");
 	git(cwd, "add", "tracked.txt");
@@ -34,6 +41,529 @@ function repository(t: test.TestContext): string {
 	return cwd;
 }
 
+function ownerMarker(root: string): string { return `${root}.owner.json`; }
+
+function mockWindowsAcl(t: test.TestContext): void {
+	setWindowsAclAuthorityForTesting(() => {});
+	t.after(() => setWindowsAclAuthorityForTesting());
+}
+
+function orphanFixture(t: test.TestContext) {
+	const cwd = repository(t);
+	const registry = new CandidateViewRegistry();
+	const view = registry.create({ contributorRoot: cwd });
+	const marker = ownerMarker(view.root);
+	const owner = JSON.parse(readFileSync(marker, "utf8"));
+	owner.pid = 2147483000;
+	writeFileSync(marker, JSON.stringify(owner));
+	return { cwd, registry, view, marker, owner };
+}
+
+function mockOwnerProbe(t: test.TestContext, code?: string): void {
+	t.mock.method(process, "kill", () => {
+		if (code) throw Object.assign(new Error("fixture probe"), { code });
+		return true;
+	});
+}
+
+test("candidate ownership is private and durable before worktree add; ordinary cleanup removes its marker", (t) => {
+	const cwd = repository(t);
+	let observed = false;
+	let syncs = 0;
+	const fsync = fs.fsyncSync;
+	t.mock.method(fs, "fsyncSync", (fd: number) => { syncs++; fsync(fd); });
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") {
+			const root = args[args.length - 2]!;
+			const marker = ownerMarker(root);
+			const owner = JSON.parse(readFileSync(marker, "utf8"));
+			assert.equal(owner.root, root);
+			assert.equal(owner.pid, process.pid);
+			assert.match(owner.token, /^[0-9a-f-]{36}$/);
+			if (process.platform !== "win32") assert.equal(lstatSync(marker).mode & 0o777, 0o600);
+			assert.equal(existsSync(root), false);
+			assert.ok(syncs >= (process.platform === "win32" ? 1 : 4), "marker and every newly created ancestor must be durable before add");
+			observed = true;
+		}
+		return execFileSync(file, args, options);
+	});
+	const view = registry.create({ contributorRoot: cwd });
+	assert.equal(observed, true);
+	view.cleanup();
+	assert.equal(existsSync(view.root), false);
+	assert.equal(existsSync(ownerMarker(view.root)), false);
+});
+
+test("private candidate owner accepts safe Windows artifacts", (t) => {
+	mockWindowsAcl(t);
+	const view = new CandidateViewRegistry(undefined, "win32").create({ contributorRoot: repository(t) });
+	try {
+		assert.equal(lstatSync(ownerMarker(view.root)).isFile(), true);
+		assert.doesNotThrow(() => view.verify());
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("private candidate owner accepts a canonical Windows worktree registration spelling", { skip: process.platform !== "win32" }, (t) => {
+	let root: string | undefined;
+	const registry = new CandidateViewRegistry((file, arguments_, options) => {
+		const output = execFileSync(file, arguments_, options);
+		if (root !== undefined && arguments_[0] === "worktree" && arguments_[1] === "list" && typeof output === "string") {
+			return output.replace(`worktree ${root}\0`, `worktree \\\\?\\${root}\0`);
+		}
+		return output;
+	}, "win32");
+	const view = registry.create({ contributorRoot: repository(t) });
+	root = view.root;
+	view.cleanup();
+	assert.equal(existsSync(root), false);
+});
+
+test("private candidate owner rejects an untrusted conditional Windows allow ACE", () => {
+	assert.throws(
+		() => validatePrivateWindowsDacl("D:P(A;OICI;FA;;;S-1-5-21-1)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(XA;OICI;FA;;;S-1-5-21-2)", "S-1-5-21-1", true),
+		(error: unknown) => error instanceof WindowsDaclValidationError && error.reason === "ace-type" && !error.message.includes("S-1-5-21-2"),
+	);
+});
+
+test("private candidate owner reports bounded Windows DACL mismatch reasons", () => {
+	const dacl = "D:P(A;OICI;FA;;;S-1-5-21-1)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)";
+	for (const [reason, invalid] of [["ace-flags", dacl.replace("OICI", "OI")], ["ace-rights", dacl.replace("FA", "FR")], ["ace-reserved-fields", dacl.replace(";;;S-1-5-21-1", ";object;;S-1-5-21-1")], ["ace-trustee", dacl.replace("S-1-5-21-1", "S-1-5-21-2")], ["ace-duplicate", `${dacl}(A;OICI;FA;;;SY)`], ["ace-count", dacl.replace("(A;OICI;FA;;;BA)", "")]] as const) {
+		assert.throws(() => validatePrivateWindowsDacl(invalid, "S-1-5-21-1", true), (error: unknown) => error instanceof WindowsDaclValidationError && error.reason === reason && error.message === `Windows DACL validation failed: ${reason}${reason === "ace-trustee" ? " (sid)" : ""}`);
+	}
+});
+
+test("private candidate owner reports bounded Windows DACL mismatch reasons for trustees", () => {
+	const dacl = "D:P(A;OICI;FA;;;S-1-5-21-1)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)";
+	for (const [trustee, classification] of [["OW", "OW"], ["CO", "CO"], ["BU", "BU"], ["AU", "AU"], ["WD", "WD"], ["LA", "LA"], ["S-1-5-21-999-888-777-666", "sid"], ["unknown", "other"], ["", "missing"]] as const) {
+		assert.throws(() => validatePrivateWindowsDacl(dacl.replace("S-1-5-21-1", trustee), "S-1-5-21-1", true), (error: unknown) => error instanceof WindowsDaclValidationError && error.reason === "ace-trustee" && error.trustee === classification && error.message === `Windows DACL validation failed: ace-trustee (${classification})` && (trustee === classification || trustee === "" || !error.message.includes(trustee)));
+	}
+});
+
+test("private candidate owner accepts LA for the exact local Administrator SID", () => {
+	assert.doesNotThrow(() => validatePrivateWindowsDacl("D:P(A;OICI;FA;;;LA)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)", "S-1-5-21-1-2-3-500", true, "S-1-5-21-1-2-3-500"));
+});
+
+test("private candidate owner rejects LA for a non-local RID-500 current user when the local Administrator differs", () => {
+	assert.throws(() => validatePrivateWindowsDacl("D:P(A;OICI;FA;;;LA)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)", "S-1-5-21-1-2-3-500", true, "S-1-5-21-4-5-6-500"), (error: unknown) => error instanceof WindowsDaclValidationError && error.reason === "ace-trustee" && error.trustee === "LA");
+});
+
+test("private candidate owner rejects raw and LA local Administrator grants as duplicates", () => {
+	assert.throws(() => validatePrivateWindowsDacl("D:P(A;OICI;FA;;;S-1-5-21-1-2-3-500)(A;OICI;FA;;;LA)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)", "S-1-5-21-1-2-3-500", true, "S-1-5-21-1-2-3-500"), (error: unknown) => error instanceof WindowsDaclValidationError && error.reason === "ace-duplicate");
+});
+
+test("private candidate owner fails closed when local Administrator resolution is unavailable", () => {
+	assert.throws(() => validatePrivateWindowsDacl("D:P(A;OICI;FA;;;LA)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)", "S-1-5-21-1-2-3-500", true), (error: unknown) => error instanceof WindowsDaclValidationError && error.reason === "ace-trustee" && error.trustee === "LA");
+});
+
+test("private candidate owner accepts only trusted Windows owners", () => {
+	for (const owner of ["S-1-5-21-1-2-3-1001", "S-1-5-18", "S-1-5-32-544"]) assert.doesNotThrow(() => validatePrivateWindowsOwner(owner, "S-1-5-21-1-2-3-1001"));
+	assert.throws(() => validatePrivateWindowsOwner("S-1-5-21-4-5-6-1002", "S-1-5-21-1-2-3-1001"), (error: unknown) => error instanceof WindowsOwnerValidationError && !error.message.includes("S-1-5-21-4-5-6-1002"));
+});
+
+test("private candidate owner fails closed when Windows owner resolution is unavailable", () => {
+	assert.throws(() => validatePrivateWindowsOwner(undefined, "S-1-5-21-1-2-3-1001"), WindowsOwnerValidationError);
+});
+
+test("private candidate owner rejects a different Windows owner at the ancestor replacement boundary", (t) => {
+	const cwd = repository(t), commonDir = join(cwd, ".git"), control = join(commonDir, "gentle-ai"), parent = join(control, "candidate-views");
+	mkdirSync(parent, { recursive: true });
+	setWindowsAclAuthorityForTesting((path) => {
+		if (path === control) validatePrivateWindowsOwner("S-1-5-21-4-5-6-1002", "S-1-5-21-1-2-3-1001");
+	});
+	t.after(() => setWindowsAclAuthorityForTesting());
+	assert.throws(() => prepareCandidateOwnerParent(commonDir, "win32"), (error: unknown) => error instanceof WindowsOwnerValidationError && error.owner === "sid");
+});
+
+test("private candidate owner revalidates every Windows ancestor replacement boundary", (t) => {
+	const cwd = repository(t), commonDir = join(cwd, ".git"), control = join(commonDir, "gentle-ai"), parent = join(control, "candidate-views");
+	mkdirSync(parent, { recursive: true });
+	const checked: string[] = [];
+	setWindowsAclAuthorityForTesting((path) => checked.push(path));
+	t.after(() => setWindowsAclAuthorityForTesting());
+	assert.equal(assertCandidateOwnerParent(commonDir, "win32"), parent);
+	assert.deepEqual(checked, [commonDir, control, parent]);
+});
+
+test("private candidate owner rejects a controlled foreign Windows owner", { skip: process.platform !== "win32" }, (t) => {
+	const path = mkdtempSync(join(tmpdir(), "gentle-pi-foreign-owner-"));
+	t.after(() => rmSync(path, { recursive: true, force: true }));
+	try {
+		execFileSync(realpathSync.native("\\\\?\\GLOBALROOT\\SystemRoot\\System32\\icacls.exe"), [path, "/setowner", "*S-1-5-32-545"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+	} catch {
+		if (process.env.GITHUB_ACTIONS === "true" || process.env.CI === "true") assert.fail("Windows CI could not assign BUILTIN\\Users as the controlled temporary directory owner");
+		t.skip("Current Windows token cannot assign BUILTIN\\Users as the controlled temporary directory owner");
+		return;
+	}
+	assert.throws(() => assertTrustedWindowsOwner(path, "directory"), (error: unknown) => error instanceof WindowsOwnerValidationError && error.owner === "sid");
+});
+
+test("private candidate owner reads trusted Windows directory and marker file owners", { skip: process.platform !== "win32" }, (t) => {
+	const cwd = repository(t), commonDir = join(cwd, ".git"), parent = join(commonDir, "gentle-ai", "candidate-views");
+	const view = new CandidateViewRegistry().create({ contributorRoot: cwd });
+	try {
+		assert.doesNotThrow(() => assertTrustedWindowsOwner(parent, "directory"));
+		assert.doesNotThrow(() => assertTrustedWindowsOwner(ownerMarker(view.root), "file"));
+		assert.doesNotThrow(() => view.verify());
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("private candidate owner removes unrelated explicit Windows grants during enforcement", { skip: process.platform !== "win32" }, (t) => {
+	const cwd = repository(t), commonDir = join(cwd, ".git"), parent = join(commonDir, "gentle-ai", "candidate-views");
+	const initial = new CandidateViewRegistry().create({ contributorRoot: cwd });
+	initial.cleanup();
+	const system = process.env.SystemRoot!;
+	execFileSync(`${system}\\System32\\icacls.exe`, [parent, "/grant", "*S-1-5-32-545:(OI)(CI)F"], { encoding: "utf8" });
+	const archive = ".candidate-owner-acl.txt";
+	try {
+		execFileSync(`${system}\\System32\\icacls.exe`, [parent, "/save", archive, "/c"], { cwd: parent, encoding: "utf8" });
+		const before = readFileSync(join(parent, archive), "utf16le").match(/D:[^\r\n]+/)?.[0];
+		assert.ok(before);
+		assert.match(before, /;;;(?:BU|S-1-5-32-545)\)/i);
+		assert.doesNotThrow(() => prepareCandidateOwnerParent(commonDir));
+		execFileSync(`${system}\\System32\\icacls.exe`, [parent, "/save", archive, "/c"], { cwd: parent, encoding: "utf8" });
+		const after = readFileSync(join(parent, archive), "utf16le").match(/D:[^\r\n]+/)?.[0];
+		assert.ok(after);
+		assert.doesNotMatch(after, /;;;(?:BU|S-1-5-32-545)\)/i);
+	} finally {
+		rmSync(join(parent, archive), { force: true });
+	}
+});
+
+test("candidate contributor root accepts canonical Windows Git path spelling", { skip: process.platform !== "win32" }, (t) => {
+	const contributorRoot = repository(t);
+	let useCanonicalSpelling = false;
+	const registry = new CandidateViewRegistry((file, arguments_, options) => {
+		const output = execFileSync(file, arguments_, options);
+		if (!useCanonicalSpelling || typeof output !== "string" || arguments_[0] !== "rev-parse") return output;
+		if (arguments_[1] === "--show-toplevel") return output.toUpperCase();
+		if (arguments_[1] === "--git-common-dir") return resolve(contributorRoot, output).toUpperCase();
+		return output;
+	}, "win32");
+	mockWindowsAcl(t);
+	const view = registry.create({ contributorRoot });
+	try {
+		useCanonicalSpelling = true;
+		assert.doesNotThrow(() => view.verify());
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("private candidate owner ignores a spoofed SystemRoot when invoking Windows ACL tools", { skip: process.platform !== "win32" }, (t) => {
+	const originalSystemRoot = process.env.SystemRoot;
+	const spoofedSystemRoot = join(tmpdir(), "gentle-pi-spoofed-SystemRoot");
+	process.env.SystemRoot = spoofedSystemRoot;
+	t.after(() => {
+		if (originalSystemRoot === undefined) delete process.env.SystemRoot;
+		else process.env.SystemRoot = originalSystemRoot;
+	});
+	const execFile = childProcess.execFileSync;
+	const aclExecutables: string[] = [];
+	t.mock.method(childProcess, "execFileSync", (file, arguments_, options) => {
+		if (typeof file === "string" && /\\(?:whoami|icacls)\.exe$/i.test(file)) {
+			aclExecutables.push(file);
+			assert.equal(file.toLowerCase().startsWith(spoofedSystemRoot.toLowerCase()), false);
+		}
+		return execFile(file, arguments_, options);
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	const view = new CandidateViewRegistry().create({ contributorRoot: repository(t) });
+	try {
+		view.verify();
+		assert.ok(aclExecutables.length > 0);
+	} finally {
+		view.cleanup();
+	}
+});
+
+test("private candidate owner reads back a restrictive Windows DACL before worktree materialization", { skip: process.platform !== "win32" }, (t) => {
+	const system = process.env.SystemRoot!;
+	const view = new CandidateViewRegistry().create({ contributorRoot: repository(t) });
+	try {
+		const parent = join(view.root, ".."), archive = ".candidate-owner-acl.txt";
+		execFileSync(`${system}\\System32\\icacls.exe`, [parent, "/save", archive, "/c"], { cwd: parent, encoding: "utf8" });
+		const sddl = readFileSync(join(parent, archive), "utf16le");
+		rmSync(join(parent, archive));
+		const dacl = sddl.match(/D:[^\r\n]+/)?.[0];
+		assert.ok(dacl);
+		assert.doesNotThrow(() => view.verify());
+	} finally {
+		view.cleanup();
+	}
+});
+
+function publicationFailure(t: test.TestContext, phase: "write" | "fsync" | "directory"): void {
+	mockWindowsAcl(t);
+	if (phase === "directory") {
+		const descriptor = Object.getOwnPropertyDescriptor(process, "platform")!;
+		Object.defineProperty(process, "platform", { configurable: true, value: "linux" });
+		t.after(() => Object.defineProperty(process, "platform", descriptor));
+	}
+	const cwd = repository(t), parent = join(cwd, ".git", "gentle-ai", "candidate-views");
+	let adds = 0;
+	if (phase === "write") t.mock.method(fs, "writeFileSync", () => { throw new Error("fixture marker write failure"); });
+	if (phase === "fsync") t.mock.method(fs, "fsyncSync", () => { throw new Error("fixture marker fsync failure"); });
+	if (phase === "directory") {
+		const fsync = fs.fsyncSync;
+		let syncs = 0;
+		t.mock.method(fs, "fsyncSync", (fd: number) => {
+			if (++syncs === 1) return fsync(fd);
+			throw new Error("fixture marker directory sync failure");
+		});
+	}
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") adds++;
+		return execFileSync(file, args, options);
+	}, "win32");
+	assert.throws(
+		() => registry.create({ contributorRoot: cwd }),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "candidate-owner-preparation-failed",
+	);
+	assert.equal(adds, 0);
+	assert.deepEqual(readdirSync(parent).filter((name) => name.endsWith(".owner.json") || name.endsWith(".reaper-lock")), []);
+}
+
+for (const [phase, label] of [["write", "marker write"], ["fsync", "marker fsync"], ["directory", "post-marker directory sync"]] as const) {
+	test(`candidate owner publication rolls back after ${label} failure`, (t) => publicationFailure(t, phase));
+}
+
+test("candidate owner publication never removes a replaced marker", (t) => {
+	mockWindowsAcl(t);
+	const cwd = repository(t), parent = join(cwd, ".git", "gentle-ai", "candidate-views");
+	const write = fs.writeFileSync;
+	t.mock.method(fs, "fsyncSync", () => {
+		const marker = readdirSync(parent).find((name) => name.endsWith(".owner.json"));
+		assert.ok(marker);
+		renameSync(join(parent, marker!), join(parent, `${marker}.saved`));
+		write(join(parent, marker!), "replacement", { mode: 0o600 });
+		throw new Error("fixture marker fsync failure after replacement");
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	let adds = 0;
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") adds++;
+		return execFileSync(file, args, options);
+	}, "win32");
+	assert.throws(() => registry.create({ contributorRoot: cwd }), CandidateViewError);
+	assert.equal(adds, 0);
+	const marker = readdirSync(parent).find((name) => name.endsWith(".owner.json"));
+	assert.ok(marker);
+	assert.equal(readFileSync(join(parent, marker!), "utf8"), "replacement");
+	assert.equal(readdirSync(parent).some((name) => name.endsWith(".reaper-lock")), false);
+});
+
+test("candidate owner rejects an absent POSIX getuid before worktree creation", { skip: process.platform === "win32" }, (t) => {
+	const originalGetuid = process.getuid;
+	Object.defineProperty(process, "getuid", { configurable: true, value: undefined });
+	t.after(() => Object.defineProperty(process, "getuid", { configurable: true, value: originalGetuid }));
+	assert.throws(
+		() => new CandidateViewRegistry().create({ contributorRoot: repository(t) }),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "candidate-owner-preparation-failed",
+	);
+});
+
+test("candidate owner rejects a POSIX UID mismatch before worktree creation", { skip: process.platform === "win32" }, (t) => {
+	const uid = process.getuid?.();
+	assert.equal(typeof uid, "number");
+	const originalGetuid = process.getuid;
+	Object.defineProperty(process, "getuid", { configurable: true, value: () => uid! + 1 });
+	t.after(() => Object.defineProperty(process, "getuid", { configurable: true, value: originalGetuid }));
+	assert.throws(
+		() => new CandidateViewRegistry().create({ contributorRoot: repository(t) }),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "candidate-owner-preparation-failed",
+	);
+});
+
+test("marked registered definitively dead candidate is reclaimed before another materialization", (t) => {
+	const { cwd, view, marker } = orphanFixture(t);
+	mockOwnerProbe(t, "ESRCH");
+	const next = new CandidateViewRegistry().create({ contributorRoot: cwd });
+	assert.equal(existsSync(view.root), false);
+	assert.equal(existsSync(marker), false);
+	assert.ok(!git(cwd, "worktree", "list", "--porcelain").includes(view.root));
+	next.cleanup();
+});
+
+for (const scenario of ["self", "live", "EPERM", "unknown", "malformed", "foreign-host", "unknown-host", "invalid-pid", "extra-key", "legacy", "unregistered", "root-symlink", "marker-symlink", "parent-symlink", "escape", "unknown-lock", "public-marker", "locked", "backlink", "admin-symlink", "missing-root"] as const) {
+	test(`orphan sweep preserves ${scenario} ownership`, (t) => {
+		const { cwd, view, marker, owner } = orphanFixture(t);
+		mockOwnerProbe(t, scenario === "live" ? undefined : scenario === "EPERM" ? "EPERM" : scenario === "unknown" ? "EIO" : "ESRCH");
+		if (scenario === "self") owner.pid = process.pid;
+		if (scenario === "foreign-host") owner.host = "another-host";
+		if (scenario === "unknown-host") owner.host = null;
+		if (scenario === "invalid-pid") owner.pid = -1;
+		if (scenario === "extra-key") owner.extra = true;
+		if (scenario === "escape") owner.root = cwd;
+		writeFileSync(marker, scenario === "malformed" ? "{" : JSON.stringify(owner));
+		if (scenario === "legacy") rmSync(marker);
+		if (scenario === "public-marker") chmodSync(marker, 0o644);
+		if (scenario === "locked") git(cwd, "worktree", "lock", view.root);
+		if (scenario === "backlink" || scenario === "admin-symlink") {
+			const admin = readFileSync(join(view.root, ".git"), "utf8").slice(8).trim();
+			if (scenario === "backlink") writeFileSync(join(admin, "gitdir"), `${cwd}/.git\n`);
+			else { renameSync(admin, `${admin}.saved`); symlinkSync(`${admin}.saved`, admin); }
+		}
+		if (scenario === "missing-root") renameSync(view.root, `${view.root}.saved`);
+		if (scenario === "unknown-lock") writeFileSync(`${view.root}.reaper-lock`, "unknown");
+		if (scenario === "unregistered") {
+			execFileSync("chmod", ["-R", "u+rwx", view.root]);
+			git(cwd, "worktree", "remove", "--force", view.root);
+			mkdirSync(view.root);
+			writeFileSync(join(view.root, "preserve.txt"), "unregistered");
+		}
+		if (scenario === "root-symlink") { renameSync(view.root, `${view.root}.saved`); symlinkSync(`${view.root}.saved`, view.root); }
+		if (scenario === "marker-symlink") { renameSync(marker, `${marker}.saved`); symlinkSync(`${marker}.saved`, marker); }
+		if (scenario === "parent-symlink") {
+			const parent = join(view.root, "..");
+			renameSync(parent, `${parent}.saved`);
+			symlinkSync(`${parent}.saved`, parent);
+		}
+		new CandidateViewRegistry().sweepOrphans(cwd);
+		assert.equal(existsSync(view.root), scenario !== "missing-root");
+		assert.equal(existsSync(marker), scenario !== "legacy");
+		assert.equal(readFileSync(join(cwd, "tracked.txt"), "utf8"), "base\n");
+	});
+}
+
+test("reaper lock excludes concurrent sweeps and rechecks marker identity before removal", (t) => {
+	const { cwd, view, marker, owner } = orphanFixture(t);
+	mockOwnerProbe(t, "ESRCH");
+	let lists = 0;
+	const racing = new CandidateViewRegistry((file, args, options) => {
+		if (args.includes("list")) {
+			lists++;
+			new CandidateViewRegistry().sweepOrphans(cwd);
+			if (lists === 2) writeFileSync(marker, JSON.stringify({ ...owner, token: "00000000-0000-4000-8000-000000000000" }));
+		}
+		return execFileSync(file, args, options);
+	});
+	racing.sweepOrphans(cwd);
+	assert.ok(lists >= 2);
+	assert.equal(existsSync(view.root), true);
+	assert.equal(existsSync(`${view.root}.reaper-lock`), false);
+});
+
+test("failed Git removal preserves owned candidate and marker without recursive fallback", (t) => {
+	const cwd = repository(t);
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args.includes("remove")) throw new Error("fixture removal failure");
+		return execFileSync(file, args, options);
+	});
+	const view = registry.create({ contributorRoot: cwd });
+	assert.throws(() => view.cleanup());
+	assert.equal(existsSync(view.root), true);
+	assert.equal(existsSync(ownerMarker(view.root)), true);
+});
+
+test("failed creation retains a recoverable marker when Git removal also fails", (t) => {
+	const cwd = repository(t);
+	let root = "";
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") root = args[args.length - 2]!;
+		if (args.includes("remove") || (args[0] === "read-tree" && options.cwd === root)) throw new Error("fixture failure");
+		return execFileSync(file, args, options);
+	});
+	assert.throws(() => registry.create({ contributorRoot: cwd }));
+	assert.equal(existsSync(root), true);
+	const owner = JSON.parse(readFileSync(ownerMarker(root), "utf8"));
+	writeFileSync(ownerMarker(root), JSON.stringify({ ...owner, pid: 2147483000 }));
+	mockOwnerProbe(t, "ESRCH");
+	new CandidateViewRegistry().sweepOrphans(cwd);
+	assert.equal(existsSync(root), false);
+});
+
+test("materialization rejects a symlinked owner ancestor without creating an external store", (t) => {
+	const cwd = repository(t);
+	const outside = join(cwd, "outside");
+	mkdirSync(outside);
+	symlinkSync(outside, join(cwd, ".git", "gentle-ai"));
+	assert.throws(() => new CandidateViewRegistry().create({ contributorRoot: cwd }));
+	assert.equal(existsSync(join(outside, "candidate-views")), false);
+});
+
+test("owner fsync failure prevents worktree registration", (t) => {
+	const cwd = repository(t);
+	let adds = 0;
+	t.mock.method(fs, "fsyncSync", () => { throw new Error("fixture fsync failure"); });
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add") adds++;
+		return execFileSync(file, args, options);
+	});
+	assert.throws(
+		() => registry.create({ contributorRoot: cwd }),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "candidate-owner-preparation-failed" && error.cause instanceof Error && /fsync/.test(error.cause.message),
+	);
+	assert.equal(adds, 0);
+});
+
+test("ordinary cleanup preserves mismatched owner and cleanupAll continues other records", (t) => {
+	const cwd = repository(t);
+	const registry = new CandidateViewRegistry();
+	const first = registry.create({ contributorRoot: cwd });
+	const second = registry.create({ contributorRoot: cwd });
+	const marker = ownerMarker(first.root);
+	const bytes = readFileSync(marker, "utf8");
+	writeFileSync(marker, JSON.stringify({ ...JSON.parse(bytes), token: "00000000-0000-4000-8000-000000000000" }));
+	registry.cleanupAll();
+	assert.equal(existsSync(first.root), true);
+	assert.equal(existsSync(marker), true);
+	assert.equal(existsSync(second.root), false);
+	writeFileSync(marker, bytes);
+	registry.cleanupAll();
+	assert.equal(existsSync(first.root), false);
+});
+
+for (const race of ["root", "registration", "lock"] as const) {
+	test(`orphan reaper preserves a ${race} replacement at the Git race boundary`, (t) => {
+		const { cwd, view, marker } = orphanFixture(t);
+		mockOwnerProbe(t, "ESRCH");
+		let lists = 0;
+		const registry = new CandidateViewRegistry((file, args, options) => {
+			const result = execFileSync(file, args, options);
+			if (args.includes("list") && ++lists === 2) {
+				if (race === "root") { renameSync(view.root, `${view.root}.saved`); mkdirSync(view.root); }
+				if (race === "registration") return String(result).replace(`worktree ${view.root}`, `worktree ${view.root}.other`);
+				if (race === "lock") writeFileSync(`${view.root}.reaper-lock`, "replacement");
+			}
+			return result;
+		});
+		registry.sweepOrphans(cwd);
+		assert.equal(existsSync(view.root), true);
+		assert.equal(existsSync(marker), true);
+		if (race === "lock") assert.equal(readFileSync(`${view.root}.reaper-lock`, "utf8"), "replacement");
+	});
+}
+
+test("ordinary cleanup never unlinks a replaced sidecar after Git removal", (t) => {
+	const cwd = repository(t);
+	let marker = "";
+	const registry = new CandidateViewRegistry((file, args, options) => {
+		const result = execFileSync(file, args, options);
+		if (args[0] === "worktree" && args[1] === "remove") {
+			const bytes = readFileSync(marker);
+			renameSync(marker, `${marker}.saved`);
+			writeFileSync(marker, bytes, { mode: 0o600 });
+		}
+		return result;
+	});
+	const view = registry.create({ contributorRoot: cwd });
+	marker = ownerMarker(view.root);
+	assert.throws(() => view.cleanup(), /ownership changed/i);
+	assert.equal(existsSync(marker), true);
+});
+
 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");
@@ -379,6 +909,50 @@ test("candidate view preserves staged additions with explicit intended-untracked
 	}
 });
 
+test("candidate view detects a same-stat tracked rewrite with selected untracked content when trustctime is disabled", (t) => {
+	const contributorRoot = repository(t);
+	const tracked = join(contributorRoot, "tracked.txt");
+	const index = join(contributorRoot, ".git", "index");
+	// A fractional timestamp exposes Date-based timestamp restoration, which can
+	// collapse the private index onto the live index's racy-clean boundary.
+	const fixedTimestampSeconds = 946_684_800.654_321;
+	git(contributorRoot, "config", "core.trustctime", "false");
+	writeFileSync(tracked, "fixed\n");
+	utimesSync(tracked, fixedTimestampSeconds, fixedTimestampSeconds);
+	git(contributorRoot, "add", "tracked.txt");
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "fixed timestamp base");
+	writeFileSync(tracked, "other\n");
+	utimesSync(tracked, fixedTimestampSeconds, fixedTimestampSeconds);
+	utimesSync(index, fixedTimestampSeconds, fixedTimestampSeconds);
+	const liveIndexMtimeNs = lstatSync(index, { bigint: true }).mtimeNs;
+	if (liveIndexMtimeNs % 1_000_000n === 0n) t.diagnostic("filesystem does not retain sub-millisecond index mtimes; retaining the same-stat rewrite assertion");
+	else assert.notEqual(liveIndexMtimeNs % 1_000_000_000n, 0n, "sub-millisecond filesystem must retain the requested non-whole-second index mtime");
+	writeFileSync(join(contributorRoot, "selected.txt"), "selected\n");
+
+	let privateIndexMtimeNs: bigint | undefined;
+	const registry = new CandidateViewRegistry((file, arguments_, options) => {
+		if (arguments_[0] === "add" && privateIndexMtimeNs === undefined) {
+			const privateIndexPath = options.env?.GIT_INDEX_FILE;
+			assert.equal(typeof privateIndexPath, "string", "private candidate index must be set before Git refreshes tracked entries");
+			privateIndexMtimeNs = lstatSync(privateIndexPath, { bigint: true }).mtimeNs;
+		}
+		return execFileSync(file, arguments_, options);
+	});
+	const view = registry.create({ contributorRoot, intendedUntracked: ["selected.txt"] });
+	try {
+		assert.notEqual(privateIndexMtimeNs, undefined, "private index timestamp must be observed before Git add");
+		assert.ok(privateIndexMtimeNs! < liveIndexMtimeNs, "private index must be strictly earlier than the live index");
+		assert.ok(liveIndexMtimeNs - privateIndexMtimeNs! >= 1_000_000_000n, "private index must leave a bounded racy-clean safety interval");
+		assert.deepEqual(view.intendedUntracked, ["selected.txt"]);
+		assert.deepEqual(view.paths, ["selected.txt", "tracked.txt"]);
+		assert.notEqual(view.candidateTree, view.baseTree);
+		assert.equal(readFileSync(join(view.root, "tracked.txt"), "utf8"), "other\n");
+		assert.equal(readFileSync(join(view.root, "selected.txt"), "utf8"), "selected\n");
+	} finally {
+		view.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");
@@ -490,6 +1064,76 @@ test("candidate registry isolates replay, projection, current, and cleanup state
 	registry.cleanupTerminal("same-lineage", "approved", rootA);
 });
 
+// ga#4085 / ga#4050: after a valid `granted` consent, a retried native START
+// for a lineage this controller already bound (native reports it "resumed")
+// re-materializes a fresh, content-identical candidate view under a new
+// token -- for example after a transport hiccup between START and the
+// follow-up STATUS call. Rebinding that duplicate to the same lineage used to
+// fail closed with "candidate view lineage binding is missing or ambiguous"
+// even though nothing was actually ambiguous. It must reuse the already-bound
+// view instead of failing the retry.
+test("candidate registry rebinds a retried native START for an already-bound lineage instead of failing closed", (t) => {
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "tracked.txt"), "candidate\n");
+	const registry = new CandidateViewRegistry();
+	t.after(() => registry.cleanupAll());
+	const first = registry.create({ contributorRoot });
+	registry.bindCurrent({ token: first.token, lineageId: "retry-lineage", selectedLenses: ["review-risk"] });
+	assert.equal(registry.hasCurrentBinding(contributorRoot), true);
+
+	const retry = registry.create({ contributorRoot });
+	assert.notEqual(retry.token, first.token, "the retry must materialize a distinct physical worktree/token");
+	assert.doesNotThrow(() => registry.bindCurrent({ token: retry.token, lineageId: "retry-lineage", selectedLenses: ["review-risk"] }));
+
+	// The already-bound view stays current; the redundant duplicate is discarded.
+	assert.equal(registry.resolveForLens("retry-lineage", "review-risk", contributorRoot).root, first.root);
+	assert.equal(registry.resolveCurrentForLens("review-risk", contributorRoot).root, first.root);
+	assert.equal(existsSync(retry.root), false, "the redundant duplicate candidate view must be cleaned up");
+	registry.cleanupTerminal("retry-lineage", "approved", contributorRoot);
+});
+
+test("candidate registry still fails closed rebinding the same lineage to genuinely different content", (t) => {
+	const contributorRoot = repository(t);
+	const registry = new CandidateViewRegistry();
+	t.after(() => registry.cleanupAll());
+	const first = registry.create({ contributorRoot });
+	registry.bindCurrent({ token: first.token, lineageId: "conflict-lineage", selectedLenses: ["review-risk"] });
+	writeFileSync(join(contributorRoot, "tracked.txt"), "different content\n");
+	const conflicting = registry.create({ contributorRoot });
+	assert.notEqual(conflicting.candidateTree, first.candidateTree);
+	assert.throws(
+		() => registry.bindCurrent({ token: conflicting.token, lineageId: "conflict-lineage", selectedLenses: ["review-risk"] }),
+		CandidateViewError,
+	);
+	registry.cleanup(conflicting.token);
+	registry.cleanupTerminal("conflict-lineage", "approved", contributorRoot);
+});
+
+// gentle-pi#323: `createOrReuse` reuses whatever view a replay key maps to,
+// with no awareness of live candidate content -- a content-independent key
+// reuses a stale view even after the candidate content it was frozen from
+// has changed. The fix lives at the START call site (extensions/gentle-ai.ts),
+// which now folds the current candidate tree into the replay key; this test
+// documents both the registry's plain-key reuse contract and that folding
+// content identity into the key produces a fresh view once content changes.
+test("candidate registry reuses a replay-keyed view verbatim regardless of live content, so callers must fold content identity into the key", (t) => {
+	const registry = new CandidateViewRegistry();
+	t.after(() => registry.cleanupAll());
+	const contributorRoot = repository(t);
+	const contentIndependentKey = "cwd-and-lineage-only";
+	const first = registry.createOrReuse({ contributorRoot, replayKey: contentIndependentKey });
+	writeFileSync(join(contributorRoot, "tracked.txt"), "candidate two\n");
+	const staleReuse = registry.createOrReuse({ contributorRoot, replayKey: contentIndependentKey });
+	assert.equal(staleReuse.token, first.token, "a content-independent replay key reuses the stale view");
+	const freshForCurrentContent = registry.create({ contributorRoot });
+	assert.notEqual(staleReuse.candidateTree, freshForCurrentContent.candidateTree, "the stale reused view no longer reflects live candidate content");
+	const contentScopedKey = `${contentIndependentKey}${freshForCurrentContent.candidateTree}`;
+	const rekeyed = registry.createOrReuse({ contributorRoot, replayKey: contentScopedKey });
+	assert.notEqual(rekeyed.token, staleReuse.token, "folding candidate content into the replay key mints a fresh view once content changes");
+	assert.equal(rekeyed.candidateTree, freshForCurrentContent.candidateTree);
+	registry.cleanup(freshForCurrentContent.token);
+});
+
 test("candidate registry rejects a lineage target whose authorized symlink was replaced", (t) => {
 	const root = repository(t);
 	const replacement = repository(t);
@@ -546,14 +1190,15 @@ 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) => {
+test("candidate cleanup preserves a 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);
+	assert.throws(() => view.cleanup(), /incomplete/);
+	assert.throws(() => view.cleanup(), /incomplete/);
+	assert.equal(existsSync(view.root), true);
+	assert.equal(existsSync(ownerMarker(view.root)), true);
 });
 
 test("corrected views stay within frozen scope and replace projections only when promoted", (t) => {
@@ -711,6 +1356,32 @@ test("candidate view verifies unchanged tree entries even when they are absent f
 	}
 });
 
+test("candidate executable-mode validation accepts a readonly Git executable on Windows and rejects it on POSIX", () => {
+	assert.equal(hasExpectedExecutableBits(0o444, "100755", "win32"), true);
+	assert.equal(hasExpectedExecutableBits(0o444, "100755", "linux"), false);
+	assert.equal(hasExpectedExecutableBits(0o555, "100755", "linux"), true);
+	assert.equal(hasExpectedExecutableBits(0o555, "100644", "win32"), false);
+});
+
+test("candidate registry forwards explicit Windows mode validation to view verification", (t) => {
+	mockWindowsAcl(t);
+	const contributorRoot = repository(t);
+	writeFileSync(join(contributorRoot, "unchanged-executable.sh"), "#!/bin/sh\necho base\n");
+	git(contributorRoot, "add", "unchanged-executable.sh");
+	git(contributorRoot, "update-index", "--chmod=+x", "unchanged-executable.sh");
+	chmodSync(join(contributorRoot, "unchanged-executable.sh"), 0o755);
+	git(contributorRoot, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "executable base");
+	writeFileSync(join(contributorRoot, "tracked.txt"), "changed\n");
+	const view = new CandidateViewRegistry(undefined, "win32").createOrReuse({ contributorRoot, baseRef: "HEAD" });
+	try {
+		assert.deepEqual(view.paths, ["tracked.txt"]);
+		chmodSync(view.root, 0o755); chmodSync(join(view.root, "unchanged-executable.sh"), 0o444); chmodSync(view.root, 0o555);
+		assert.doesNotThrow(() => view.verify());
+	} finally {
+		view.cleanup();
+	}
+});
+
 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");
@@ -1925,3 +2596,76 @@ test("candidate view cleans up a partially registered unborn fallback worktree w
 	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");
 });
+
+function stagedFinalizeDescriptor(cwd: string, path: string, content: string): NativeCandidateProjectionDescriptor {
+	writeFileSync(join(cwd, path), content);
+	git(cwd, "add", path);
+	const baseTree = git(cwd, "rev-parse", "HEAD^{tree}");
+	const currentCandidateTree = git(cwd, "write-tree");
+	return { baseTree, currentCandidateTree, paths: [path], intendedUntracked: [], projection: "staged" };
+}
+
+function candidateViewWorktreeCount(cwd: string): number {
+	return git(cwd, "worktree", "list").split("\n").filter((line) => line.includes("candidate-views")).length;
+}
+
+test("gentle-pi#185: a forecast-restored FINALIZE worktree does not leak across the next restore for the same lineage", (t) => {
+	// gentle-pi#185: `restoreForFinalizeFromNative` materializes a real Git
+	// worktree to restore a lineage's FINALIZE binding from the native frozen
+	// projection. A forecast-only FINALIZE after a process restart uses this
+	// exact path, but its outcome is non-terminal, so `cleanupTerminal` (which
+	// only fires for "approved"/"escalated") never runs for it. Before the fix,
+	// `restoreForFinalizeFromNative` never cleared the stale binding it had
+	// just created, so restoring the same lineage's FINALIZE binding again
+	// (the lineage's later approved FINALIZE, or another restart-time
+	// forecast) threw "native frozen projection is invalid or already
+	// restored" from `restoreProjectionFromNative` — leaving the first
+	// worktree registered forever and breaking the very finalize that should
+	// have succeeded.
+	const cwd = repository(t);
+	const registry = new CandidateViewRegistry();
+	const lineageId = "forecast-lineage-185";
+	const descriptor = stagedFinalizeDescriptor(cwd, "tracked.txt", "forecast change\n");
+
+	assert.equal(candidateViewWorktreeCount(cwd), 0, "no candidate worktree exists before any restore");
+
+	// Reproduces the leak symptom: a forecast-only FINALIZE restore
+	// materializes a worktree that is still registered with Git once the
+	// (non-terminal) forecast finalize returns.
+	registry.restoreForFinalizeFromNative(lineageId, cwd, descriptor);
+	assert.equal(candidateViewWorktreeCount(cwd), 1, "the forecast restore leaves its worktree registered with Git after it returns");
+
+	// A later restore for the same lineage (its approved FINALIZE, or another
+	// restart-time forecast) must clean up the stale worktree and replace it
+	// deterministically instead of throwing or leaking a parallel sibling.
+	assert.doesNotThrow(
+		() => registry.restoreForFinalizeFromNative(lineageId, cwd, descriptor),
+		"restoring the same lineage's FINALIZE binding again must not fail on the stale binding it left behind",
+	);
+	assert.equal(candidateViewWorktreeCount(cwd), 1, "the second restore must replace the first worktree, never accumulate a parallel sibling");
+
+	// The subsequent approved FINALIZE's terminal cleanup must still work for
+	// the worktree that is actually registered after the restore.
+	registry.cleanupTerminal(lineageId, "approved", cwd);
+	assert.equal(candidateViewWorktreeCount(cwd), 0, "approved cleanup removes the restored worktree, leaving no candidate worktree registered");
+});
+
+test("gentle-pi#185 review correction: a restore whose materialization fails leaves the previous binding intact", (t) => {
+	const cwd = repository(t);
+	const lineageId = "forecast-lineage-185-rollback";
+	const descriptor = stagedFinalizeDescriptor(cwd, "tracked.txt", "forecast change\n");
+	let worktreeAdds = 0;
+	const executor: CandidateGitExecutor = (file, args, options) => {
+		if (args[0] === "worktree" && args[1] === "add" && ++worktreeAdds === 2) throw Object.assign(new Error("simulated worktree add failure"), { status: 128 });
+		return execFileSync(file, args, options);
+	};
+	const registry = new CandidateViewRegistry(executor);
+	const first = registry.restoreForFinalizeFromNative(lineageId, cwd, descriptor);
+	assert.equal(candidateViewWorktreeCount(cwd), 1);
+	let failure: unknown;
+	try { registry.restoreForFinalizeFromNative(lineageId, cwd, descriptor); } catch (error) { failure = error; }
+	assert.equal((failure as CandidateViewError)?.reason, "candidate-view-git-failure", "a failed materialization must propagate, not silently succeed");
+	assert.equal(candidateViewWorktreeCount(cwd), 1, "the previously registered worktree must survive the failed restore");
+	assert.equal(registry.resolveForFinalize(lineageId, cwd).token, first.token, "the lineage must still resolve to its original worktree");
+	registry.cleanupTerminal(lineageId, "approved", cwd);
+});