@davideasden/pi-undo 0.2.16 → 0.2.17

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,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.16",
+	"version": "0.2.17",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [

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/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/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;
@@ -1010,7 +1010,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 +1027,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 +1054,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) => {
@@ -1243,12 +1245,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 +1259,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 +1342,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]!;

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 {