@davideasden/pi-undo 0.2.14 → 0.2.16

package/extensions/pi-undo.ts

@@ -218,9 +218,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 +255,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 +268,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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.14",
+	"version": "0.2.16",
 	"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>;
@@ -170,6 +175,7 @@ export interface ControllerInitialState {
 	readonly redoStack?: readonly ControllerRedoEntry[];
 	readonly historyPaused?: boolean;
 	readonly locked?: boolean;
+	readonly recoveryCompleted?: boolean;
 }
 
 interface PendingTree {
@@ -201,6 +207,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,6 +219,7 @@ export class UndoControllerImpl implements UndoController {
 		this.redoStack.push(...(initialState.redoStack ?? []));
 		this.historyPaused = initialState.historyPaused ?? false;
 		this.locked = initialState.locked ?? false;
+		this.recoveryCompleted = initialState.recoveryCompleted ?? false;
 	}
 
 	history(): HistoryState {
@@ -222,7 +234,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 +255,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", {
@@ -280,6 +320,41 @@ 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;
@@ -434,12 +509,24 @@ export class UndoControllerImpl implements UndoController {
 	}
 
 	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.locked = true;
+			} catch {
+				this.locked = true;
+			} finally {
+				this.recoveryCompleted = true;
+			}
+		})();
+		this.recoveryInFlight = recovery;
+		await recovery;
 	}
 
 	private async runOperation(action: "undo" | "redo"): Promise<OperationResult> {
@@ -703,6 +790,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,

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,7 +50,14 @@ 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,
@@ -214,6 +221,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,6 +259,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 	const controller = new UndoControllerImpl(dependencies, {
 		...rebuildControllerState(manager, sessionIdentity),
 		locked: startupRecovery.kind === "locked",
+		recoveryCompleted: true,
 	});
 	return {
 		controller,

package/src/snapshot-store.ts

@@ -3,7 +3,7 @@ import { lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-import { fsyncDirectory, writeContentAddressed, writeJsonAtomic } from "./atomic-fs.ts";
+import { fsyncDirectory, writeBytesAtomic, writeContentAddressed, writeJsonAtomic } from "./atomic-fs.ts";
 import {
 	assertManifest,
 	canonicalJson,
@@ -47,6 +47,7 @@ const BLOB_CACHE_MAX_BYTES = 128 * 1024 * 1024;
 const BLOB_BATCH_MAX_BYTES = 16 * 1024 * 1024;
 const BLOB_BATCH_MAX_ENTRIES = process.platform === "win32" ? 256 : 2_048;
 const RACY_CLEAN_WINDOW_NS = 2_000_000_000n;
+const LEAF_CACHE_FILE = "leaf-cache.json";
 
 interface PinRecord {
 	readonly schemaVersion: 1;
@@ -119,6 +120,22 @@ interface CachedBlob {
 	size: number;
 }
 
+/** 持久化叶子缓存文件（storeDirectory/leaf-cache.json），schema 不匹配时整体忽略。 */
+interface PersistedLeafCacheFile {
+	readonly schemaVersion: 1;
+	readonly entries: Readonly<Record<string, Readonly<Record<string, PersistedLeafCacheEntry>>>>;
+}
+
+interface PersistedLeafCacheEntry {
+	readonly kind: "file" | "symlink";
+	readonly mode: number;
+	readonly fingerprint: string;
+	readonly cacheable: boolean;
+	readonly objectId: string;
+	readonly changedAtNs: string;
+	readonly verifiedAtNs: string;
+}
+
 export interface SnapshotStoreOptions {
 	readonly storeRoot?: string;
 	readonly git?: GitRunner;
@@ -130,6 +147,8 @@ export interface SnapshotStoreOptions {
 
 export interface CaptureOptions {
 	readonly excludePaths?: readonly string[];
+	/** 调用方刚完成 topology discovery 时跳过重复的捕获前校验。捕获后校验仍然执行。 */
+	readonly topologyAlreadyValidated?: boolean;
 }
 
 export interface SnapshotBlobRequest {
@@ -159,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>;
@@ -184,6 +209,7 @@ export class SnapshotStore {
 	private readonly treeBlobMembership = new Map<string, string>();
 	private readonly blobCache = new Map<string, CachedBlob>();
 	private readonly visibleLeafCache = new Map<string, Map<string, CachedVisibleLeaf>>();
+	private readonly leafCacheDirectoriesLoaded = new Set<string>();
 	private blobCacheBytes = 0;
 
 	constructor(options: SnapshotStoreOptions = {}) {
@@ -251,13 +277,17 @@ 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(", ")}`);
 			}
 
 			const storeDirectory = this.storeDirectory(topology);
+			// 新进程首次 capture 时从磁盘加载叶子指纹缓存，避免全量重新 hash。
+			await this.loadPersistedLeafCache(storeDirectory);
 			const transactionsRoot = join(storeDirectory, "transactions");
 			await mkdir(transactionsRoot, { recursive: true });
 			transactionDirectory = await mkdtemp(join(transactionsRoot, "capture-"));
@@ -315,6 +345,8 @@ export class SnapshotStore {
 			await writeContentAddressed(manifestPath, Buffer.from(canonicalJson(manifest), "utf8"));
 			this.manifestLocations.set(manifestId, manifestPath);
 			for (const update of cacheUpdates) this.rememberVisibleLeaves(update);
+			// 指纹缓存落盘：让下一个进程（新会话）的首次 capture 跳过全量内容 hash。
+			await this.persistLeafCache(storeDirectory);
 			return manifest;
 		} catch (error) {
 			if (error instanceof SnapshotStoreError) {
@@ -328,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 = {},
@@ -960,6 +1175,69 @@ export class SnapshotStore {
 		this.visibleLeafCache.set(gitDirectory, cache);
 	}
 
+	/** 从 storeDirectory 读取持久化叶子缓存并合并进内存；进程内已有条目优先。 */
+	private async loadPersistedLeafCache(storeDirectory: string): Promise<void> {
+		if (this.leafCacheDirectoriesLoaded.has(storeDirectory)) return;
+		this.leafCacheDirectoriesLoaded.add(storeDirectory);
+		let file: unknown;
+		try {
+			file = JSON.parse(await readFile(join(storeDirectory, LEAF_CACHE_FILE), "utf8"));
+		} catch {
+			return; // 缺失或损坏：忽略，本次 capture 走冷路径并重建缓存。
+		}
+		if (!isPersistedLeafCacheFile(file)) return;
+		const prefix = `${storeDirectory}${sep}`;
+		for (const [gitDirectory, entries] of Object.entries(file.entries)) {
+			if (!gitDirectory.startsWith(prefix) || this.visibleLeafCache.has(gitDirectory)) continue;
+			const cache = new Map<string, CachedVisibleLeaf>();
+			for (const [relativePath, entry] of Object.entries(entries)) {
+				cache.set(relativePath, {
+					relativePath,
+					kind: entry.kind,
+					mode: entry.mode,
+					fingerprint: entry.fingerprint,
+					cacheable: entry.cacheable,
+					changedAtNs: BigInt(entry.changedAtNs),
+					objectId: entry.objectId,
+					verifiedAtNs: BigInt(entry.verifiedAtNs),
+				});
+			}
+			this.visibleLeafCache.set(gitDirectory, cache);
+		}
+	}
+
+	/** 把当前 storeDirectory 范围内的叶子缓存原子写入磁盘（best-effort）。 */
+	private async persistLeafCache(storeDirectory: string): Promise<void> {
+		const prefix = `${storeDirectory}${sep}`;
+		const entries: Record<string, Record<string, PersistedLeafCacheEntry>> = {};
+		for (const [gitDirectory, cache] of this.visibleLeafCache) {
+			if (!gitDirectory.startsWith(prefix)) continue;
+			const rootEntries: Record<string, PersistedLeafCacheEntry> = {};
+			for (const [relativePath, leaf] of cache) {
+				rootEntries[relativePath] = {
+					kind: leaf.kind,
+					mode: leaf.mode,
+					fingerprint: leaf.fingerprint,
+					cacheable: leaf.cacheable,
+					objectId: leaf.objectId,
+					changedAtNs: leaf.changedAtNs.toString(),
+					verifiedAtNs: leaf.verifiedAtNs.toString(),
+				};
+			}
+			entries[gitDirectory] = rootEntries;
+		}
+		try {
+			// 用普通 JSON 序列化（非 canonicalJson）：缓存只在本机消费，避免大规模排序开销。
+			await writeBytesAtomic(
+				join(storeDirectory, LEAF_CACHE_FILE),
+				Buffer.from(JSON.stringify({ schemaVersion: 1, entries }), "utf8"),
+				0o600,
+			);
+		} catch {
+			// 缓存写入是 best-effort：失败只影响下次性能，不影响正确性。
+		}
+	}
+
 	private async assertVisibleLeavesUnchanged(
 		cwd: string,
 		leaves: readonly VisibleLeaf[],
@@ -1508,8 +1786,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 {
@@ -1792,6 +2079,33 @@ function nativeVisibleLeafMetadata(entry: NativeMetadataEntry): VisibleLeafMetad
 	};
 }
 
+function isPersistedLeafCacheFile(value: unknown): value is PersistedLeafCacheFile {
+	if (typeof value !== "object" || value === null) return false;
+	const file = value as { schemaVersion?: unknown; entries?: unknown };
+	if (file.schemaVersion !== 1 || typeof file.entries !== "object" || file.entries === null) return false;
+	for (const entries of Object.values(file.entries as Record<string, unknown>)) {
+		if (typeof entries !== "object" || entries === null) return false;
+		for (const entry of Object.values(entries as Record<string, unknown>)) {
+			if (typeof entry !== "object" || entry === null) return false;
+			const candidate = entry as Partial<PersistedLeafCacheEntry>;
+			if (
+				(candidate.kind !== "file" && candidate.kind !== "symlink") ||
+				typeof candidate.mode !== "number" ||
+				typeof candidate.fingerprint !== "string" ||
+				typeof candidate.cacheable !== "boolean" ||
+				typeof candidate.objectId !== "string" ||
+				typeof candidate.changedAtNs !== "string" ||
+				typeof candidate.verifiedAtNs !== "string" ||
+				!/^[0-9]+$/.test(candidate.changedAtNs) ||
+				!/^[0-9]+$/.test(candidate.verifiedAtNs)
+			) {
+				return false;
+			}
+		}
+	}
+	return true;
+}
+
 function visibleLeafFingerprint(metadata: VisibleLeafMetadata): string {
 	return checksum(canonicalJson({
 		kind: metadata.kind,
@@ -2074,6 +2388,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;
 }