@davideasden/pi-undo 0.2.16 → 0.2.18

package/extensions/pi-undo.ts

@@ -9,7 +9,7 @@ import type {
 	SessionTreeEvent as PiSessionTreeEvent,
 } from "@earendil-works/pi-coding-agent";
 
-import type { UndoController } from "../src/controller.ts";
+import type { OperationResult, UndoController } from "../src/controller.ts";
 import { browseDiff } from "../src/diff-ui.ts";
 import { computeCheckpointDiff, type DiffSource, formatDiffSummary, sanitizeDisplayText } from "../src/diff-view.ts";
 import { createPiUndoRuntime } from "../src/pi-runtime.ts";
@@ -19,7 +19,7 @@ export interface PiUndoRuntime {
 	readonly controller: UndoController;
 	readonly reporter: StatusReporter;
 	readonly diffSource?: DiffSource;
-	readonly recovery?: { readonly files?: number; readonly opId?: string };
+	readonly recovery?: { readonly reason?: string; readonly files?: number; readonly opId?: string };
 	setCommandContext?(context: ExtensionCommandContext | undefined): void;
 	isInternalNavigation?(): boolean;
 }
@@ -63,8 +63,12 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 				runtime = next;
 				await next.controller.recover();
 				const history = next.controller.history();
-				if (history.locked) next.reporter.setRecoveryRequired("pending journal", next.recovery);
-				else next.reporter.setReady(history.undoCount, history.redoCount);
+				if (history.locked) {
+					next.reporter.setRecoveryRequired(
+						next.controller.recoveryReason?.() ?? next.recovery?.reason ?? "pending journal",
+						next.recovery,
+					);
+				} else next.reporter.setReady(history.undoCount, history.redoCount);
 				// 后台预热快照缓存，把新会话首次冷 capture 移出第一条 prompt 的关键路径。
 				next.controller.warmUp();
 			} catch (error) {
@@ -117,7 +121,9 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			if (expectedGeneration !== generation || runtime !== active) return;
 			const history = active.controller.history();
 			if (history.locked) {
-				active.reporter.setRecoveryRequired(lockedReason);
+				active.reporter.setRecoveryRequired(
+					active.controller.recoveryReason?.() ?? lockedReason,
+				);
 				restoreDeferredPrompts(runtimeContext);
 			} else {
 				active.reporter.setReady(history.undoCount, history.redoCount);
@@ -137,22 +143,32 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			}
 			const commandToken = Symbol(action);
 			const commandSet = activeCommands;
+			// 只有当前执行命令能安装/清理导航上下文；busy 的第二个命令不得覆盖或清空它。
+			const ownsCommandContext = commandSet.size === 0;
 			commandSet.add(commandToken);
 			activeAction = action;
 			active.reporter.setPhase(action === "undo" ? "undoing" : "redoing");
-			active.setCommandContext?.(context);
+			if (ownsCommandContext) active.setCommandContext?.(context);
 			const commandStarted = performance.now();
-			let result;
+			let result: OperationResult;
 			try {
 				result = action === "undo"
 					? await active.controller.undo()
 					: await active.controller.redo();
 			} finally {
-				active.setCommandContext?.(undefined);
+				if (ownsCommandContext) active.setCommandContext?.(undefined);
 				commandSet.delete(commandToken);
 				if (commandSet === activeCommands && commandSet.size === 0) activeAction = undefined;
 			}
 			if (commandGeneration !== generation || runtime !== active) return;
+			const history = active.controller.history();
+			if (history.locked && result.code === "busy") {
+				result = {
+					...result,
+					code: "recovery_required",
+					message: active.controller.recoveryReason?.() ?? "pending journal",
+				};
+			}
 			active.reporter.result(result, performance.now() - commandStarted);
 			const hasDeferredPrompt = deferredPrompts.length > 0 || replaying !== undefined;
 			if (
@@ -305,7 +321,11 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			if (active === undefined) return;
 			await active.controller.agentSettled();
 			if (runtime !== active || generation !== settledGeneration) return;
-			resumeDeferredPrompts(active, settledGeneration, "session state ambiguous");
+			resumeDeferredPrompts(
+				active,
+				settledGeneration,
+				active.controller.recoveryReason?.() ?? "session state ambiguous",
+			);
 		});
 		pi.on("session_before_tree", async (event: PiSessionBeforeTreeEvent) => {
 			if (runtime === undefined) return { cancel: true };
@@ -326,7 +346,11 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 				navigationTargetLeafId: event.summaryEntry?.parentId ?? event.newLeafId,
 			});
 			if (active !== undefined && runtime === active && generation === treeGeneration) {
-				resumeDeferredPrompts(active, treeGeneration, "session state ambiguous");
+				resumeDeferredPrompts(
+					active,
+					treeGeneration,
+					active.controller.recoveryReason?.() ?? "session state ambiguous",
+				);
 			}
 		});
 		pi.on("session_shutdown", async () => {

package/package.json

@@ -1,7 +1,8 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.16",
+	"version": "0.2.18",
 	"description": "Persistent workspace undo and redo for Pi",
+	"license": "MIT",
 	"type": "module",
 	"keywords": [
 		"pi-package",

package/src/controller.ts

@@ -150,6 +150,8 @@ export interface UndoController {
 	cancelTree?(): Promise<void>;
 	recover(): Promise<void>;
 	history(): HistoryState;
+	/** 当前 recovery lock 的原因；未锁定时返回 undefined。 */
+	recoveryReason?(): string | undefined;
 	/** 后台预热快照缓存：立即返回，失败静默；后续 capture 会先等预热完成。 */
 	warmUp(): void;
 	/** 最近一次输入前快照是否失败（此时本次 run 不可 undo，但输入不受影响）。 */
@@ -175,6 +177,7 @@ export interface ControllerInitialState {
 	readonly redoStack?: readonly ControllerRedoEntry[];
 	readonly historyPaused?: boolean;
 	readonly locked?: boolean;
+	readonly recoveryReason?: string;
 	readonly recoveryCompleted?: boolean;
 }
 
@@ -198,6 +201,7 @@ export class UndoControllerImpl implements UndoController {
 	private staged: StagedRun | undefined;
 	private pendingTree: PendingTree | undefined;
 	private locked = false;
+	private lockedReason: string | undefined;
 	private historyPaused = false;
 	private operationInFlight = false;
 	private operationAction: "undo" | "redo" | undefined;
@@ -219,6 +223,7 @@ export class UndoControllerImpl implements UndoController {
 		this.redoStack.push(...(initialState.redoStack ?? []));
 		this.historyPaused = initialState.historyPaused ?? false;
 		this.locked = initialState.locked ?? false;
+		this.lockedReason = initialState.recoveryReason;
 		this.recoveryCompleted = initialState.recoveryCompleted ?? false;
 	}
 
@@ -226,6 +231,26 @@ export class UndoControllerImpl implements UndoController {
 		return { undoCount: this.undoStack.length, redoCount: this.redoStack.length, locked: this.locked };
 	}
 
+	recoveryReason(): string | undefined {
+		return this.locked ? this.lockedReason ?? "pending journal" : undefined;
+	}
+
+	private lock(reason: string): void {
+		this.locked = true;
+		if (this.lockedReason === undefined) {
+			const normalized = truncateReason(reason);
+			this.lockedReason = normalized.length === 0 ? "recovery_required" : normalized;
+		}
+	}
+
+	private recoveryResult(changedFiles = 0): OperationResult {
+		return {
+			code: "recovery_required",
+			changedFiles,
+			message: this.recoveryReason(),
+		};
+	}
+
 	captureFailed(): boolean {
 		return this.lastCaptureFailed;
 	}
@@ -306,13 +331,13 @@ export class UndoControllerImpl implements UndoController {
 				sourceLogicalLeaf: this.staged.sourceLogicalLeaf,
 			});
 			if (this.staged.startEntryId === null) {
-				this.locked = true;
+				this.lock("start_entry_missing");
 				this.staged = undefined;
 				await this.dependencies.appendControl("pi-undo:barrier", { reason: "start_entry_missing" }).catch(() => {});
 				return;
 			}
 		} catch {
-			this.locked = true;
+			this.lock("start_entry_append_failed");
 			this.staged = undefined;
 			return;
 		}
@@ -361,13 +386,13 @@ export class UndoControllerImpl implements UndoController {
 		if (this.locked || staged === undefined) return;
 		if (staged.startEntryId === undefined || staged.startEntryId === null) {
 			// Pi 没有提供已落盘的 start entry ID，不能把后续 assistant 输出归属到该 checkpoint。
-			this.locked = true;
+			this.lock("start_entry_missing");
 			await this.dependencies.appendControl("pi-undo:barrier", { reason: "start_entry_missing" }).catch(() => {});
 			return;
 		}
 		const userEntryId = this.dependencies.findUserEntryAfter(staged.startEntryId);
 		if (userEntryId === null) {
-			this.locked = true;
+			this.lock("user_entry_missing");
 			await this.dependencies.appendControl("pi-undo:barrier", { reason: "user_entry_missing" }).catch(() => {});
 			return;
 		}
@@ -375,7 +400,8 @@ export class UndoControllerImpl implements UndoController {
 		const measure = <T>(phase: string, operation: () => Promise<T>): Promise<T> =>
 			profiler === undefined ? operation() : profiler.measure(phase, operation);
 		try {
-			const after = await measure("settled.capture", () => this.captureWithWorkspaceLock());
+			// settled 复用 run 开始时的 before；helper 在缺少 captureBaseline 时回退完整 capture。
+			const after = await measure("settled.capture", () => this.captureBaselineWithWorkspaceLock(staged.before));
 			const changedPaths = await measure("settled.changedPaths", () =>
 				this.dependencies.changedPaths(staged.before, after));
 			if (changedPaths.length > 0 && this.dependencies.prepareDurableRestore !== undefined) {
@@ -396,7 +422,7 @@ export class UndoControllerImpl implements UndoController {
 			const checkpointEntryId = await measure("settled.checkpoint", () =>
 				this.dependencies.appendControl("pi-undo:checkpoint", checkpoint));
 			if (checkpointEntryId === null) {
-				this.locked = true;
+				this.lock("checkpoint_entry_missing");
 				await this.dependencies.appendControl("pi-undo:barrier", { reason: "checkpoint_entry_missing" }).catch(() => {});
 				return;
 			}
@@ -410,11 +436,13 @@ export class UndoControllerImpl implements UndoController {
 	}
 
 	async undo(): Promise<OperationResult> {
+		if (this.locked) return this.recoveryResult();
 		if (this.historyPaused) return { code: "history_paused", changedFiles: 0 };
 		return this.runOperation("undo");
 	}
 
 	async redo(): Promise<OperationResult> {
+		if (this.locked) return this.recoveryResult();
 		if (this.historyPaused) return { code: "history_paused", changedFiles: 0 };
 		// 新 run 开始时 redo frontier 已失效；空栈命令不得为了确认 noop 而中断正在运行的 Agent。
 		if (this.redoStack.length === 0) return noop();
@@ -441,7 +469,7 @@ export class UndoControllerImpl implements UndoController {
 			return undefined;
 		} catch {
 			if (lease !== undefined) {
-				await lease.release().catch(() => { this.locked = true; });
+				await lease.release().catch(() => { this.lock("workspace_lock_release_failed"); });
 			}
 			this.operationInFlight = false;
 			return { cancel: true };
@@ -454,7 +482,7 @@ export class UndoControllerImpl implements UndoController {
 		this.pendingTree = undefined;
 		try {
 			if ((event.navigationTargetLeafId ?? event.newLeafId) !== pending.descriptor.toLogicalLeaf) {
-				this.locked = true;
+				this.lock("session_navigation_diverged");
 				await this.dependencies.journal.setPhase(pending.descriptor.opId, "RECOVERY_REQUIRED");
 				return;
 			}
@@ -468,7 +496,7 @@ export class UndoControllerImpl implements UndoController {
 				{ opId: pending.descriptor.opId },
 			);
 			if (applied.code !== "ok") {
-				this.locked = true;
+				this.lock("restore_failed");
 				await this.dependencies.journal.setPhase(pending.descriptor.opId, "RECOVERY_REQUIRED");
 				return;
 			}
@@ -477,7 +505,7 @@ export class UndoControllerImpl implements UndoController {
 				this.createTreeCursor(pending.descriptor, event.newLeafId, pending.undoStack),
 			);
 			if (cursorResult.kind !== "durable") {
-				this.locked = true;
+				this.lock(cursorResult.kind === "recovery_required" ? cursorResult.reason : "cursor_recovery_required");
 				await this.dependencies.journal.setPhase(pending.descriptor.opId, "RECOVERY_REQUIRED");
 				return;
 			}
@@ -486,9 +514,9 @@ export class UndoControllerImpl implements UndoController {
 			this.undoStack.splice(0, this.undoStack.length, ...pending.undoStack);
 			this.redoStack.length = 0;
 		} catch {
-			this.locked = true;
+			this.lock("tree_recovery_failed");
 		} finally {
-			await pending.lease.release().catch(() => { this.locked = true; });
+			await pending.lease.release().catch(() => { this.lock("workspace_lock_release_failed"); });
 			this.operationInFlight = false;
 		}
 	}
@@ -501,9 +529,9 @@ export class UndoControllerImpl implements UndoController {
 			await this.dependencies.journal.setPhase(pending.descriptor.opId, "ABORTING");
 			await this.dependencies.journal.setPhase(pending.descriptor.opId, "ABORTED");
 		} catch {
-			this.locked = true;
+			this.lock("tree_cancel_failed");
 		} finally {
-			await pending.lease.release().catch(() => { this.locked = true; });
+			await pending.lease.release().catch(() => { this.lock("workspace_lock_release_failed"); });
 			this.operationInFlight = false;
 		}
 	}
@@ -518,9 +546,9 @@ export class UndoControllerImpl implements UndoController {
 		const recovery = (async (): Promise<void> => {
 			try {
 				const result = await this.dependencies.recoverPending();
-				if (result.kind === "locked") this.locked = true;
+				if (result.kind === "locked") this.lock(result.reason ?? "recovery_failed");
 			} catch {
-				this.locked = true;
+				this.lock("recovery_failed");
 			} finally {
 				this.recoveryCompleted = true;
 			}
@@ -530,7 +558,8 @@ export class UndoControllerImpl implements UndoController {
 	}
 
 	private async runOperation(action: "undo" | "redo"): Promise<OperationResult> {
-		if (this.locked || this.operationInFlight) return { code: "busy", changedFiles: 0 };
+		if (this.locked) return this.recoveryResult();
+		if (this.operationInFlight) return { code: "busy", changedFiles: 0 };
 		const profile = new OperationProfiler();
 		const done = (result: OperationResult): OperationResult => profile.attach(result);
 		this.operationInFlight = true;
@@ -600,7 +629,7 @@ export class UndoControllerImpl implements UndoController {
 				return done({ code: "restore_failed_safe", changedFiles: 0 });
 			}
 			if (navigation.logicalLeafId !== descriptor.toLogicalLeaf) {
-				this.locked = true;
+				this.lock("session_navigation_diverged");
 				await profile.measure("journal", () =>
 					this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED"));
 				return done({ code: "recovery_required", changedFiles: 0 });
@@ -620,7 +649,7 @@ export class UndoControllerImpl implements UndoController {
 			const cursor = this.createCursor(descriptor, action, checkpoint);
 			const cursorResult = await profile.measure("cursor", () => this.dependencies.appendCursor(cursor));
 			if (cursorResult.kind === "recovery_required") {
-				this.locked = true;
+				this.lock(cursorResult.reason);
 				await profile.measure("journal", () =>
 					this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {}));
 				return done({ code: "recovery_required", changedFiles: applied.verifiedPaths });
@@ -639,13 +668,13 @@ export class UndoControllerImpl implements UndoController {
 			this.lastSafetyManifestId = rollback.manifestId;
 			return done(this.advanceHistory(action, checkpoint, { code: "ok", changedFiles: applied.verifiedPaths }));
 		} catch {
-			this.locked = true;
-			return done({ code: "recovery_required", changedFiles: 0 });
+			this.lock("operation_failed");
+			return done(this.recoveryResult());
 		} finally {
 			const activeLease = lease;
 			if (activeLease !== undefined) {
 				await profile.measure("unlock", () =>
-					activeLease.release().catch(() => { this.locked = true; }));
+					activeLease.release().catch(() => { this.lock("workspace_lock_release_failed"); }));
 			}
 			if (this.operationProfiler === profile) this.operationProfiler = undefined;
 			this.operationAction = undefined;
@@ -703,7 +732,7 @@ export class UndoControllerImpl implements UndoController {
 			return { code: "restore_failed_safe", changedFiles: 0 };
 		}
 		if (navigation.logicalLeafId !== descriptor.toLogicalLeaf) {
-			this.locked = true;
+			this.lock("session_navigation_diverged");
 			await profile.measure("journal", () =>
 				this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED"));
 			return { code: "recovery_required", changedFiles: 0 };
@@ -716,7 +745,7 @@ export class UndoControllerImpl implements UndoController {
 		const cursorResult = await profile.measure("cursor", () =>
 			this.dependencies.appendCursor(this.createCursor(descriptor, action, checkpoint)));
 		if (cursorResult.kind === "recovery_required") {
-			this.locked = true;
+			this.lock(cursorResult.reason);
 			await profile.measure("journal", () =>
 				this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {}));
 			return { code: "recovery_required", changedFiles: 0 };
@@ -741,9 +770,9 @@ export class UndoControllerImpl implements UndoController {
 			await this.dependencies.journal.setPhase(descriptor.opId, "ABORTED");
 			return { code: "restore_failed_safe", changedFiles: 0 };
 		} catch {
-			this.locked = true;
+			this.lock("session_only_recovery_failed");
 			await this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {});
-			return { code: "recovery_required", changedFiles: 0 };
+			return this.recoveryResult();
 		}
 	}
 
@@ -825,9 +854,9 @@ export class UndoControllerImpl implements UndoController {
 		} catch {
 			// 下面统一进入 recovery lock。
 		}
-		this.locked = true;
+		this.lock("compensation_failed");
 		await this.dependencies.journal.setPhase(descriptor.opId, "RECOVERY_REQUIRED").catch(() => {});
-		return { code: "recovery_required", changedFiles: failure.verifiedPaths };
+		return this.recoveryResult(failure.verifiedPaths);
 	}
 
 	private createCheckpoint(

package/src/durable-pack.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { copyFile, link, lstat, open, readFile, rename, rm, type FileHandle } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 
@@ -194,7 +194,12 @@ export async function createDurablePack(
 		await rm(temporary, { force: true }).catch(() => {});
 		throw error;
 	}
-	const packChecksum = checksum(Buffer.concat([MAGIC, lengthBytes, headerBytes, ...payloads]));
+	const digest = createHash("sha256");
+	digest.update(MAGIC);
+	digest.update(lengthBytes);
+	digest.update(headerBytes);
+	for (const payload of payloads) digest.update(payload);
+	const packChecksum = digest.digest("hex");
 	return durablePackFromInput(input.opId, input.planDigest, packPath, packChecksum, entries);
 }
 

package/src/journal.ts

@@ -133,6 +133,27 @@ export class JournalStore {
 		return result;
 	}
 
+	/**
+	 * 判断 foreign PREPARED transaction 是否是严格意义上的 session-only 空操作。
+	 * 这是纯只读检查；任何目录、控制文件或 plan 证据不确定时都返回 false。
+	 */
+	async isInertForeignPrepared(pending: PendingJournal): Promise<boolean> {
+		if (
+			pending.state.phase !== "PREPARED" ||
+			pending.descriptor.scopePaths.length !== 0 ||
+			!isInertRestorePlan(pending.plan, pending.descriptor)
+		) return false;
+		try {
+			const current = await this.load(pending.descriptor.opId);
+			if (!samePendingJournal(current, pending) || !isInertRestorePlan(current.plan, current.descriptor)) return false;
+			if (!await hasOnlyControlFiles(this.operationDirectory(pending.descriptor.opId))) return false;
+			const verified = await this.load(pending.descriptor.opId);
+			return samePendingJournal(verified, current) && await hasOnlyControlFiles(this.operationDirectory(pending.descriptor.opId));
+		} catch {
+			return false;
+		}
+	}
+
 	async assertLogicalCommitReady(opId: string, allowPendingMutations = false): Promise<void> {
 		if (!allowPendingMutations) await this.mutationJournal(opId).assertCleaned();
 		const pending = await this.load(opId);
@@ -319,6 +340,84 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isInertRestorePlan(value: unknown, descriptor: OperationDescriptor): boolean {
+	if (!isRecord(value)) return false;
+	const expectedKeys = [
+		"boundaryRoots",
+		"currentManifestId",
+		"deletePaths",
+		"planDigest",
+		"scopePaths",
+		"targetManifestId",
+		"writePaths",
+	].sort();
+	if (canonicalJson(Object.keys(value).sort()) !== canonicalJson(expectedKeys)) return false;
+	if (
+		value.currentManifestId !== descriptor.rollbackManifestId ||
+		value.targetManifestId !== descriptor.targetManifestId ||
+		!isEmptyArray(value.boundaryRoots) ||
+		!isEmptyArray(value.deletePaths) ||
+		!isEmptyArray(value.writePaths) ||
+		!isEmptyArray(value.scopePaths) ||
+		typeof value.planDigest !== "string" ||
+		!/^[0-9a-f]{64}$/.test(value.planDigest)
+	) return false;
+	try {
+		return checksum(canonicalJson({
+			currentManifestId: value.currentManifestId,
+			targetManifestId: value.targetManifestId,
+			boundaryRoots: value.boundaryRoots,
+			deletePaths: value.deletePaths,
+			writePaths: value.writePaths,
+			scopePaths: value.scopePaths,
+		})) === value.planDigest;
+	} catch {
+		return false;
+	}
+}
+
+async function hasOnlyControlFiles(directory: string): Promise<boolean> {
+	const expected = ["descriptor.json", "restore-plan.json", "state.json"];
+	try {
+		const metadata = await lstat(directory);
+		if (!metadata.isDirectory() || metadata.isSymbolicLink()) return false;
+	} catch {
+		return false;
+	}
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	if (entries.length !== expected.length || !expected.every((name) => entries.some((entry) => entry.name === name))) {
+		return false;
+	}
+	try {
+		for (const name of expected) {
+			const entry = entries.find((candidate) => candidate.name === name);
+			if (entry === undefined || !entry.isFile() || entry.isSymbolicLink()) return false;
+			const stats = await lstat(join(directory, name));
+			if (!stats.isFile() || stats.isSymbolicLink()) return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function samePendingJournal(left: PendingJournal, right: PendingJournal): boolean {
+	try {
+		return canonicalJson(left) === canonicalJson(right);
+	} catch {
+		return false;
+	}
+}
+
+function isEmptyArray(value: unknown): value is readonly unknown[] {
+	return Array.isArray(value) && value.length === 0;
+}
+
 function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }

package/src/pi-runtime.ts

@@ -64,6 +64,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		workspaceIdentity: initialTopology.workspaceIdentity,
 		getLogicalLeafId: () => sessionStateFor(manager).getLogicalLeafId(),
 		loadPending: () => journal.loadPending(),
+		assessForeignTransaction: (pending) => journal.isInertForeignPrepared(pending),
 		inspectCursor: (pending) => inspectCursorMarkers(pending.descriptor.sessionIdentity.path, pending.descriptor),
 		finalizeCursor: (pending, inspection) => finalizeCursorMarker(
 			pending.descriptor.sessionIdentity.path,
@@ -259,6 +260,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 	const controller = new UndoControllerImpl(dependencies, {
 		...rebuildControllerState(manager, sessionIdentity),
 		locked: startupRecovery.kind === "locked",
+		recoveryReason: startupRecovery.kind === "locked" ? startupRecovery.reason : undefined,
 		recoveryCompleted: true,
 	});
 	return {
@@ -266,7 +268,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		reporter: new StatusReporter(context),
 		diffSource: store,
 		recovery: startupRecovery.kind === "locked"
-			? { files: startupRecovery.files, opId: startupRecovery.opId }
+			? { reason: startupRecovery.reason, files: startupRecovery.files, opId: startupRecovery.opId }
 			: undefined,
 		setCommandContext(next: ExtensionCommandContext | undefined): void {
 			commandContext = next;

package/src/recovery.ts

@@ -9,6 +9,8 @@ export interface JournalRecoveryDependencies {
 	readonly workspaceIdentity: string;
 	readonly getLogicalLeafId: () => string | null;
 	readonly loadPending: () => Promise<readonly PendingJournal[]>;
+	/** 仅允许严格证明无工作区 mutation 的 foreign PREPARED 空事务被忽略。 */
+	readonly assessForeignTransaction?: (journal: PendingJournal) => Promise<boolean>;
 	readonly inspectCursor: (journal: PendingJournal) => Promise<CursorMarkerInspection>;
 	readonly finalizeCursor: (journal: PendingJournal, inspection: Extract<CursorMarkerInspection, { kind: "match" }>) => Promise<void>;
 	readonly recoverMutations: (
@@ -65,6 +67,7 @@ export class JournalRecovery {
 		for (const journal of pending) {
 			const identityError = this.identityError(journal);
 			if (identityError !== null) {
+				if (identityError === "session_identity_mismatch" && await this.canIgnoreForeignTransaction(journal)) continue;
 				return { kind: "locked", reason: identityError, operations: recovered };
 			}
 			let inspection: CursorMarkerInspection;
@@ -131,6 +134,17 @@ export class JournalRecovery {
 		return { kind: "recovered", operations: recovered };
 	}
 
+	private async canIgnoreForeignTransaction(journal: PendingJournal): Promise<boolean> {
+		const assess = this.dependencies.assessForeignTransaction;
+		if (assess === undefined) return false;
+		try {
+			return await assess(journal);
+		} catch {
+			// 评估失败等同于证据不足，保留 foreign identity lock。
+			return false;
+		}
+	}
+
 	private identityError(journal: PendingJournal): string | null {
 		if (journal.descriptor.workspaceIdentity !== this.dependencies.workspaceIdentity) {
 			return "workspace_identity_mismatch";

package/src/restore-engine.ts

@@ -38,6 +38,7 @@ const PREPARED_PLAN_CACHE_LIMIT = 16;
 const RESTORE_FILE_BATCH_MAX_ENTRIES = 1_024;
 const RESTORE_FILE_BATCH_MAX_BYTES = 64 * 1024 * 1024;
 const RESTORE_FILE_PREPARE_CONCURRENCY = 32;
+const RESTORE_FILE_VERIFY_CONCURRENCY = 32;
 
 export interface RestorePlan {
 	currentManifestId: ManifestId;
@@ -519,7 +520,13 @@ export class RestoreEngine {
 			return { code: "recovery_required", verifiedPaths: 0, totalPaths: currentPaths.size };
 		}
 		try {
-			await this.assertCompleteVisibleSubset(topologyBefore, [current, target], options.mutationJournal);
+			await this.assertCompleteVisibleSubset(
+				topologyBefore,
+				[current, target],
+				options.mutationJournal,
+				[],
+				this.completeCoverageOwnedPaths(plan.scopePaths, [currentPaths, targetPaths]),
+			);
 		} catch {
 			return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
 		}
@@ -588,6 +595,11 @@ export class RestoreEngine {
 			);
 			return result;
 		}
+		try {
+			await this.prefetchCompleteRestoreBlobs(plan, current, target, currentPaths, targetPaths);
+		} catch {
+			// 预取是性能优化；失败时继续走原有逐文件校验和可恢复 mutation 路径。
+		}
 		const preflight = await this.verifyKnownState(current, target, currentPaths, targetPaths, plan.scopePaths);
 		if (!preflight.ok) {
 			return {
@@ -625,7 +637,13 @@ export class RestoreEngine {
 
 			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
 			assertUnchangedTopology(topologyBefore, topologyAfter);
-			await this.assertCompleteVisibleSubset(topologyAfter, [target], options.mutationJournal);
+			await this.assertCompleteVisibleSubset(
+				topologyAfter,
+				[target],
+				options.mutationJournal,
+				[],
+				this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
+			);
 			const verification = await this.verifyTarget(
 				target,
 				currentPaths,
@@ -702,6 +720,7 @@ export class RestoreEngine {
 						? []
 						: [artifacts.source, ...(artifacts.target === null ? [] : [artifacts.target])];
 				}),
+				this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
 			);
 			const totalPaths = plan.deletePaths.length + plan.writePaths.length;
 			if ((await options.mutationJournal.load()).length !== 0) {
@@ -887,6 +906,41 @@ export class RestoreEngine {
 		return result;
 	}
 
+	private completeCoverageOwnedPaths(
+		scopePaths: readonly string[] | undefined,
+		ownedPaths: readonly ReadonlyMap<string, OwnedPath>[],
+	): readonly ReadonlyMap<string, OwnedPath>[] | undefined {
+		return scopePaths === undefined ? ownedPaths : undefined;
+	}
+
+	private async prefetchCompleteRestoreBlobs(
+		plan: RestorePlan,
+		current: SnapshotManifest,
+		target: SnapshotManifest,
+		currentPaths: ReadonlyMap<string, OwnedPath>,
+		targetPaths: ReadonlyMap<string, OwnedPath>,
+	): Promise<void> {
+		if (plan.scopePaths !== undefined || !SnapshotStore.supportsValidatedBlobBatch(this.store)) return;
+		const requestsFor = (paths: ReadonlyMap<string, OwnedPath>, extraPaths: readonly string[] = []) => {
+			const requests = [];
+			const requested = new Set([...plan.writePaths, ...extraPaths]);
+			for (const path of requested) {
+				const owned = paths.get(path);
+				if (owned === undefined || owned.entry.kind !== "file" || owned.entry.blobId === null) continue;
+				requests.push({
+					rootPath: owned.root.relativeRoot,
+					blobId: owned.entry.blobId,
+					relativePath: owned.entry.relativePath,
+				});
+			}
+			return requests;
+		};
+		await Promise.all([
+			this.store.prefetchBlobs(current.manifestId, requestsFor(currentPaths, plan.deletePaths)),
+			this.store.prefetchBlobs(target.manifestId, requestsFor(targetPaths)),
+		]);
+	}
+
 	private assertCurrentTopology(
 		current: SnapshotManifest,
 		target: SnapshotManifest,
@@ -926,12 +980,13 @@ export class RestoreEngine {
 		const paths = [...new Set([...currentPaths.keys(), ...targetPaths.keys()])]
 			.filter((path) => scope === undefined || scope.has(path))
 			.sort(comparePaths);
-		let verifiedPaths = 0;
-		for (const path of paths) {
-			if (await this.pathIsShadowedByTarget(target.manifestId, path, targetPaths)) {
-				verifiedPaths += 1;
-				continue;
-			}
+		const results: Array<boolean | undefined> = new Array(paths.length);
+		let nextIndex = 0;
+		let stop = false;
+		let failure: unknown;
+		let failureIndex: number | undefined;
+		const verifyPath = async (path: string): Promise<boolean> => {
+			if (await this.pathIsShadowedByTarget(target.manifestId, path, targetPaths)) return true;
 			const currentPath = currentPaths.get(path);
 			const targetPath = targetPaths.get(path);
 			const matchesCurrent = currentPath !== undefined &&
@@ -941,7 +996,37 @@ export class RestoreEngine {
 			const matchesAbsentSide = !matchesCurrent && !matchesTarget &&
 				(currentPath === undefined || targetPath === undefined) &&
 				await this.pathIsAbsent(path);
-			if (!matchesCurrent && !matchesTarget && !matchesAbsentSide) {
+			return matchesCurrent || matchesTarget || matchesAbsentSide;
+		};
+		const worker = async (): Promise<void> => {
+			while (!stop && nextIndex < paths.length) {
+				const index = nextIndex;
+				nextIndex += 1;
+				try {
+					const ok = await verifyPath(paths[index]!);
+					results[index] = ok;
+					if (!ok) stop = true;
+				} catch (error) {
+					if (failureIndex === undefined || index < failureIndex) {
+						failure = error;
+						failureIndex = index;
+					}
+					stop = true;
+				}
+			}
+		};
+		if (paths.length > 0) {
+			await Promise.all(Array.from(
+				{ length: Math.min(RESTORE_FILE_VERIFY_CONCURRENCY, paths.length) },
+				() => worker(),
+			));
+		}
+		let verifiedPaths = 0;
+		for (let index = 0; index < results.length; index += 1) {
+			const ok = results[index];
+			if (ok === false) return { ok: false, verifiedPaths, totalPaths: paths.length };
+			if (ok === undefined) {
+				if (failureIndex === index && failure !== undefined) throw failure;
 				return { ok: false, verifiedPaths, totalPaths: paths.length };
 			}
 			verifiedPaths += 1;
@@ -1168,7 +1253,13 @@ export class RestoreEngine {
 			await this.writePlannedPaths(current.manifestId, currentPaths, rollbackPlan.writePaths, context);
 			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
 			assertUnchangedTopology(topologyBefore, topologyAfter);
-			await this.assertCompleteVisibleSubset(topologyAfter, [current], options.mutationJournal);
+			await this.assertCompleteVisibleSubset(
+				topologyAfter,
+				[current],
+				options.mutationJournal,
+				[],
+				this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+			);
 			const verification = await this.verifyTarget(
 				current,
 				targetPaths,
@@ -1205,7 +1296,13 @@ export class RestoreEngine {
 				try {
 					const topologyAfter = await this.discovery.discover(this.workspaceRoot);
 					assertUnchangedTopology(topologyBefore, topologyAfter);
-					await this.assertCompleteVisibleSubset(topologyAfter, [current], options.mutationJournal);
+					await this.assertCompleteVisibleSubset(
+						topologyAfter,
+						[current],
+						options.mutationJournal,
+						[],
+						this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+					);
 					const verification = await this.verifyTarget(
 						current,
 						targetPaths,
@@ -1397,16 +1494,17 @@ export class RestoreEngine {
 		allowedManifests: readonly SnapshotManifest[],
 		mutationJournal?: MutationJournal,
 		extraExclusions: readonly string[] = [],
+		ownedPaths?: readonly (ReadonlyMap<string, OwnedPath> | undefined)[],
 	): Promise<void> {
 		if (allowedManifests.some((manifest) => manifest.coverage !== "complete")) {
 			return;
 		}
 		const allowedPaths = new Set<string>();
-		for (const manifest of allowedManifests) {
+		for (const [index, manifest] of allowedManifests.entries()) {
 			for (const path of ignoredWorkspacePaths(manifest)) {
 				allowedPaths.add(path);
 			}
-			const paths = await this.readOwnedPaths(manifest);
+			const paths = ownedPaths?.[index] ?? await this.readOwnedPaths(manifest);
 			for (const [path, owned] of paths) {
 				if (owned.entry.kind !== "directory") {
 					allowedPaths.add(path);
@@ -1435,23 +1533,18 @@ export class RestoreEngine {
 		deletePaths: readonly string[],
 		scopePaths?: readonly string[],
 	): Promise<{ verifiedPaths: number; totalPaths: number; pathFingerprints: string[] }> {
-		const pathFingerprints: string[] = [];
 		const scope = scopePaths === undefined ? undefined : new Set(scopePaths);
-		for (const [path, owned] of targetPaths) {
-			if (scope !== undefined && !scope.has(path)) continue;
-			pathFingerprints.push(await this.verifyEntry(target.manifestId, owned));
-		}
-		let verifiedPaths = pathFingerprints.length;
-		let totalPaths = pathFingerprints.length;
-		for (const path of deletePaths) {
-			if (
-				targetPaths.has(path) ||
-				currentPaths.get(path)?.entry.kind === "directory" ||
-				hasNonDirectoryAncestor(path, targetPaths)
-			) {
-				continue;
-			}
-			totalPaths += 1;
+		const scopedTargets = [...targetPaths].filter(([path]) => scope === undefined || scope.has(path));
+		const pathFingerprints = await mapConcurrentOrdered(
+			scopedTargets,
+			RESTORE_FILE_VERIFY_CONCURRENCY,
+			([, owned]) => this.verifyEntry(target.manifestId, owned),
+		);
+		const remainingDeletes = deletePaths.filter((path) =>
+			!targetPaths.has(path) &&
+			currentPaths.get(path)?.entry.kind !== "directory" &&
+			!hasNonDirectoryAncestor(path, targetPaths));
+		await mapConcurrentOrdered(remainingDeletes, RESTORE_FILE_VERIFY_CONCURRENCY, async (path) => {
 			try {
 				await lstat(this.absolutePath(path));
 				throw new Error(`目标应删除的路径仍然存在：${path}`);
@@ -1460,11 +1553,10 @@ export class RestoreEngine {
 					throw error;
 				}
 			}
-			verifiedPaths += 1;
-		}
+		});
 		return {
-			verifiedPaths,
-			totalPaths,
+			verifiedPaths: pathFingerprints.length + remainingDeletes.length,
+			totalPaths: pathFingerprints.length + remainingDeletes.length,
 			pathFingerprints,
 		};
 	}

package/src/snapshot-store.ts

@@ -40,7 +40,7 @@ const HASH_BATCH_MAX_ARGUMENT_BYTES = process.platform === "win32" ? 24 * 1024 :
 const HASH_BATCH_CONCURRENCY = 4;
 const ROOT_CAPTURE_CONCURRENCY = 4;
 const FILE_SYSTEM_INSPECTION_CONCURRENCY = 32;
-const IGNORED_METADATA_BATCH_SIZE = 1_024;
+const METADATA_BATCH_SIZE = 1_024;
 const INDEX_BATCH_MAX_ENTRIES = 4_096;
 const INDEX_BATCH_MAX_BYTES = 8 * 1024 * 1024;
 const BLOB_CACHE_MAX_BYTES = 128 * 1024 * 1024;
@@ -210,6 +210,8 @@ export class SnapshotStore {
 	private readonly blobCache = new Map<string, CachedBlob>();
 	private readonly visibleLeafCache = new Map<string, Map<string, CachedVisibleLeaf>>();
 	private readonly leafCacheDirectoriesLoaded = new Set<string>();
+	private readonly configuredPrivateRepositories = new Set<string>();
+	private readonly leafCacheDirtyDirectories = new Set<string>();
 	private blobCacheBytes = 0;
 
 	constructor(options: SnapshotStoreOptions = {}) {
@@ -741,6 +743,61 @@ export class SnapshotStore {
 		return (await this.readBlobOperation(id, [{ rootPath, blobId, relativePath }], false))[0]!;
 	}
 
+	/** 按 root 批量预取普通文件 blob；membership 与 manifest 校验仍走只读路径。 */
+	async prefetchBlobs(id: ManifestId, requests: readonly SnapshotBlobRequest[]): Promise<void> {
+		if (requests.length === 0) return;
+		for (const request of requests) {
+			relativeSafePath("/", request.rootPath);
+			if (!isObjectId(request.blobId)) {
+				throw new SnapshotStoreError("object_missing", "blob ID 无效");
+			}
+			if (request.relativePath === undefined) {
+				throw new SnapshotStoreError("object_missing", "blob 预取必须提供 root-relative path");
+			}
+		}
+		const manifestPath = await this.findManifestPath(id);
+		const manifest = await this.loadManifest(id);
+		const roots = new Map(manifest.roots.map((root) => [root.relativeRoot, root]));
+		const storeDirectory = dirname(dirname(manifestPath));
+		const byRoot = new Map<string, SnapshotBlobRequest[]>();
+		for (const request of requests) {
+			const grouped = byRoot.get(request.rootPath) ?? [];
+			grouped.push(request);
+			byRoot.set(request.rootPath, grouped);
+		}
+		try {
+			const grouped = new Map<string, Map<string, CapturedTreeEntry>>();
+			for (const [rootPath, rootRequests] of byRoot) {
+				const root = roots.get(rootPath);
+				if (root === undefined) {
+					throw new SnapshotStoreError("root_not_found", "manifest 中不存在指定 root");
+				}
+				if (root.state !== "active" || root.treeId === null) {
+					throw new SnapshotStoreError("object_missing", "指定 root 没有可读取的 tree");
+				}
+				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
+				const entries = await this.readTreeEntries(gitDirectory, root.treeId);
+				const byPath = new Map(entries.map((entry) => [entry.relativePath, entry]));
+				const unique = grouped.get(gitDirectory) ?? new Map<string, CapturedTreeEntry>();
+				for (const request of rootRequests) {
+					const safeRelativePath = relativeSafePath("/", request.relativePath!);
+					const entry = byPath.get(safeRelativePath);
+					if (entry === undefined || entry.objectId !== request.blobId) {
+						throw new SnapshotStoreError("object_missing", "blob 不属于指定 root tree path");
+					}
+					unique.set(entry.objectId, entry);
+				}
+				grouped.set(gitDirectory, unique);
+			}
+			for (const [gitDirectory, unique] of grouped) {
+				await this.preloadBlobBytes(gitDirectory, [...unique.values()]);
+			}
+		} catch (error) {
+			if (error instanceof SnapshotStoreError) throw error;
+			throw new SnapshotStoreError("object_missing", "blob 无法预取", { cause: error });
+		}
+	}
+
 	private readBlobsValidated(
 		id: ManifestId,
 		requests: readonly SnapshotBlobRequest[],
@@ -1010,7 +1067,7 @@ export class SnapshotStore {
 		}
 		// ignored build/vendor trees 常含数万叶子；复用同一批量 metadata 协议，避免逐路径重复
 		// 遍历父目录。Native 与 fallback 都在叶子扫描前后复核共享父目录。
-		const nativeEntries = await this.inspectIgnoredMetadataBatches(cwd, candidates, requestDirectory);
+		const nativeEntries = await this.inspectNativeMetadataBatches(cwd, candidates, requestDirectory);
 		const kinds = nativeEntries === undefined
 			? await this.collectIgnoredPresentKindsFallback(cwd, candidates)
 			: nativeEntries.map((entry) => entry.kind);
@@ -1027,18 +1084,20 @@ export class SnapshotStore {
 		return result.sort(comparePaths);
 	}
 
-	private async inspectIgnoredMetadataBatches(
+	private async inspectNativeMetadataBatches(
 		cwd: string,
 		paths: readonly string[],
 		requestDirectory: string,
 	): Promise<readonly NativeMetadataEntry[] | undefined> {
+		// 空路径不得触发 native inspect；首批 unsupported 才整体回退，中途变化必须 fail closed。
+		if (paths.length === 0) return [];
 		const result: NativeMetadataEntry[] = [];
-		for (let offset = 0; offset < paths.length; offset += IGNORED_METADATA_BATCH_SIZE) {
-			const batch = paths.slice(offset, offset + IGNORED_METADATA_BATCH_SIZE);
+		for (let offset = 0; offset < paths.length; offset += METADATA_BATCH_SIZE) {
+			const batch = paths.slice(offset, offset + METADATA_BATCH_SIZE);
 			const inspected = await this.nativeMetadata.inspect(cwd, batch, requestDirectory);
 			if (inspected === undefined) {
 				if (result.length > 0) {
-					throw new SnapshotStoreError("capture_failed", "native ignored metadata 能力在批次间变化");
+					throw new SnapshotStoreError("capture_failed", "native metadata 能力在批次间变化");
 				}
 				return undefined;
 			}
@@ -1052,8 +1111,8 @@ export class SnapshotStore {
 		paths: readonly string[],
 	): Promise<readonly NativeMetadataEntry["kind"][]> {
 		const result: NativeMetadataEntry["kind"][] = [];
-		for (let offset = 0; offset < paths.length; offset += IGNORED_METADATA_BATCH_SIZE) {
-			const batch = paths.slice(offset, offset + IGNORED_METADATA_BATCH_SIZE);
+		for (let offset = 0; offset < paths.length; offset += METADATA_BATCH_SIZE) {
+			const batch = paths.slice(offset, offset + METADATA_BATCH_SIZE);
 			await assertNoSymlinkParents(cwd, batch);
 			const kinds = await mapConcurrentOrdered(batch, FILE_SYSTEM_INSPECTION_CONCURRENCY, async (relativePath) => {
 				const metadata = await lstat(join(cwd, ...relativePath.split("/"))).catch((error) => {
@@ -1153,9 +1212,10 @@ export class SnapshotStore {
 
 	private rememberVisibleLeaves(update: VisibleLeafCacheUpdate): void {
 		const { gitDirectory, staged, inclusions } = update;
+		const previous = this.visibleLeafCache.get(gitDirectory);
 		const cache = inclusions !== null && inclusions.length === 0
 			? new Map<string, CachedVisibleLeaf>()
-			: new Map(this.visibleLeafCache.get(gitDirectory));
+			: new Map(previous);
 		if (inclusions !== null && inclusions.length > 0) {
 			for (const relativePath of cache.keys()) {
 				if (inclusions.some((inclusion) => isPathAtOrBelow(inclusion, relativePath))) {
@@ -1172,6 +1232,9 @@ export class SnapshotStore {
 			}
 			cache.set(leaf.relativePath, { ...leaf, objectId, verifiedAtNs: staged.verifiedAtNs });
 		}
+		if (!samePersistedLeafCache(previous, cache)) {
+			this.leafCacheDirtyDirectories.add(storeDirectoryForGitDirectory(gitDirectory));
+		}
 		this.visibleLeafCache.set(gitDirectory, cache);
 	}
 
@@ -1208,6 +1271,7 @@ export class SnapshotStore {
 
 	/** 把当前 storeDirectory 范围内的叶子缓存原子写入磁盘（best-effort）。 */
 	private async persistLeafCache(storeDirectory: string): Promise<void> {
+		if (!this.leafCacheDirtyDirectories.has(storeDirectory)) return;
 		const prefix = `${storeDirectory}${sep}`;
 		const entries: Record<string, Record<string, PersistedLeafCacheEntry>> = {};
 		for (const [gitDirectory, cache] of this.visibleLeafCache) {
@@ -1233,6 +1297,7 @@ export class SnapshotStore {
 				Buffer.from(JSON.stringify({ schemaVersion: 1, entries }), "utf8"),
 				0o600,
 			);
+			this.leafCacheDirtyDirectories.delete(storeDirectory);
 		} catch {
 			// 缓存写入是 best-effort：失败只影响下次性能，不影响正确性。
 		}
@@ -1243,12 +1308,12 @@ export class SnapshotStore {
 		leaves: readonly VisibleLeaf[],
 		requestDirectory?: string,
 	): Promise<void> {
+		if (leaves.length === 0) return;
+		const paths = leaves.map((leaf) => leaf.relativePath);
 		if (requestDirectory !== undefined) {
-			const inspected = await this.nativeMetadata.inspect(
-				cwd,
-				leaves.map((leaf) => leaf.relativePath),
-				requestDirectory,
-			);
+			// 分批 inspect 只核验当前批次祖先；全部可见路径必须在批次前后各包一层父目录检查。
+			await assertNoSymlinkParents(cwd, paths);
+			const inspected = await this.inspectNativeMetadataBatches(cwd, paths, requestDirectory);
 			if (inspected !== undefined) {
 				for (let index = 0; index < leaves.length; index += 1) {
 					const leaf = leaves[index]!;
@@ -1257,10 +1322,15 @@ export class SnapshotStore {
 						throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化：${leaf.relativePath}`);
 					}
 				}
+				await assertNoSymlinkParents(cwd, paths);
 				return;
 			}
+			await mapConcurrentOrdered(leaves, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
+				this.assertVisibleLeafUnchanged(cwd, leaf));
+			await assertNoSymlinkParents(cwd, paths);
+			return;
 		}
-		await assertNoSymlinkParents(cwd, leaves.map((leaf) => leaf.relativePath));
+		await assertNoSymlinkParents(cwd, paths);
 		await mapConcurrentOrdered(leaves, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
 			this.assertVisibleLeafUnchanged(cwd, leaf));
 	}
@@ -1335,10 +1405,14 @@ export class SnapshotStore {
 			exclusions,
 			exactExclusions,
 		);
-		const nativeEntries = await this.nativeMetadata.inspect(cwd, paths, requestDirectory);
+		if (paths.length === 0) return [];
+		// 分批 inspect 只核验当前批次祖先；全部可见路径必须在批次前后各包一层父目录检查。
+		await assertNoSymlinkParents(cwd, paths);
+		const nativeEntries = await this.inspectNativeMetadataBatches(cwd, paths, requestDirectory);
 		const metadataEntries = nativeEntries === undefined
 			? await this.collectVisibleLeafMetadataFallback(cwd, paths)
 			: nativeEntries.map((entry) => nativeVisibleLeafMetadata(entry));
+		await assertNoSymlinkParents(cwd, paths);
 		const leaves: VisibleLeaf[] = [];
 		for (let index = 0; index < paths.length; index += 1) {
 			const relativePath = paths[index]!;
@@ -1417,9 +1491,11 @@ export class SnapshotStore {
 	}
 
 	private async configurePrivateRepository(gitDirectory: string): Promise<void> {
+		if (this.configuredPrivateRepositories.has(gitDirectory)) return;
 		const environment = cleanGitEnvironment();
 		await this.runGit(["--git-dir", gitDirectory, "config", "gc.auto", "0"], { env: environment });
 		await this.runGit(["--git-dir", gitDirectory, "config", "maintenance.auto", "false"], { env: environment });
+		this.configuredPrivateRepositories.add(gitDirectory);
 	}
 
 	private async assertNoAlternates(gitDirectory: string): Promise<void> {
@@ -1971,6 +2047,35 @@ function blobCacheKey(gitDirectory: string, objectId: string): string {
 	return `${gitDirectory}\0${objectId}`;
 }
 
+function storeDirectoryForGitDirectory(gitDirectory: string): string {
+	return dirname(dirname(dirname(gitDirectory)));
+}
+
+function samePersistedLeafCache(
+	left: ReadonlyMap<string, CachedVisibleLeaf> | undefined,
+	right: ReadonlyMap<string, CachedVisibleLeaf>,
+): boolean {
+	if (left === undefined) return right.size === 0;
+	if (left.size !== right.size) return false;
+	for (const [path, entry] of right) {
+		const existing = left.get(path);
+		const existingTrusted = existing !== undefined &&
+			existing.verifiedAtNs > existing.changedAtNs + RACY_CLEAN_WINDOW_NS;
+		const entryTrusted = entry.verifiedAtNs > entry.changedAtNs + RACY_CLEAN_WINDOW_NS;
+		if (
+			existing === undefined ||
+			existing.kind !== entry.kind ||
+			existing.mode !== entry.mode ||
+			existing.fingerprint !== entry.fingerprint ||
+			existing.cacheable !== entry.cacheable ||
+			existing.objectId !== entry.objectId ||
+			existing.changedAtNs !== entry.changedAtNs ||
+			existingTrusted !== entryTrusted
+		) return false;
+	}
+	return true;
+}
+
 function blobReadBatches(entries: readonly CapturedTreeEntry[]): CapturedTreeEntry[][] {
 	const result: CapturedTreeEntry[][] = [];
 	let batch: CapturedTreeEntry[] = [];

package/src/status-reporter.ts

@@ -32,11 +32,12 @@ export class StatusReporter {
 		reason: string,
 		details?: { readonly files?: number; readonly opId?: string },
 	): void {
+		const safeReason = sanitize(reason) || "recovery_required";
 		if (details?.files !== undefined && details.opId !== undefined) {
-			this.setStatus(`recovery_required files:${details.files} op:${sanitize(details.opId)}`);
+			this.setStatus(`recovery_required reason:${safeReason} files:${details.files} op:${sanitize(details.opId)}`);
 			return;
 		}
-		this.setStatus(`recovery required: ${sanitize(reason)}`);
+		this.setStatus(`recovery required: ${safeReason}`);
 	}
 
 	clear(): void {