gentle-pi 2.3.0 → 2.5.0

package/lib/review-candidate-view-owner.ts

@@ -0,0 +1,177 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { conservativeOwnerDeathProofV1 } from "./review-lock.ts";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const BOOT_UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+export interface CandidateViewOwner {
+	version: 1;
+	uuid: string;
+	token: string;
+	pid: number;
+	host: string | null;
+	root: string;
+	commonDir: string;
+}
+type Git = (args: readonly string[]) => string;
+
+// A hostname or a repository-local nonce cannot prove that a PID is local.
+// Bind to the kernel boot and, on Linux, its PID namespace. Unsupported or
+// unavailable provenance disables reclamation (including across reboots).
+function localHost(): string | null {
+	try {
+		if (process.platform === "darwin") {
+			const boot = execFileSync("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], { encoding: "utf8", timeout: 1000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"] }).trim();
+			if (BOOT_UUID.test(boot)) return `darwin:${boot.toLowerCase()}`;
+		}
+		if (process.platform === "linux") {
+			const boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+			const namespace = readlinkSync("/proc/self/ns/pid");
+			if (BOOT_UUID.test(boot) && /^pid:\[\d+\]$/.test(namespace)) return `linux:${boot}:${namespace}`;
+		}
+	} catch { /* No remote/PID-only fallback. */ }
+	return null;
+}
+
+function directory(path: string, privateMode = false): string {
+	const stat = lstatSync(path);
+	if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(path) !== path ||
+		(privateMode && (stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0))) throw new Error("Unsafe candidate owner directory");
+	return `${stat.dev}:${stat.ino}`;
+}
+
+export function assertCandidateOwnerParent(commonDir: string): string {
+	directory(commonDir);
+	directory(join(commonDir, "gentle-ai"));
+	const parent = join(commonDir, "gentle-ai", "candidate-views");
+	directory(parent, true);
+	return parent;
+}
+
+function regular(path: string, privateMode = false): string {
+	const stat = lstatSync(path);
+	if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || realpathSync(path) !== path || stat.size > 16384 ||
+		(privateMode && (stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600))) throw new Error("Unsafe candidate owner file");
+	return `${stat.dev}:${stat.ino}`;
+}
+
+function syncDirectory(path: string): void {
+	const fd = openSync(path, "r");
+	try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function exclusiveFile(path: string, content: string): void {
+	const fd = openSync(path, "wx", 0o600);
+	try { writeFileSync(fd, content); fsyncSync(fd); } finally { closeSync(fd); }
+	syncDirectory(dirname(path));
+}
+
+function markerPath(root: string): string { return `${root}.owner.json`; }
+
+export function createCandidateOwner(commonDir: string, root: string): CandidateViewOwner {
+	const parent = assertCandidateOwnerParent(commonDir);
+	const uuid = basename(root);
+	if (!UUID.test(uuid) || root !== join(parent, uuid) || lstatSync(root, { throwIfNoEntry: false })) throw new Error("Unsafe candidate owner root");
+	const owner: CandidateViewOwner = { version: 1, uuid, token: randomUUID(), pid: process.pid, host: localHost(), root, commonDir };
+	// Any write/fsync failure aborts creation BEFORE Git can register the view.
+	// An incomplete marker is retained, never guessed into ownership.
+	exclusiveFile(markerPath(root), JSON.stringify(owner));
+	syncDirectory(dirname(parent));
+	syncDirectory(commonDir);
+	return Object.freeze(owner);
+}
+
+function readOwner(commonDir: string, root: string): CandidateViewOwner {
+	const parent = assertCandidateOwnerParent(commonDir);
+	if (!UUID.test(basename(root)) || root !== join(parent, basename(root))) throw new Error("Candidate owner escaped parent");
+	regular(markerPath(root), true);
+	const owner = JSON.parse(readFileSync(markerPath(root), "utf8")) as CandidateViewOwner;
+	if (!owner || Object.keys(owner).sort().join(",") !== "commonDir,host,pid,root,token,uuid,version" || owner.version !== 1 ||
+		owner.uuid !== basename(root) || !UUID.test(owner.token) || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 ||
+		owner.root !== root || owner.commonDir !== commonDir || !(owner.host === null || typeof owner.host === "string")) throw new Error("Malformed candidate owner");
+	return owner;
+}
+
+function dead(owner: CandidateViewOwner): boolean {
+	return owner.host !== null && owner.host === localHost() && conservativeOwnerDeathProofV1({
+		pid: owner.pid, token: owner.token, owner_hash: "", repository_id: owner.commonDir, authority_id: owner.uuid,
+	});
+}
+
+function registration(root: string, commonDir: string, git: Git): string {
+	const rows = git(["worktree", "list", "--porcelain", "-z"]).split("\0\0");
+	const matching = rows.filter((row) => row.split("\0")[0] === `worktree ${root}`);
+	if (matching.length !== 1 || matching[0]!.split("\0").some((field) => /^(locked|prunable)( |$)/.test(field))) throw new Error("Candidate registration is ambiguous");
+	const gitFile = join(root, ".git");
+	regular(gitFile);
+	const pointer = readFileSync(gitFile, "utf8");
+	if (!pointer.startsWith("gitdir: ") || !pointer.endsWith("\n")) throw new Error("Unsafe candidate Git pointer");
+	const admin = pointer.slice(8, -1);
+	if (dirname(admin) !== join(commonDir, "worktrees")) throw new Error("Candidate admin escaped common directory");
+	directory(join(commonDir, "worktrees"));
+	directory(admin);
+	regular(join(admin, "gitdir"));
+	regular(join(admin, "commondir"));
+	if (readFileSync(join(admin, "gitdir"), "utf8") !== `${gitFile}\n` ||
+		resolve(admin, readFileSync(join(admin, "commondir"), "utf8").trim()) !== commonDir) throw new Error("Candidate Git backlinks changed");
+	return matching[0]! + pointer;
+}
+
+export function removeCandidateOwner(owner: CandidateViewOwner, git: Git, makeWritable: (root: string) => void, orphan = false): void {
+	const { root, commonDir } = owner;
+	const parent = assertCandidateOwnerParent(commonDir);
+	const expected = JSON.stringify(owner);
+	const parentIdentity = directory(parent, true);
+	const markerIdentity = regular(markerPath(root), true);
+	const checkOwner = (): void => {
+		if (directory(parent, true) !== parentIdentity || regular(markerPath(root), true) !== markerIdentity ||
+			JSON.stringify(readOwner(commonDir, root)) !== expected || (orphan ? !dead(owner) : owner.pid !== process.pid)) throw new Error("Candidate ownership changed");
+	};
+	checkOwner();
+	const lock = `${root}.reaper-lock`;
+	const token = randomUUID();
+	exclusiveFile(lock, token); // EEXIST is final; unknown/stale locks are never stolen.
+	const lockIdentity = regular(lock, true);
+	const checkLock = (): void => {
+		if (regular(lock, true) !== lockIdentity || readFileSync(lock, "utf8") !== token) throw new Error("Candidate reaper lock changed");
+	};
+	try {
+		checkOwner();
+		const identity = [directory(parent, true), directory(root), regular(markerPath(root), true)];
+		const registered = registration(root, commonDir, git);
+		checkOwner();
+		checkLock();
+		makeWritable(root);
+		// Git and chmod are race boundaries: repeat path, owner, lock, and exact
+		// registration proofs immediately before asking Git to remove this root.
+		if (registration(root, commonDir, git) !== registered ||
+			JSON.stringify([directory(parent, true), directory(root), regular(markerPath(root), true)]) !== JSON.stringify(identity)) throw new Error("Candidate cleanup identity changed");
+		checkOwner();
+		checkLock();
+		git(["worktree", "remove", "--force", root]);
+		// Git failure or incomplete removal must never trigger recursive rm.
+		if (lstatSync(root, { throwIfNoEntry: false }) || git(["worktree", "list", "--porcelain", "-z"]).split("\0").includes(`worktree ${root}`)) throw new Error("Candidate removal is incomplete");
+		checkOwner();
+		checkLock();
+		unlinkSync(markerPath(root));
+		syncDirectory(parent);
+	} finally {
+		// Only release this exact lock, even when the deletion itself failed.
+		try { assertCandidateOwnerParent(commonDir); checkLock(); unlinkSync(lock); syncDirectory(parent); } catch {}
+	}
+}
+
+export function sweepCandidateOwners(commonDir: string, git: Git, makeWritable: (root: string) => void): void {
+	try {
+		const parent = assertCandidateOwnerParent(commonDir);
+		for (const name of readdirSync(parent)) {
+			if (!name.endsWith(".owner.json")) continue;
+			try {
+				const owner = readOwner(commonDir, join(parent, name.slice(0, -11)));
+				if (dead(owner)) removeCandidateOwner(owner, git, makeWritable, true);
+			} catch { /* Unknown, legacy, unsafe, unregistered, and contended entries survive. */ }
+		}
+	} catch { /* Startup/materialization sweeps are best-effort; never create a store. */ }
+}

package/lib/review-candidate-view.ts

@@ -1,10 +1,11 @@
 import { execFileSync, type ExecFileSyncOptions } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, utimesSync } from "node:fs";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
+import { assertCandidateOwnerParent, createCandidateOwner, removeCandidateOwner, sweepCandidateOwners, type CandidateViewOwner } from "./review-candidate-view-owner.ts";
 
 const REVIEW_LENS = ["review-risk", "review-resilience", "review-readability", "review-reliability"] as const;
 export type ReviewLens = (typeof REVIEW_LENS)[number];
@@ -12,6 +13,11 @@ const CANDIDATE_GIT_TIMEOUT_MS = 10_000;
 const CANDIDATE_GIT_TIMEOUT_MAX_MS = 120_000;
 const CANDIDATE_GIT_TIMEOUT_ENV = "GENTLE_PI_CANDIDATE_GIT_TIMEOUT_MS";
 const CANDIDATE_GIT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+// Keep the copied index at least one timestamp tick behind its source. The
+// two-second target also clears filesystems whose mtime granularity is a second
+// or coarser without needlessly assigning an arbitrary historical timestamp.
+const PRIVATE_INDEX_RACY_SAFETY_NS = 1_000_000_000n;
+const PRIVATE_INDEX_RACY_BACKDATE_NS = 2_000_000_000n;
 
 // Candidate views may materialize full repository trees. Large repositories can
 // raise this bounded deadline without creating an unbounded child process.
@@ -94,6 +100,7 @@ interface CandidateViewScope {
 }
 
 interface CandidateViewRecord {
+	owner: CandidateViewOwner;
 	token: string;
 	root: string;
 	parent: string;
@@ -333,12 +340,37 @@ function isMaterializedCandidateMode(mode: string): boolean {
 	return mode === "100644" || mode === "100755" || mode === "120000";
 }
 
+export function hasExpectedExecutableBits(filesystemMode: number, gitMode: string, platform: NodeJS.Platform = process.platform): boolean {
+	return gitMode === "100755" && platform === "win32"
+		|| (filesystemMode & 0o111) === (gitMode === "100755" ? 0o111 : 0);
+}
+
 function isCanonicalObjectId(objectId: string): boolean { return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(objectId); }
 function gitlinkMapsEqual(left: Readonly<Record<string, string>>, right: Readonly<Record<string, string>>): boolean {
 	const entries = Object.entries(left);
 	return entries.length === Object.keys(right).length && entries.every(([path, objectId]) => right[path] === objectId);
 }
 
+// Two materialized candidate views describe the exact same reviewable content
+// when their base, candidate tree, commit-state, and changed scope all match.
+// This is what makes a retried native START's freshly-materialized duplicate
+// view safely discardable in favor of an already-bound one (gentle-pi
+// candidate-view rebind defect, ga#4085 / ga#4050): the comparison never
+// trusts a caller-supplied claim, only Git-derived identity already computed
+// by materializeCandidateView for both records.
+function candidateRecordsShareIdentity(left: CandidateViewRecord, right: CandidateViewRecord): boolean {
+	return left.contributorRoot === right.contributorRoot &&
+		left.baseCommit === right.baseCommit &&
+		left.baseTree === right.baseTree &&
+		left.candidateTree === right.candidateTree &&
+		left.committedOnly === right.committedOnly &&
+		JSON.stringify(left.intendedUntracked ?? null) === JSON.stringify(right.intendedUntracked ?? null) &&
+		JSON.stringify(left.scope.paths) === JSON.stringify(right.scope.paths) &&
+		JSON.stringify(left.scope.modes) === JSON.stringify(right.scope.modes) &&
+		gitlinkMapsEqual(left.scope.gitlinks, right.scope.gitlinks) &&
+		JSON.stringify(left.scope.deletedPaths) === JSON.stringify(right.scope.deletedPaths);
+}
+
 function decodeCanonicalPath(value: Buffer): string {
 	const path = value.toString("utf8");
 	if (!Buffer.from(path, "utf8").equals(value) || !isSafeCandidatePath(path)) {
@@ -603,11 +635,15 @@ function makeWritableForCleanup(path: string): void {
 }
 
 function candidateViewParent(commonDir: string): string {
-	const parent = join(commonDir, "gentle-ai", "candidate-views");
+	const control = join(commonDir, "gentle-ai");
+	mkdirSync(control, { recursive: true, mode: 0o700 });
+	const controlStat = lstatSync(control);
+	if (!controlStat.isDirectory() || controlStat.isSymbolicLink() || realpathSync(control) !== control) throw new CandidateViewError("candidate view ancestor is unsafe");
+	const parent = join(control, "candidate-views");
 	mkdirSync(parent, { recursive: true, mode: 0o700 });
 	const stat = lstatSync(parent);
 	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new CandidateViewError("candidate view parent is unsafe");
-	return realpathSync(parent);
+	return assertCandidateOwnerParent(commonDir);
 }
 
 export interface ResolvedCandidateBase {
@@ -780,11 +816,29 @@ function isErrnoCode(error: unknown, code: string): boolean {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
+function timestampSeconds(timestampNs: bigint): number {
+	// Node's utimes API takes Unix seconds as a number. Splitting the value keeps
+	// the seconds conversion exact; the explicit racy-clean backdate below is far
+	// larger than the fractional precision a Number can represent at this epoch.
+	return Number(timestampNs / 1_000_000_000n) + Number(timestampNs % 1_000_000_000n) / 1_000_000_000;
+}
+
 function seedPrivateIndexFromLiveIndex(cwd: string, indexPath: string, executor: CandidateGitExecutor): boolean {
 	const liveIndex = resolve(cwd, git(cwd, ["rev-parse", "--path-format=absolute", "--git-path", "index"], process.env, executor));
-	const entry = lstatSync(liveIndex, { throwIfNoEntry: false });
+	const entry = lstatSync(liveIndex, { bigint: true, throwIfNoEntry: false });
 	if (entry === undefined) return false; if (!entry.isFile()) throw new CandidateViewError("candidate live Git index is not a regular file");
+	if (entry.mtimeNs < PRIVATE_INDEX_RACY_BACKDATE_NS) throw new CandidateViewError("candidate live Git index timestamp is too early for racy-clean protection");
 	copyFileSync(liveIndex, indexPath);
+	// Git's racy-clean check compares index and tracked-file mtimes. copyFileSync
+	// gives the private index a new timestamp; restoring a Date can also lose
+	// nanoseconds. Backdate the bigint live timestamp instead, then verify the
+	// filesystem applied enough of that bounded interval for Git to refresh
+	// content rather than trusting a racy-clean stat match.
+	utimesSync(indexPath, timestampSeconds(entry.atimeNs), timestampSeconds(entry.mtimeNs - PRIVATE_INDEX_RACY_BACKDATE_NS));
+	const privateMtimeNs = lstatSync(indexPath, { bigint: true }).mtimeNs;
+	if (privateMtimeNs >= entry.mtimeNs || entry.mtimeNs - privateMtimeNs < PRIVATE_INDEX_RACY_SAFETY_NS) {
+		throw new CandidateViewError("candidate private Git index timestamp cannot preserve racy-clean protection");
+	}
 	for (const name of readdirSync(dirname(liveIndex))) if (/^sharedindex\.[0-9a-f]+$/.test(name)) {
 		try {
 			const sharedIndex = join(dirname(liveIndex), name);
@@ -809,6 +863,7 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 		? resolveCandidateBase(contributorRoot, "HEAD", process.env, executor)
 		: base;
 	const parent = candidateViewParent(canonicalCommonDir);
+	sweepCandidateOwners(canonicalCommonDir, (args) => git(canonicalCommonDir, args, process.env, executor), makeWritableForCleanup);
 	const index = mkdtempSync(join(tmpdir(), "gentle-ai-candidate-index-"));
 	const indexPath = join(index, "index");
 	const environment = { ...process.env, GIT_INDEX_FILE: indexPath };
@@ -832,6 +887,7 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 		}
 		const candidateTree = git(contributorRoot, ["write-tree"], environment, executor);
 		const root = join(parent, randomUUID());
+		const owner = createCandidateOwner(canonicalCommonDir, root);
 		// The worktree is created under the same try/catch cleanup boundary as
 		// the read-tree materialization that follows. addUnbornWorktree's
 		// fallback path can register a worktree with `worktree add` and then
@@ -852,9 +908,9 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 			const scope = deriveChangedScope(contributorRoot, base.tree, candidateTree, [...tree.entries, ...tree.gitlinks], executor);
 			for (const gitlink of tree.gitlinks) if (lstatSync(join(root, gitlink.path), { throwIfNoEntry: false })) throw new CandidateViewError("candidate view materialized a metadata-only gitlink");
 			makeReadonly(root, entries);
-			return { token: basename(root), root: realpathSync(root), parent, contributorRoot, commonDir: canonicalCommonDir, baseCommit, baseTree: base.tree, candidateTree, committedOnly, intendedUntracked, entries, gitlinks: tree.gitlinks, scope, gitExecutor: executor };
+			return { owner, token: basename(root), root: realpathSync(root), parent, contributorRoot, commonDir: canonicalCommonDir, baseCommit, baseTree: base.tree, candidateTree, committedOnly, intendedUntracked, entries, gitlinks: tree.gitlinks, scope, gitExecutor: executor };
 		} catch (error) {
-			try { git(contributorRoot, ["worktree", "remove", "--force", root], process.env, executor); } catch { rmSync(root, { recursive: true, force: true }); }
+			try { removeCandidateOwner(owner, (args) => git(canonicalCommonDir, args, process.env, executor), makeWritableForCleanup); } catch { /* Preserve the marker and any partial worktree for conservative recovery. */ }
 			throw error;
 		}
 	} finally {
@@ -862,7 +918,7 @@ function materializeCandidateView(request: CreateCandidateViewRequest, executor:
 	}
 }
 
-function assertRecordSafe(record: CandidateViewRecord): void {
+function assertRecordSafe(record: CandidateViewRecord, platform: NodeJS.Platform = process.platform): void {
 	try {
 		const contributor = lstatSync(record.contributorRoot);
 		if (!contributor.isDirectory() || contributor.isSymbolicLink() || realpathSync(record.contributorRoot) !== record.contributorRoot) {
@@ -902,7 +958,7 @@ function assertRecordSafe(record: CandidateViewRecord): void {
 		if (!item) throw new CandidateViewError("candidate view entry is missing or moved");
 		if (entry.mode === "120000") {
 			if (!item.isSymbolicLink()) throw new CandidateViewError("candidate view symlink is unsafe or changed");
-		} else if (!item.isFile() || item.isSymbolicLink() || (item.mode & 0o222) !== 0 || ((item.mode & 0o111) !== (entry.mode === "100755" ? 0o111 : 0))) {
+		} else if (!item.isFile() || item.isSymbolicLink() || (item.mode & 0o222) !== 0 || !hasExpectedExecutableBits(item.mode, entry.mode, platform)) {
 			throw new CandidateViewError("candidate view entry is unsafe, writable, or has a changed mode");
 		}
 		const actualHash = entryContentHash(root, entry);
@@ -913,8 +969,10 @@ function assertRecordSafe(record: CandidateViewRecord): void {
 export class CandidateViewRegistry {
 	private readonly records = new Map<string, CandidateViewRecord>();
 	private readonly gitExecutor: CandidateGitExecutor;
-	constructor(gitExecutor: CandidateGitExecutor = defaultCandidateGitExecutor) {
+	private readonly platform: NodeJS.Platform;
+	constructor(gitExecutor: CandidateGitExecutor = defaultCandidateGitExecutor, platform: NodeJS.Platform = process.platform) {
 		this.gitExecutor = gitExecutor;
+		this.platform = platform;
 	}
 	// Lifecycle state is scoped to the canonical target worktree as well as the
 	// provider lineage. Lineage text is repository-local and may legitimately be
@@ -1000,15 +1058,25 @@ export class CandidateViewRegistry {
 		const key = this.lineageKey(contributorRoot, lineageId);
 		const token = this.lineages.get(key);
 		const record = token === undefined ? undefined : this.records.get(token);
-		if (record !== undefined) assertRecordSafe(record);
+		if (record !== undefined) assertRecordSafe(record, this.platform);
 	}
 
 	create(request: CreateCandidateViewRequest): CandidateView {
 		return this.createOrReuse(request);
 	}
 
+	sweepOrphans(contributorRoot: string): void {
+		try {
+			const cwd = realpathSync(contributorRoot);
+			const common = realpathSync(resolve(cwd, git(cwd, ["rev-parse", "--git-common-dir"], process.env, this.gitExecutor)));
+			sweepCandidateOwners(common, (args) => git(common, args, process.env, this.gitExecutor), makeWritableForCleanup);
+		} catch { /* Non-repositories and unavailable ownership are preserved. */ }
+	}
+
 	cleanupAll(): void {
-		for (const token of [...this.records.keys()]) this.cleanup(token);
+		for (const token of [...this.records.keys()]) {
+			try { this.cleanup(token); } catch { /* Continue other owned views; failed records remain retryable. */ }
+		}
 	}
 
 	createOrReuse(request: CreateCandidateViewRequest): CandidateView {
@@ -1017,7 +1085,7 @@ export class CandidateViewRegistry {
 		const scopedReplayKey = normalizedRequest.replayKey === undefined ? undefined : this.replayKey(contributorRoot, normalizedRequest.replayKey);
 		const token = scopedReplayKey === undefined ? undefined : this.replays.get(scopedReplayKey);
 		const existing = token === undefined ? undefined : this.records.get(token);
-		if (existing) { assertRecordSafe(existing); return this.expose(existing); }
+		if (existing) { assertRecordSafe(existing, this.platform); return this.expose(existing); }
 		const record = materializeCandidateView(normalizedRequest, this.gitExecutor);
 		this.records.set(record.token, record);
 		if (scopedReplayKey !== undefined) this.replays.set(scopedReplayKey, record.token);
@@ -1030,6 +1098,32 @@ export class CandidateViewRegistry {
 
 	bindCurrent(request: BindCandidateViewRequest): void {
 		const selectedLenses = this.validateSelectedLenses(request.selectedLenses);
+		const candidate = this.records.get(request.token);
+		const key = candidate === undefined ? undefined : this.lineageKey(candidate.contributorRoot, request.lineageId);
+		const existingToken = key === undefined ? undefined : this.lineages.get(key);
+		// 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 before it reaches here.
+		// Rebinding that duplicate to the same lineage key used to fail closed
+		// with "candidate view lineage binding is missing or ambiguous" even
+		// though nothing is actually ambiguous: it is the exact same reviewable
+		// content, re-verified from Git. Discard the redundant duplicate and
+		// keep the already-bound view current instead of failing the retry
+		// (gentle-pi candidate-view rebind defect, ga#4085 / ga#4050).
+		if (candidate !== undefined && existingToken !== undefined && existingToken !== request.token) {
+			const existing = this.records.get(existingToken);
+			let existingSafe = false;
+			if (existing !== undefined && existing.lineageId === request.lineageId) {
+				try { assertRecordSafe(existing, this.platform); existingSafe = true; } catch { existingSafe = false; }
+			}
+			if (existing !== undefined && existingSafe && candidateRecordsShareIdentity(existing, candidate)) {
+				existing.selectedLenses = selectedLenses;
+				this.remove(candidate);
+				this.forget(candidate);
+				this.current.set(existing.contributorRoot, { lineageId: request.lineageId, token: existingToken });
+				return;
+			}
+		}
 		const record = this.bindRecord(request.token, request.lineageId, selectedLenses);
 		this.current.set(record.contributorRoot, { lineageId: request.lineageId, token: request.token });
 	}
@@ -1043,7 +1137,7 @@ export class CandidateViewRegistry {
 		const record = this.records.get(request.token);
 		if (!record || record.lineageId !== undefined) throw new CandidateViewError("native reviewing candidate view is missing or already bound", "authoritative-current-match-missing");
 		if (this.current.has(record.contributorRoot)) throw new CandidateViewError("candidate view already has a current lineage binding", "current-binding-already-established");
-		assertRecordSafe(record);
+		assertRecordSafe(record, this.platform);
 		this.assertCurrentBindingMatchesLiveCandidate(record);
 		this.bindCurrent(request);
 	}
@@ -1085,7 +1179,7 @@ export class CandidateViewRegistry {
 		const existing = existingToken === undefined ? undefined : this.records.get(existingToken);
 		if (existing) {
 			if (existing.lineageId !== undefined) throw new CandidateViewError("corrected candidate replay is no longer pending");
-			assertRecordSafe(existing);
+			assertRecordSafe(existing, this.platform);
 			return this.expose(existing);
 		}
 		const record = materializeCandidateView({ contributorRoot: root, baseRef: projection.baseCommit, committedOnly: projection.committedOnly, ...(projection.intendedUntracked === undefined ? {} : { intendedUntracked: projection.intendedUntracked }) }, this.gitExecutor);
@@ -1115,8 +1209,8 @@ export class CandidateViewRegistry {
 		if (currentBinding !== undefined && currentBinding.lineageId !== lineageId) {
 			throw new CandidateViewError("corrected candidate replacement conflicts with the current lineage binding");
 		}
-		assertRecordSafe(replacement);
-		if (current) assertRecordSafe(current);
+		assertRecordSafe(replacement, this.platform);
+		if (current) assertRecordSafe(current, this.platform);
 		if (
 			replacement.contributorRoot !== projection.contributorRoot ||
 			replacement.baseCommit !== projection.baseCommit ||
@@ -1177,7 +1271,7 @@ export class CandidateViewRegistry {
 		const record = this.records.get(token);
 		const key = record === undefined ? undefined : this.lineageKey(record.contributorRoot, lineageId);
 		if (!record || record.lineageId !== undefined || !key || this.lineages.has(key)) throw new CandidateViewError("candidate view lineage binding is missing or ambiguous");
-		assertRecordSafe(record);
+		assertRecordSafe(record, this.platform);
 		record.lineageId = lineageId;
 		record.selectedLenses = selectedLenses;
 		this.lineages.set(key, record.token);
@@ -1276,21 +1370,18 @@ export class CandidateViewRegistry {
 	 * correction.
 	 */
 	rebindForFinalizeFromNative(lineageId: string, contributorRoot: string, descriptor: NativeCandidateProjectionDescriptor): CandidateView {
-		const root = this.canonicalRoot(contributorRoot);
-		const key = this.lineageKey(root, lineageId);
-		const staleToken = this.lineages.get(key);
-		const stale = staleToken === undefined ? undefined : this.records.get(staleToken);
-		this.projections.delete(key);
-		if (stale !== undefined) {
-			this.remove(stale);
-			this.forget(stale);
-		}
-		return this.restoreForFinalizeFromNative(lineageId, root, descriptor);
+		return this.restoreForFinalizeFromNative(lineageId, contributorRoot, descriptor);
 	}
 
+	/**
+	 * Restores a lineage's FINALIZE binding (gentle-pi #185): the stale entry
+	 * is only detached, not destroyed, so a failed restore can undo it.
+	 */
 	restoreForFinalizeFromNative(lineageId: string, contributorRoot: string, descriptor: NativeCandidateProjectionDescriptor): CandidateView {
 		const root = this.canonicalRoot(contributorRoot);
 		const key = this.lineageKey(root, lineageId);
+		const staleToken = this.lineages.get(key), staleProjection = this.projections.get(key);
+		this.lineages.delete(key); this.projections.delete(key);
 		let projectionRestored = false;
 		let record: CandidateViewRecord | undefined;
 		try {
@@ -1308,6 +1399,8 @@ export class CandidateViewRegistry {
 			if (!matchesProjection(record)) throw new CandidateViewError("live candidate does not match the native frozen projection");
 			this.records.set(record.token, record);
 			this.bindRecord(record.token, lineageId, []);
+			const stale = staleToken === undefined ? undefined : this.records.get(staleToken);
+			if (stale !== undefined) { this.remove(stale); this.forget(stale); }
 			return this.expose(record);
 		} catch (error) {
 			if (projectionRestored) this.projections.delete(key);
@@ -1315,6 +1408,8 @@ export class CandidateViewRegistry {
 				this.forget(record);
 				this.remove(record);
 			}
+			if (staleToken !== undefined) this.lineages.set(key, staleToken);
+			if (staleProjection !== undefined) this.projections.set(key, staleProjection);
 			throw error;
 		}
 	}
@@ -1375,7 +1470,7 @@ export class CandidateViewRegistry {
 		const token = this.lineages.get(key);
 		const record = token === undefined ? undefined : this.records.get(token);
 		if (!record || record.lineageId !== lineageId || !record.selectedLenses?.includes(lens as ReviewLens)) throw new CandidateViewError("candidate view context is missing, ambiguous, stale, or lens-unselected");
-		assertRecordSafe(record);
+		assertRecordSafe(record, this.platform);
 		return this.expose(record);
 	}
 
@@ -1426,7 +1521,7 @@ export class CandidateViewRegistry {
 		const current = this.currentBinding(contributorRoot);
 		const record = this.records.get(current.token);
 		if (!record || record.lineageId !== current.lineageId || this.lineages.get(this.lineageKey(current.root, current.lineageId)) !== current.token) throw new CandidateViewError("review subagent dispatch current lineage binding is stale or ambiguous", "current-binding-stale");
-		assertRecordSafe(record);
+		assertRecordSafe(record, this.platform);
 		this.assertCurrentBindingMatchesLiveCandidate(record);
 		if (!lenses.every((lens) => record.selectedLenses?.includes(lens as ReviewLens))) throw new CandidateViewError("candidate view context is missing, ambiguous, stale, or lens-unselected", "current-binding-lens-unselected");
 		return lenses.map(() => this.expose(record));
@@ -1455,7 +1550,7 @@ export class CandidateViewRegistry {
 		const token = this.lineages.get(key);
 		const record = token === undefined ? undefined : this.records.get(token);
 		if (!record || record.lineageId !== lineageId) throw new CandidateViewError("candidate view context is missing or ambiguous for FINALIZE");
-		assertRecordSafe(record);
+		assertRecordSafe(record, this.platform);
 		return this.expose(record);
 	}
 
@@ -1476,10 +1571,7 @@ export class CandidateViewRegistry {
 
 	private remove(record: CandidateViewRecord): void {
 		if (!isWithin(record.parent, record.root)) throw new CandidateViewError("candidate view cleanup escaped its owned parent");
-		try { makeWritableForCleanup(record.root); } catch {}
-		try { git(record.contributorRoot, ["worktree", "remove", "--force", record.root], process.env, record.gitExecutor); } catch {}
-		// Git removes worktree metadata; physical removal remains this owner's duty.
-		rmSync(record.root, { recursive: true, force: true });
+		removeCandidateOwner(record.owner, (args) => git(record.commonDir, args, process.env, record.gitExecutor), makeWritableForCleanup);
 	}
 
 	private forget(record: CandidateViewRecord): void {
@@ -1511,7 +1603,7 @@ export class CandidateViewRegistry {
 			modes: record.scope.modes,
 			gitlinks: record.scope.gitlinks,
 			deletedPaths: record.scope.deletedPaths,
-			verify: () => assertRecordSafe(record),
+			verify: () => assertRecordSafe(record, this.platform),
 			cleanup: () => this.cleanup(record.token),
 		};
 	}

package/lib/review-consent-ui.ts

@@ -0,0 +1,65 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ReviewConsentEnvelope, ReviewConsentV3 } from "./review-integration-v2.ts";
+
+export const HOST_REVIEW_SESSION_PERMISSION_LABEL = "Run this review and allow reviews for this Pi session";
+
+const HOST_REVIEW_SESSION_PERMISSION_EFFECT =
+	"Runs the provider's exact grant for this frozen candidate, then lets the Pi host use each later candidate's fresh validated provider grant once while this exact Pi session and canonical Git repository identity, including sibling worktrees, remain active. Reload keeps it; new, resume, fork, quit, process restart, or explicit revocation ends it. It grants no verdict, acknowledgement, maintenance, delivery, or cross-repository authority.";
+
+export type ReviewConsentUiSelection =
+	| { kind: "provider"; answer: "granted" | "declined" }
+	| { kind: "host-session" };
+
+export interface ReviewConsentUiModel {
+	readonly title: string;
+	readonly options: readonly [string, string, string];
+}
+
+export function isPiConsentV3(consent: ReviewConsentEnvelope): consent is ReviewConsentV3 {
+	return consent.schema === "gentle-ai.review-integration.consent/v3" && consent.agent === "pi";
+}
+
+export function formatReviewConsentUi(consent: ReviewConsentV3): ReviewConsentUiModel {
+	const evidence = consent.riskEvidence.map((item) => `- ${item}`).join("\n");
+	const title = [
+		consent.headline,
+		"",
+		`Reason: ${consent.reason}`,
+		`Value: ${consent.value}`,
+		`Risk: ${consent.riskLevel}; ${consent.changedFiles} changed file(s), ${consent.changedLines} changed line(s).`,
+		`Target: ${consent.targetIdentity}`,
+		`Projection: ${consent.projection}`,
+		"Risk evidence:",
+		evidence,
+		"",
+		"Ownership: The first two actions are provider-owned and apply only to this candidate. The third action is owned by the Pi host and controls only an in-memory permission for this exact Pi session and canonical Git repository identity, including sibling worktrees.",
+		"",
+		`Off-path note: ${consent.offPath.note}`,
+		`Off-path command: ${consent.offPath.command}`,
+	].join("\n");
+	return {
+		title,
+		options: [
+			`1. ${consent.choices[0].label}\nEffect: ${consent.choices[0].effect}`,
+			`2. ${consent.choices[1].label}\nEffect: ${consent.choices[1].effect}`,
+			`3. ${HOST_REVIEW_SESSION_PERMISSION_LABEL}\nEffect: ${HOST_REVIEW_SESSION_PERMISSION_EFFECT}`,
+		],
+	};
+}
+
+export async function presentReviewConsentUi(
+	context: ExtensionContext,
+	consent: ReviewConsentEnvelope,
+): Promise<ReviewConsentUiSelection | undefined> {
+	if (!isPiConsentV3(consent)) return undefined;
+	const model = formatReviewConsentUi(consent);
+	try {
+		const selected = await context.ui.select(model.title, [...model.options]);
+		if (selected === model.options[0]) return { kind: "provider", answer: "granted" };
+		if (selected === model.options[1]) return { kind: "provider", answer: "declined" };
+		if (selected === model.options[2]) return { kind: "host-session" };
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}