@davideasden/pi-undo 0.2.15 → 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 (
@@ -218,9 +234,10 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		pi.on("input", async (event: InputEvent, context: ExtensionContext) => {
 			const active = runtime;
 			if (active === undefined) return { action: "continue" as const };
-			const result = await active.controller.prepareInput(event.text, {
-				streaming: event.streamingBehavior !== undefined,
-			});
+			const inputContext = { streaming: event.streamingBehavior !== undefined };
+			const result = active.controller.beginInput !== undefined
+				? active.controller.beginInput(event.text, inputContext)
+				: await active.controller.prepareInput(event.text, inputContext);
 			const replay = replaying;
 			if (result.action === "defer") {
 				if (replay !== undefined && event.source === "extension" && samePrompt(event.text, event.images, replay)) {
@@ -254,7 +271,10 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 					}
 				}
 			}
-			if (result.action === "continue" && active.controller.captureFailed() && !captureFailureNotified) {
+			if (
+				active.controller.beginInput === undefined &&
+				result.action === "continue" && active.controller.captureFailed() && !captureFailureNotified
+			) {
 				captureFailureNotified = true;
 				const reason = active.controller.captureFailureReason();
 				context.ui.notify(
@@ -264,6 +284,22 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			}
 			return result;
 		});
+		pi.on("message_end", async (event, context: ExtensionContext) => {
+			if (event.message.role !== "user") return;
+			const active = runtime;
+			const messageGeneration = generation;
+			if (active === undefined || active.controller.commitInput === undefined) return;
+			await active.controller.commitInput();
+			if (runtime !== active || generation !== messageGeneration) return;
+			if (active.controller.captureFailed() && !captureFailureNotified) {
+				captureFailureNotified = true;
+				const reason = active.controller.captureFailureReason();
+				context.ui.notify(
+					`pi-undo: pre-input snapshot failed${reason === undefined || reason.length === 0 ? "" : ` (${reason})`}; this run will not be undoable`,
+					"warning",
+				);
+			}
+		});
 		pi.on("before_agent_start", async () => {
 			const active = runtime;
 			const startGeneration = generation;
@@ -285,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 };
@@ -306,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.15",
+	"version": "0.2.17",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [

package/src/controller.ts

@@ -37,6 +37,7 @@ export interface ControllerDependencies {
 	readonly appendControl: (customType: string, data?: unknown) => Promise<string | null>;
 	readonly appendCursor: (cursor: CursorState) => Promise<CursorAppendResult>;
 	readonly capture: (scopePaths?: readonly string[]) => Promise<SnapshotManifest>;
+	readonly captureBaseline?: (baseline: SnapshotManifest) => Promise<SnapshotManifest>;
 	readonly captureSafety?: (
 		referenceManifestId: ManifestId,
 		targetManifestId: ManifestId,
@@ -136,6 +137,10 @@ export interface UndoController {
 	/** 只读的 undo 栈视图（栈底在前）；仅供 /diff 等展示使用。 */
 	listCheckpoints(): readonly CheckpointRecord[];
 	prepareInput(text: string, context: InputContext): Promise<InputEventResult>;
+	/** 在 input hook 中启动快照，但不等待，供 message_end 前的快速路径使用。 */
+	beginInput?(text: string, context: InputContext): InputEventResult;
+	/** 在用户 message_end 后等待快照并写入 start entry。 */
+	commitInput?(): Promise<void>;
 	beforeAgentStart(): Promise<void>;
 	agentSettled(): Promise<void>;
 	undo(): Promise<OperationResult>;
@@ -145,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，但输入不受影响）。 */
@@ -170,6 +177,8 @@ export interface ControllerInitialState {
 	readonly redoStack?: readonly ControllerRedoEntry[];
 	readonly historyPaused?: boolean;
 	readonly locked?: boolean;
+	readonly recoveryReason?: string;
+	readonly recoveryCompleted?: boolean;
 }
 
 interface PendingTree {
@@ -192,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;
@@ -201,6 +211,11 @@ export class UndoControllerImpl implements UndoController {
 	private lastCaptureFailed = false;
 	private lastCaptureFailureMessage: string | undefined;
 	private warmUpInFlight: Promise<void> | undefined;
+	private warmUpManifest: SnapshotManifest | undefined;
+	private pendingInputCapture: { readonly token: symbol; readonly promise: Promise<void> } | undefined;
+	private deferAgentStartUntilMessageEnd = false;
+	private recoveryInFlight: Promise<void> | undefined;
+	private recoveryCompleted = false;
 
 	constructor(dependencies: ControllerDependencies, initialState: ControllerInitialState = {}) {
 		this.dependencies = dependencies;
@@ -208,12 +223,34 @@ 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;
 	}
 
 	history(): HistoryState {
 		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;
 	}
@@ -222,7 +259,7 @@ export class UndoControllerImpl implements UndoController {
 		if (this.locked || this.warmUpInFlight !== undefined) return;
 		this.warmUpInFlight = (async () => {
 			try {
-				await this.captureWithWorkspaceLock();
+				this.warmUpManifest = await this.captureWithWorkspaceLock();
 			} catch {
 				// 预热是 best-effort：失败静默，正式 capture 会再次尝试并上报。
 			}
@@ -243,21 +280,49 @@ export class UndoControllerImpl implements UndoController {
 		if (this.operationInFlight) return { action: "defer" };
 		if (context.streaming || text.length === 0) return { action: "continue" };
 		try {
-			const before = await this.captureWithWorkspaceLock();
-			this.lastCaptureFailed = false;
-			this.lastCaptureFailureMessage = undefined;
-			this.historyPaused = false;
-			this.staged = { rawPrompt: text, before, sourceLogicalLeaf: this.dependencies.getLogicalLeafId() };
+			const before = await this.captureInputBaseline();
+			this.stageInput(text, before);
 			return { action: "continue" };
 		} catch (error) {
 			// 无法证明输入前状态：放弃记录本次历史，但绝不吞掉用户输入。
-			this.lastCaptureFailed = true;
-			this.lastCaptureFailureMessage = truncateReason(error instanceof Error ? error.message : String(error));
+			this.recordCaptureFailure(error);
 			return { action: "continue" };
 		}
 	}
 
+	beginInput(text: string, context: InputContext): InputEventResult {
+		if (this.promptDeferralInFlight) return { action: "defer" };
+		if (this.locked) return { action: "continue" };
+		if (this.operationInFlight) return { action: "defer" };
+		if (context.streaming || text.length === 0) return { action: "continue" };
+		this.staged = undefined;
+		this.lastCaptureFailed = false;
+		this.lastCaptureFailureMessage = undefined;
+		this.deferAgentStartUntilMessageEnd = true;
+		const token = Symbol("input-capture");
+		const promise = this.captureInputForToken(text, token);
+		this.pendingInputCapture = { token, promise };
+		void promise.then(() => {
+			if (this.pendingInputCapture?.token === token) this.pendingInputCapture = undefined;
+		});
+		return { action: "continue" };
+	}
+
+	async commitInput(): Promise<void> {
+		if (!this.deferAgentStartUntilMessageEnd) return;
+		const pending = this.pendingInputCapture;
+		if (pending !== undefined) await pending.promise;
+		this.pendingInputCapture = undefined;
+		this.deferAgentStartUntilMessageEnd = false;
+		await this.startAgentRun();
+	}
+
 	async beforeAgentStart(): Promise<void> {
+		if (this.deferAgentStartUntilMessageEnd) return;
+		await this.startAgentRun();
+	}
+
+	private async startAgentRun(): Promise<void> {
 		if (this.locked || this.staged === undefined) return;
 		try {
 			this.staged.startEntryId = await this.dependencies.appendControl("pi-undo:start", {
@@ -266,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;
 		}
@@ -280,19 +345,54 @@ export class UndoControllerImpl implements UndoController {
 		this.redoStack.length = 0;
 	}
 
+	private async captureInputBaseline(): Promise<SnapshotManifest> {
+		// warm-up 仍在进行时先等待，确保随后可以消费已完成的 baseline，而不是再次完整 capture。
+		const warmUp = this.warmUpInFlight;
+		if (warmUp !== undefined) await warmUp;
+		const warmUpManifest = this.warmUpManifest;
+		this.warmUpManifest = undefined;
+		return warmUpManifest !== undefined && this.dependencies.captureBaseline !== undefined
+			? this.captureBaselineWithWorkspaceLock(warmUpManifest)
+			: this.captureWithWorkspaceLock();
+	}
+
+	private async captureInputForToken(text: string, token: symbol): Promise<void> {
+		try {
+			const before = await this.captureInputBaseline();
+			if (this.pendingInputCapture?.token !== token) return;
+			this.stageInput(text, before);
+		} catch (error) {
+			if (this.pendingInputCapture?.token !== token) return;
+			// 无法证明输入前状态：放弃记录本次历史，但绝不吞掉用户输入。
+			this.recordCaptureFailure(error);
+		}
+	}
+
+	private stageInput(text: string, before: SnapshotManifest): void {
+		this.lastCaptureFailed = false;
+		this.lastCaptureFailureMessage = undefined;
+		this.historyPaused = false;
+		this.staged = { rawPrompt: text, before, sourceLogicalLeaf: this.dependencies.getLogicalLeafId() };
+	}
+
+	private recordCaptureFailure(error: unknown): void {
+		this.lastCaptureFailed = true;
+		this.lastCaptureFailureMessage = truncateReason(error instanceof Error ? error.message : String(error));
+	}
+
 	async agentSettled(): Promise<void> {
 		const staged = this.staged;
 		this.staged = undefined;
 		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;
 		}
@@ -300,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) {
@@ -321,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;
 			}
@@ -335,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();
@@ -366,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 };
@@ -379,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;
 			}
@@ -393,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;
 			}
@@ -402,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;
 			}
@@ -411,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;
 		}
 	}
@@ -426,24 +529,37 @@ 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;
 		}
 	}
 
 	async recover(): Promise<void> {
-		try {
-			const result = await this.dependencies.recoverPending();
-			if (result.kind === "locked") this.locked = true;
-		} catch {
-			this.locked = true;
+		if (this.recoveryCompleted) return;
+		const recoveryInFlight = this.recoveryInFlight;
+		if (recoveryInFlight !== undefined) {
+			await recoveryInFlight;
+			return;
 		}
+		const recovery = (async (): Promise<void> => {
+			try {
+				const result = await this.dependencies.recoverPending();
+				if (result.kind === "locked") this.lock(result.reason ?? "recovery_failed");
+			} catch {
+				this.lock("recovery_failed");
+			} finally {
+				this.recoveryCompleted = true;
+			}
+		})();
+		this.recoveryInFlight = recovery;
+		await recovery;
 	}
 
 	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;
@@ -513,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 });
@@ -533,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 });
@@ -552,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;
@@ -616,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 };
@@ -629,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 };
@@ -654,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();
 		}
 	}
 
@@ -703,6 +819,17 @@ export class UndoControllerImpl implements UndoController {
 		}
 	}
 
+	private async captureBaselineWithWorkspaceLock(baseline: SnapshotManifest): Promise<SnapshotManifest> {
+		const captureBaseline = this.dependencies.captureBaseline;
+		if (captureBaseline === undefined) return this.captureWithWorkspaceLock();
+		const lease = await this.dependencies.acquireWorkspaceLock();
+		try {
+			return await captureBaseline(baseline);
+		} finally {
+			await lease.release();
+		}
+	}
+
 	private async compensate(
 		descriptor: OperationDescriptor,
 		rollback: SnapshotManifest,
@@ -727,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

@@ -14,7 +14,7 @@ import {
 import { finalizeDurablePack, hasDurablePack, loadDurablePack } from "./durable-pack.ts";
 import { assertCursor, canonicalJson, checksum, sameWorkspaceSnapshot } from "./encoding.ts";
 import { JournalStore, finalizeCursorMarker, inspectCursorMarkers } from "./journal.ts";
-import type { CheckpointRecord, ManifestId, SessionFileIdentity } from "./model.ts";
+import type { CheckpointRecord, ManifestId, SessionFileIdentity, SnapshotManifest } from "./model.ts";
 import {
 	cleanupPackedMutations,
 	materializePackedMutationJournal,
@@ -50,13 +50,21 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		if (topology.workspaceIdentity !== initialTopology.workspaceIdentity) {
 			throw new Error("workspace identity 已变化");
 		}
-		return store.capture(topology, scopePaths);
+		return store.capture(topology, scopePaths, { topologyAlreadyValidated: true });
+	};
+	const captureBaseline = async (baseline: SnapshotManifest) => {
+		const topology = await discovery.discover(context.cwd);
+		if (topology.workspaceIdentity !== initialTopology.workspaceIdentity) {
+			throw new Error("workspace identity 已变化");
+		}
+		return store.captureBaseline(topology, baseline, undefined, { topologyAlreadyValidated: true });
 	};
 	const recovery = new JournalRecovery({
 		sessionIdentity,
 		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,
@@ -214,6 +222,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		appendControl: async (customType, data) => appendControlEntry(pi, manager, customType, data),
 		appendCursor: async (cursor) => cursorWriter.appendCursor(cursor, pi, sourceFor(manager)),
 		capture,
+		captureBaseline,
 		captureSafety: async (referenceManifestId, targetManifestId, scopePaths) => {
 			const [reference, target] = await Promise.all([
 				store.loadManifest(referenceManifestId),
@@ -251,13 +260,15 @@ 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 {
 		controller,
 		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;
@@ -147,6 +147,8 @@ export interface SnapshotStoreOptions {
 
 export interface CaptureOptions {
 	readonly excludePaths?: readonly string[];
+	/** 调用方刚完成 topology discovery 时跳过重复的捕获前校验。捕获后校验仍然执行。 */
+	readonly topologyAlreadyValidated?: boolean;
 }
 
 export interface SnapshotBlobRequest {
@@ -176,6 +178,12 @@ export class SnapshotStoreError extends Error {
 
 export interface SnapshotStore {
 	capture(topology: RootTopology, scope?: readonly string[], options?: CaptureOptions): Promise<SnapshotManifest>;
+	captureBaseline(
+		topology: RootTopology,
+		baseline: SnapshotManifest,
+		scope?: readonly string[],
+		options?: CaptureOptions,
+	): Promise<SnapshotManifest>;
 	listVisibleLeafPaths(topology: RootTopology, options?: CaptureOptions): Promise<readonly string[]>;
 	loadManifest(id: ManifestId): Promise<SnapshotManifest>;
 	assertComplete(id: ManifestId, scopePaths?: readonly string[]): Promise<void>;
@@ -269,7 +277,9 @@ export class SnapshotStore {
 			}
 			const coverage = captureCoverage(topology.workspaceIdentity, scope);
 			const artifactExclusions = captureExclusions(topology.workspaceIdentity, options.excludePaths);
-			await this.assertTopology(topology, "捕获前 topology 已变化");
+			if (options.topologyAlreadyValidated !== true) {
+				await this.assertTopology(topology, "捕获前 topology 已变化");
+			}
 			const brokenRoots = brokenRootPaths(topology);
 			if (brokenRoots.length > 0) {
 				throw new SnapshotStoreError("capture_failed", `broken root 不能静默进入快照: ${brokenRoots.join(", ")}`);
@@ -350,6 +360,189 @@ export class SnapshotStore {
 		}
 	}
 
+	/**
+	 * 复核 warm-up 生成的 baseline；只有 topology、可见路径、文件 metadata 和 ignored proof
+	 * 都能由现有证据证明未变化时，才跳过完整 capture。
+	 */
+	async captureBaseline(
+		topology: RootTopology,
+		baseline: SnapshotManifest,
+		scope?: readonly string[],
+		options: CaptureOptions = {},
+	): Promise<SnapshotManifest> {
+		await this.assertPrivateStore(topology.workspaceIdentity);
+		const lockIdentity = `snapshot-store:${await prospectiveCanonicalPath(this.storesRoot)}`;
+		return this.lock.withLock(lockIdentity, () => this.captureBaselineLocked(topology, baseline, scope, options));
+	}
+
+	private async captureBaselineLocked(
+		topology: RootTopology,
+		baseline: SnapshotManifest,
+		scope: readonly string[] | undefined,
+		options: CaptureOptions,
+	): Promise<SnapshotManifest> {
+		try {
+			if (topology.fingerprint !== topologyFingerprint(topology.workspaceIdentity, topology.roots)) {
+				throw new SnapshotStoreError("capture_failed", "topology fingerprint 与 roots 不匹配");
+			}
+			if (options.topologyAlreadyValidated !== true) {
+				await this.assertTopology(topology, "捕获前 topology 已变化");
+			}
+			const brokenRoots = brokenRootPaths(topology);
+			if (brokenRoots.length > 0) {
+				throw new SnapshotStoreError("capture_failed", `broken root 不能静默进入 baseline 校验: ${brokenRoots.join(", ")}`);
+			}
+			if (await this.isBaselineFresh(topology, baseline, scope, options)) {
+				await this.assertTopology(topology, "捕获期间 topology 已变化");
+				await this.touchStore(this.storeDirectory(topology));
+				return baseline;
+			}
+			// 已完成一次捕获前 topology 校验；完整回退仍保留捕获后的校验。
+			return this.captureLocked(topology, scope, { ...options, topologyAlreadyValidated: true });
+		} catch (error) {
+			if (error instanceof SnapshotStoreError) {
+				throw error;
+			}
+			throw new SnapshotStoreError("capture_failed", errorMessage(error), { cause: error });
+		}
+	}
+
+	private async isBaselineFresh(
+		topology: RootTopology,
+		baseline: SnapshotManifest,
+		scope: readonly string[] | undefined,
+		options: CaptureOptions,
+	): Promise<boolean> {
+		try {
+			assertManifest(baseline);
+		} catch {
+			return false;
+		}
+		const artifactExclusions = captureExclusions(topology.workspaceIdentity, options.excludePaths);
+		if (
+			baseline.workspaceIdentity !== topology.workspaceIdentity ||
+			baseline.topologyFingerprint !== topology.fingerprint ||
+			baseline.coverage !== captureCoverage(topology.workspaceIdentity, scope) ||
+			baseline.roots.length !== topology.roots.length
+		) {
+			return false;
+		}
+
+		const storeDirectory = this.storeDirectory(topology);
+		await this.loadPersistedLeafCache(storeDirectory);
+		const transactionsRoot = join(storeDirectory, "transactions");
+		await mkdir(transactionsRoot, { recursive: true });
+		const transactionDirectory = await mkdtemp(join(transactionsRoot, "baseline-"));
+		try {
+			const baselineRoots = new Map(baseline.roots.map((root) => [root.relativeRoot, root]));
+			for (const root of topology.roots) {
+				const baselineRoot = baselineRoots.get(root.relativeRoot);
+				if (
+					baselineRoot === undefined ||
+					baselineRoot.parentRoot !== root.parentRoot ||
+					baselineRoot.state !== root.state ||
+					baselineRoot.sourceIdentity !== root.sourceIdentity ||
+					baselineRoot.privateRepositoryId !== root.privateRepositoryId ||
+					(baselineRoot.gitlinkOid ?? null) !== (root.gitlinkOid ?? null) ||
+					baselineRoot.coverage !== rootCaptureCoverage(root.relativeRoot, scope, topology.roots) ||
+					baselineRoot.ignorePolicy !== IGNORE_POLICY
+				) {
+					return false;
+				}
+				if (root.state !== "active") {
+					if (
+						baselineRoot.treeId !== null ||
+						baselineRoot.ignoredPresentPaths.length > 0 ||
+						baselineRoot.objectClosure !== inactiveRootClosure(root)
+					) {
+						return false;
+					}
+					continue;
+				}
+
+				const treeId = baselineRoot.treeId;
+				if (treeId === null) return false;
+				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
+				await this.ensurePrivateRepository(gitDirectory);
+				await this.assertNoAlternates(gitDirectory);
+				const absoluteRoot = workspaceRootPath(topology.workspaceIdentity, root.relativeRoot);
+				const indexPath = join(transactionDirectory, `${rootStoreId(root)}.index`);
+				const environment = privateGitEnvironment(gitDirectory, absoluteRoot, indexPath);
+				await this.runGit(["read-tree", "--empty"], { cwd: absoluteRoot, env: environment });
+				await this.validateIgnoreQuery(absoluteRoot, environment, root.gitBacked);
+
+				const requestedInclusions = rootScopePathspecs(root.relativeRoot, scope);
+				const exclusions = topology.roots
+					.filter((candidate) => isStrictRootAncestor(root.relativeRoot, candidate.relativeRoot))
+					.map((candidate) => rootRelativePath(root.relativeRoot, candidate.relativeRoot));
+				const exactExclusions = ownedArtifactExclusions(topology.roots, root.relativeRoot, artifactExclusions);
+				const inclusions = ownedRootInclusions(requestedInclusions, exclusions);
+				const entries = await this.readTreeEntries(gitDirectory, treeId);
+				await this.assertObjectsComplete(gitDirectory, treeId, entries);
+				if (baselineRoot.objectClosure !== treeObjectClosure(treeId, entries)) return false;
+
+				const leaves = await this.collectVisibleLeaves(
+					absoluteRoot,
+					environment,
+					root.gitBacked,
+					inclusions,
+					exclusions,
+					exactExclusions,
+					transactionDirectory,
+				);
+				if (!samePathList(
+					leaves.map((leaf) => leaf.relativePath).sort(comparePaths),
+					entries.map((entry) => entry.relativePath).sort(comparePaths),
+				)) {
+					return false;
+				}
+				const cache = this.visibleLeafCache.get(gitDirectory);
+				if (cache === undefined) return false;
+				const entriesByPath = new Map(entries.map((entry) => [entry.relativePath, entry]));
+				for (const leaf of leaves) {
+					const entry = entriesByPath.get(leaf.relativePath);
+					const cached = cache.get(leaf.relativePath);
+					if (
+						entry === undefined ||
+						!leaf.cacheable ||
+						cached?.cacheable !== true ||
+						cached.kind !== leaf.kind ||
+						cached.mode !== leaf.mode ||
+						cached.fingerprint !== leaf.fingerprint ||
+						cached.objectId !== entry.objectId ||
+						cached.verifiedAtNs <= cached.changedAtNs + RACY_CLEAN_WINDOW_NS
+					) {
+						return false;
+					}
+				}
+
+				const ignoredPresentPaths = await this.captureIgnoredPresentPaths(
+					absoluteRoot,
+					environment,
+					root.gitBacked,
+					inclusions,
+					exclusions,
+					exactExclusions,
+					transactionDirectory,
+				);
+				if (!samePathList(ignoredPresentPaths, baselineRoot.ignoredPresentPaths)) return false;
+				if (baselineRoot.ignoreClosure !== ignoredPresentClosure({
+					coverage: baselineRoot.coverage,
+					ignorePolicy: IGNORE_POLICY,
+					ignoredPresentPaths,
+				})) return false;
+				// metadata 初检与最终复核之间若有变化，放弃 baseline，回退完整 capture。
+				await this.assertVisibleLeavesUnchanged(absoluteRoot, leaves, transactionDirectory);
+			}
+			return true;
+		} catch {
+			// baseline 证据读取失败时不复用旧快照；完整 capture 会重新建立对象和缓存。
+			return false;
+		} finally {
+			await rm(transactionDirectory, { recursive: true, force: true }).catch(() => {});
+		}
+	}
+
 	async listVisibleLeafPaths(
 		topology: RootTopology,
 		options: CaptureOptions = {},
@@ -817,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);
@@ -834,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;
 			}
@@ -859,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) => {
@@ -1050,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]!;
@@ -1064,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));
 	}
@@ -1142,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]!;
@@ -1593,8 +1797,17 @@ function ownedRootInclusions(
 	return owned.length === 0 ? null : owned;
 }
 
-function rootCaptureCoverage(rootPath: string, scope: readonly string[] | undefined): string {
-	return rootCoverageFromInclusions(rootScopePathspecs(rootPath, scope));
+function rootCaptureCoverage(
+	rootPath: string,
+	scope: readonly string[] | undefined,
+	roots?: readonly RootTopologyIdentity[],
+): string {
+	const requestedInclusions = rootScopePathspecs(rootPath, scope);
+	if (roots === undefined) return rootCoverageFromInclusions(requestedInclusions);
+	const exclusions = roots
+		.filter((root) => isStrictRootAncestor(rootPath, root.relativeRoot))
+		.map((root) => rootRelativePath(rootPath, root.relativeRoot));
+	return rootCoverageFromInclusions(ownedRootInclusions(requestedInclusions, exclusions));
 }
 
 function rootCoverageFromInclusions(inclusions: readonly string[] | null): string {
@@ -2186,6 +2399,10 @@ function gitExitCode(error: unknown): number | null | undefined {
 		: undefined;
 }
 
+function samePathList(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((path, index) => path === right[index]);
+}
+
 function comparePaths(left: string, right: string): number {
 	return left < right ? -1 : left > right ? 1 : 0;
 }

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 {