gentle-pi 2.4.0 → 2.5.0

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;
+	}
+}

package/lib/review-integration-v2.ts

@@ -79,7 +79,10 @@ const RISK_LEVELS = ["low", "medium", "high"] as const;
 const REVIEW_LENSES = ["review-risk", "review-resilience", "review-readability", "review-reliability"] as const;
 const RISK_REASON_CODES = ["configuration_change", "empty_content", "executable_change", "executable_mode", "hot_path", "large_change", "non_executable_only", "process_boundary", "process_scan_limit", "service_token", "shell_source"] as const;
 const RISK_SIGNALS = ["auth", "update", "security", "payments", "permissions", "shell_process"] as const;
-const STATUS_ACTIONS = ["start", "recover", "maintainer_action", "select_lineage", "repair_authority", "stop"] as const;
+// "collect" and "execute" are the v2 envelope's projection of a live
+// transaction whose next_transition is mandatory: the root action names the
+// transition kind instead of reading as a terminal stop.
+const STATUS_ACTIONS = ["start", "recover", "maintainer_action", "select_lineage", "repair_authority", "stop", "collect", "execute"] as const;
 const RECEIPT_STATUSES = ["expected_missing", "present", "publication_pending", "not_applicable"] as const;
 type ReviewReceiptStatus = (typeof RECEIPT_STATUSES)[number];
 export const REVIEW_STATUS_ACTION_DISPOSITION = {
@@ -385,6 +388,8 @@ export interface ReviewStatusFrozenV1 {
 	tier: RiskLevel;
 	originalChangedLines: number;
 	correctionBudget: number;
+	/** Digest of the frozen changed-path manifest; binds manifest-less capture inputs (gentle-ai#3922). */
+	changedPathManifestSha256?: string;
 }
 
 export interface ReviewStatusReconciliationV1 {
@@ -545,6 +550,16 @@ export interface ReviewCollectInputV3 {
 	validationRequest?: ReviewTargetedValidationRequestV1;
 }
 
+// gentle-pi#627: the exact `gentle-ai sync` invocation that resolves a stale
+// managed-asset set (STATUS next_transition stop, and START's preflight
+// failure envelope both carry this same shape).
+export interface ReviewManagedAssetsContinuationV1 {
+	operation: "sync";
+	command: string;
+	agent?: string;
+	staleAssets?: readonly string[];
+}
+
 export interface ReviewNextTransitionV3 {
 	kind: "execute" | "collect" | "stop";
 	reasonCode: string;
@@ -552,6 +567,8 @@ export interface ReviewNextTransitionV3 {
 	collect?: { inputs: readonly ReviewCollectInputV3[] };
 	/** status/v5 only: the bounded correction plan request. */
 	correctionRequest?: ReviewCorrectionPlanRequestV1;
+	/** stop only, reason_code managed_assets_outdated: the sync continuation. */
+	continuation?: ReviewManagedAssetsContinuationV1;
 }
 
 export interface ReviewStatusV3 {
@@ -705,6 +722,8 @@ export interface ReviewFailureV2 {
 	causeCategory?: ReviewFailureCauseCategoryV2;
 	cause?: string;
 	context?: ReviewFailureContextV2;
+	/** code=managed_assets_outdated only: the sync continuation (gentle-pi#627). */
+	continuation?: ReviewManagedAssetsContinuationV1;
 	raw: Readonly<Record<string, unknown>>;
 }
 
@@ -1639,8 +1658,11 @@ function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: bool
 	}
 
 	if (captureOperation === "review.capture-result") {
-		if (input.artifact_subject === undefined || input.base_tree === undefined || input.candidate_tree === undefined || input.changed_path_manifest === undefined) {
-			throw new TypeError(`${label} requires artifact_subject, base_tree, candidate_tree, and changed_path_manifest`);
+		// changed_path_manifest is optional here: the artifact subject's
+		// changed_path_manifest_sha256 already binds the frozen manifest, and
+		// gentle-ai stops inlining one copy per lens (gentle-ai#3922).
+		if (input.artifact_subject === undefined || input.base_tree === undefined || input.candidate_tree === undefined) {
+			throw new TypeError(`${label} requires artifact_subject, base_tree, and candidate_tree`);
 		}
 		if (schema !== "https://gentle-ai.dev/schema/review/reviewer/v1") throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/reviewer/v1`);
 	} else if (input.artifact_subject !== undefined || input.base_tree !== undefined || input.candidate_tree !== undefined || input.changed_path_manifest !== undefined) {
@@ -1673,12 +1695,32 @@ function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: bool
 	};
 }
 
+// gentle-pi#627: gentle-ai's managed-assets continuation (STATUS next_transition
+// stop reason_code=managed_assets_outdated, and START's preflight failure
+// envelope) names the exact `gentle-ai sync` invocation that resolves a stale
+// managed-asset set without abandoning the frozen candidate. Decoded verbatim
+// from internal/cli/review_operation_contract.go's ReviewManagedAssetsContinuation.
+export function decodeReviewManagedAssetsContinuationV1(value: unknown, label: string): ReviewManagedAssetsContinuationV1 {
+	const body = exactRecord(value, label, ["operation", "command"], ["agent", "stale_assets"]);
+	const operation = enumeration(body.operation, ["sync"] as const, `${label}.operation`);
+	const command = nonempty(body.command, `${label}.command`);
+	const agent = body.agent === undefined ? undefined : nonempty(body.agent, `${label}.agent`);
+	const staleAssets = body.stale_assets === undefined ? undefined : stringArray(body.stale_assets, `${label}.stale_assets`, { minimum: 1 });
+	return { operation, command, ...(agent === undefined ? {} : { agent }), ...(staleAssets === undefined ? {} : { staleAssets }) };
+}
+
 export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boolean; v6?: boolean } = {}): ReviewNextTransitionV3 {
 	const v6 = options.v6 === true;
 	const v5 = options.v5 === true || v6;
-	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : [])]);
+	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation"]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"] as const, "next_transition.kind");
 	const reasonCode = text(transition.reason_code, "next_transition.reason_code", { minimum: 1, pattern: /^[a-z0-9_]+$/ });
+	const continuation = transition.continuation === undefined ? undefined : decodeReviewManagedAssetsContinuationV1(transition.continuation, "next_transition.continuation");
+	// gentle-pi#627: continuation is optional on every status version an older
+	// gentle-ai may emit a managed_assets_outdated stop with no continuation at
+	// all, and decode must not refuse the whole envelope for that. When present
+	// it is only valid on a stop with this exact reason_code.
+	if (continuation !== undefined && !(kind === "stop" && reasonCode === "managed_assets_outdated")) throw new TypeError("next_transition.continuation is only valid for a stop transition with reason_code managed_assets_outdated");
 
 	// status/v5: the bounded correction plan request rides exactly its two
 	// reason codes and never any other (vendored status-v5.schema.json).
@@ -1728,7 +1770,7 @@ export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boo
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
 	if (transition.execute !== undefined || transition.collect !== undefined) throw new TypeError("next_transition stop cannot carry a transition");
-	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
+	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }), ...(continuation === undefined ? {} : { continuation }) };
 }
 
 // ---------------------------------------------------------------------------
@@ -1817,11 +1859,12 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 
 	let frozen: ReviewStatusFrozenV1 | undefined;
 	if (body.frozen !== undefined) {
-		const source = exactRecord(body.frozen, "status.frozen", ["tier", "original_changed_lines", "correction_budget"]);
+		const source = exactRecord(body.frozen, "status.frozen", ["tier", "original_changed_lines", "correction_budget"], ["changed_path_manifest_sha256"]);
 		frozen = {
 			tier: enumeration(source.tier, RISK_LEVELS, "status.frozen.tier"),
 			originalChangedLines: integer(source.original_changed_lines, "status.frozen.original_changed_lines"),
 			correctionBudget: integer(source.correction_budget, "status.frozen.correction_budget", 0, 200),
+			...(source.changed_path_manifest_sha256 === undefined ? {} : { changedPathManifestSha256: sha256(source.changed_path_manifest_sha256, "status.frozen.changed_path_manifest_sha256") }),
 		};
 	}
 	if (authority?.version === REVIEW_AUTHORITY_VERSION.COMPACT_V2 && frozen === undefined) throw new TypeError("compact-v2 status requires frozen metadata");
@@ -2048,9 +2091,10 @@ function decodeFailureContext(value: unknown, label: string): ReviewFailureConte
 export function decodeReviewFailureV2(value: unknown): ReviewFailureV2 {
 	const body = exactRecord(value, "failure", [
 		"schema", "contract", "operation", "phase", "code", "message", "mutation_outcome", "authority_applicability", "retry_safe", "replayability", "required_inputs", "next_action",
-	], ["lineage_id", "request_digest", "progress_identity", "cause_category", "cause", "context"]);
+	], ["lineage_id", "request_digest", "progress_identity", "cause_category", "cause", "context", "continuation"]);
 	requireIdentity(body, "gentle-ai.review-integration.failure/v2");
 	const operation = enumeration(body.operation, FAILURE_OPERATIONS, "failure.operation");
+	const code = text(body.code, "failure.code", { pattern: /^[a-z0-9]+(?:_[a-z0-9]+)*$/ });
 
 	if (body.progress_identity !== undefined) {
 		if (body.lineage_id === undefined || body.request_digest === undefined) throw new TypeError("failure.progress_identity requires lineage_id and request_digest");
@@ -2059,13 +2103,18 @@ export function decodeReviewFailureV2(value: unknown): ReviewFailureV2 {
 	if (body.request_digest !== undefined && operation === REVIEW_INTEGRATION_OPERATION.REPAIR && body.progress_identity === undefined) {
 		throw new TypeError("failure.request_digest with review.repair requires progress_identity");
 	}
+	// gentle-pi#627: continuation is optional on every version — an older
+	// gentle-ai may emit managed_assets_outdated with no continuation, and
+	// decode must not refuse the whole envelope for that. When present it is
+	// only valid on this exact code.
+	if (body.continuation !== undefined && code !== "managed_assets_outdated") throw new TypeError("failure.continuation is only valid for code managed_assets_outdated");
 
 	return {
 		schema: "gentle-ai.review-integration.failure/v2",
 		contract: REVIEW_INTEGRATION_CONTRACT,
 		operation,
 		phase: enumeration(body.phase, ["preflight", "pre_native", "native_running", "native_committed", "reconciliation"] as const, "failure.phase"),
-		code: text(body.code, "failure.code", { pattern: /^[a-z0-9]+(?:_[a-z0-9]+)*$/ }),
+		code,
 		message: text(body.message, "failure.message", { minimum: 1, maximum: 240, pattern: /^[^\r\n]+$/ }),
 		mutationOutcome: enumeration(body.mutation_outcome, Object.values(REVIEW_MUTATION_OUTCOME), "failure.mutation_outcome"),
 		authorityApplicability: enumeration(body.authority_applicability, Object.values(REVIEW_AUTHORITY_APPLICABILITY), "failure.authority_applicability"),
@@ -2079,6 +2128,7 @@ export function decodeReviewFailureV2(value: unknown): ReviewFailureV2 {
 		...(body.cause_category === undefined ? {} : { causeCategory: text(body.cause_category, "failure.cause_category", { minimum: 1, pattern: /^[a-z0-9]+(?:_[a-z0-9]+)*$/ }) }),
 		...(body.cause === undefined ? {} : { cause: text(body.cause, "failure.cause", { minimum: 1, maximum: 4000, pattern: /^[^\r\n]+$/ }) }),
 		...(body.context === undefined ? {} : { context: decodeFailureContext(body.context, "failure.context") }),
+		...(body.continuation === undefined ? {} : { continuation: decodeReviewManagedAssetsContinuationV1(body.continuation, "failure.continuation") }),
 		raw: body,
 	};
 }

package/lib/review-last-event-controller.ts

@@ -4,6 +4,7 @@ import type { ReviewLastEventClosureBinding, ReviewStatusV3 } from "./review-int
 export interface ReviewLastEventCaptureSelector {
 	readonly baseRef?: string;
 	readonly committedOnly?: true;
+	readonly agent?: "pi";
 }
 
 /**

package/lib/review-relay-contract.ts

@@ -14,3 +14,14 @@
 
 export const GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV = "GENTLE_PI_REVIEW_RELAY_CONTRACT";
 export const GENTLE_PI_REVIEW_RELAY_CONTRACT = "gentle-pi.review-relay/v1";
+
+// The host is this extension: every process the session starts (pi's shell
+// tools, Gentle Agents children) runs under it, so the handshake belongs in
+// the session environment too, not only in the extension's own invocations.
+// Without it the first `gentle-ai review status --agent pi` typed in the
+// session shell fails closed (gentle-pi#550). Returns whether anything changed.
+export function declareReviewRelayHandshake(env: NodeJS.ProcessEnv): boolean {
+	if (env[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV] === GENTLE_PI_REVIEW_RELAY_CONTRACT) return false;
+	env[GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV] = GENTLE_PI_REVIEW_RELAY_CONTRACT;
+	return true;
+}

package/lib/review-repository.ts

@@ -55,8 +55,8 @@ export function reviewGitEnvironment(): NodeJS.ProcessEnv {
 	const environment: NodeJS.ProcessEnv = {};
 	for (const [key, value] of Object.entries(process.env)) if (!key.startsWith("GIT_")) environment[key] = value;
 	environment.GIT_CONFIG_NOSYSTEM = "1";
-	environment.GIT_CONFIG_GLOBAL = process.platform === "win32" ? "NUL" : "/dev/null";
-	environment.GIT_CONFIG_SYSTEM = process.platform === "win32" ? "NUL" : "/dev/null";
+	environment.GIT_CONFIG_GLOBAL = "/dev/null";
+	environment.GIT_CONFIG_SYSTEM = "/dev/null";
 	environment.GIT_OPTIONAL_LOCKS = "0";
 	environment.LC_ALL = "C";
 	environment.LANG = "C";