gentle-pi 2.3.0 → 2.5.0

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

@@ -3,7 +3,7 @@ import { execFileSync } 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 test from "node:test";
@@ -11,6 +11,7 @@ import { gzipSync } from "node:zlib";
 import {
 	CandidateViewRegistry,
 	CandidateViewError,
+	hasExpectedExecutableBits,
 	type CandidateGitExecutor,
 	createCandidateView,
 	decodeCandidateContextManifest,
@@ -18,6 +19,7 @@ import {
 	digestChangedPathManifest,
 	injectReviewCandidateView,
 	readCandidateContextManifestPage,
+	type NativeCandidateProjectionDescriptor,
 } from "../lib/review-candidate-view.ts";
 
 function git(cwd: string, ...arguments_: string[]): string {
@@ -26,7 +28,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(() => {
+		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 +39,233 @@ function repository(t: test.TestContext): string {
 	return cwd;
 }
 
+function ownerMarker(root: string): string { return `${root}.owner.json`; }
+
+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}$/);
+			assert.equal(lstatSync(marker).mode & 0o777, 0o600);
+			assert.equal(existsSync(root), false);
+			assert.ok(syncs >= 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("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 }), /fsync/);
+	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 +611,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 +766,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 +892,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 +1058,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) => {
+	if (process.platform === "win32") return t.skip("requires POSIX candidate-owner directory permissions unavailable on Windows");
+	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 +2298,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);
+});