@davideasden/pi-undo 0.2.17 → 0.2.20

package/extensions/pi-undo.ts

@@ -69,8 +69,6 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 						next.recovery,
 					);
 				} else next.reporter.setReady(history.undoCount, history.redoCount);
-				// 后台预热快照缓存，把新会话首次冷 capture 移出第一条 prompt 的关键路径。
-				next.controller.warmUp();
 			} catch (error) {
 				if (currentGeneration !== generation) return;
 				runtime = undefined;

package/package.json

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

package/src/durable-pack.ts

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

package/src/journal.ts

@@ -2,6 +2,7 @@ import { appendFile, lstat, readFile, readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { fsyncDirectory, fsyncFile, writeContentAddressed, writeJsonAtomic } from "./atomic-fs.ts";
+import { hasDurablePack } from "./durable-pack.ts";
 import {
 	assertCursor,
 	assertJournalState,
@@ -13,6 +14,7 @@ import type {
 	CursorState,
 	JournalPhase,
 	JournalState,
+	MutationRecord,
 	OperationDescriptor,
 } from "./model.ts";
 import { MutationJournal } from "./mutation-journal.ts";
@@ -154,6 +156,31 @@ export class JournalStore {
 		}
 	}
 
+	/**
+	 * 判断 transaction 的 mutation 义务是否已全部履行且净效果回到操作前状态：
+	 * 所有记录都达到 CLEANED，且按路径折叠的 fingerprint 链首尾相接（前向变更
+	 * 被补偿变更精确抵消）；没有任何 mutation 记录且无 durable pack 时视为从未发生。
+	 * 这是纯只读检查；评估期间 journal 发生变化或任何证据不确定时都返回 false。
+	 */
+	async isFullyCompensated(pending: PendingJournal): Promise<boolean> {
+		try {
+			const current = await this.load(pending.descriptor.opId);
+			if (!samePendingJournal(current, pending)) return false;
+			const mutationJournal = this.mutationJournal(pending.descriptor.opId);
+			const records = await mutationJournal.load();
+			const compensated = records.length === 0
+				? !await hasDurablePack(mutationJournal)
+				: fingerprintChainsFoldToIdentity(records);
+			if (!compensated) return false;
+			const verified = await this.load(pending.descriptor.opId);
+			if (!samePendingJournal(verified, current)) return false;
+			const reloaded = await mutationJournal.load();
+			return reloaded.length === records.length && fingerprintChainsFoldToIdentity(reloaded);
+		} catch {
+			return false;
+		}
+	}
+
 	async assertLogicalCommitReady(opId: string, allowPendingMutations = false): Promise<void> {
 		if (!allowPendingMutations) await this.mutationJournal(opId).assertCleaned();
 		const pending = await this.load(opId);
@@ -414,6 +441,24 @@ function samePendingJournal(left: PendingJournal, right: PendingJournal): boolea
 	}
 }
 
+function fingerprintChainsFoldToIdentity(records: readonly MutationRecord[]): boolean {
+	const chains = new Map<string, { source: string; target: string }>();
+	for (const record of records) {
+		if (record.state !== "CLEANED") return false;
+		const chain = chains.get(record.path);
+		if (chain === undefined) {
+			chains.set(record.path, { source: record.sourceFingerprint, target: record.targetFingerprint });
+			continue;
+		}
+		if (record.sourceFingerprint !== chain.target) return false;
+		chain.target = record.targetFingerprint;
+	}
+	for (const chain of chains.values()) {
+		if (chain.target !== chain.source) return false;
+	}
+	return true;
+}
+
 function isEmptyArray(value: unknown): value is readonly unknown[] {
 	return Array.isArray(value) && value.length === 0;
 }

package/src/pi-runtime.ts

@@ -65,6 +65,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 		getLogicalLeafId: () => sessionStateFor(manager).getLogicalLeafId(),
 		loadPending: () => journal.loadPending(),
 		assessForeignTransaction: (pending) => journal.isInertForeignPrepared(pending),
+		assessCompensatedTransaction: (pending) => journal.isFullyCompensated(pending),
 		inspectCursor: (pending) => inspectCursorMarkers(pending.descriptor.sessionIdentity.path, pending.descriptor),
 		finalizeCursor: (pending, inspection) => finalizeCursorMarker(
 			pending.descriptor.sessionIdentity.path,

package/src/recovery.ts

@@ -11,6 +11,8 @@ export interface JournalRecoveryDependencies {
 	readonly loadPending: () => Promise<readonly PendingJournal[]>;
 	/** 仅允许严格证明无工作区 mutation 的 foreign PREPARED 空事务被忽略。 */
 	readonly assessForeignTransaction?: (journal: PendingJournal) => Promise<boolean>;
+	/** 判断 transaction 是否已被完全补偿（mutation 全部 CLEANED 且净效果回到操作前状态），可直接 settle。 */
+	readonly assessCompensatedTransaction?: (journal: PendingJournal) => Promise<boolean>;
 	readonly inspectCursor: (journal: PendingJournal) => Promise<CursorMarkerInspection>;
 	readonly finalizeCursor: (journal: PendingJournal, inspection: Extract<CursorMarkerInspection, { kind: "match" }>) => Promise<void>;
 	readonly recoverMutations: (
@@ -67,9 +69,22 @@ 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;
+				if (identityError === "session_identity_mismatch") {
+					if (await this.settleCompensated(journal)) {
+						recovered += 1;
+						continue;
+					}
+					if (await this.canIgnoreForeignTransaction(journal)) continue;
+				}
 				return { kind: "locked", reason: identityError, operations: recovered };
 			}
+			// 同一会话（重启或第二窗口）内，完全补偿的事务同样可直接 settle：
+			// 工作区义务已全部履行且无 cursor 提交证据，session leaf 位置对
+			// ABORTED 终结不构成安全输入，无需通过 leaf 校验。
+			if (await this.settleCompensated(journal)) {
+				recovered += 1;
+				continue;
+			}
 			let inspection: CursorMarkerInspection;
 			try {
 				inspection = await this.dependencies.inspectCursor(journal);
@@ -145,6 +160,38 @@ export class JournalRecovery {
 		}
 	}
 
+	/**
+	 * 终结完全补偿的 pending transaction（own session 重启/第二窗口与 foreign 会话均适用）。
+	 * 调用方持有 workspace lock，pending 非终态事务的 owner 操作已确定性结束；
+	 * mutation 义务全部履行且净效果回到操作前状态时，无需触碰工作区即可 settle。
+	 * cursor marker 必须缺失——marker 存在意味着操作已提交，与补偿证据矛盾，fail closed。
+	 */
+	private async settleCompensated(journal: PendingJournal): Promise<boolean> {
+		const assess = this.dependencies.assessCompensatedTransaction;
+		if (assess === undefined) return false;
+		let compensated: boolean;
+		try {
+			compensated = await assess(journal);
+		} catch {
+			// 评估失败等同于证据不足，退回原有恢复语义。
+			return false;
+		}
+		if (!compensated) return false;
+		let inspection: CursorMarkerInspection;
+		try {
+			inspection = await this.dependencies.inspectCursor(journal);
+		} catch {
+			return false;
+		}
+		if (inspection.kind !== "absent") return false;
+		try {
+			await this.dependencies.settle(journal.descriptor.opId, "ABORTED");
+		} catch {
+			return false;
+		}
+		return true;
+	}
+
 	private identityError(journal: PendingJournal): string | null {
 		if (journal.descriptor.workspaceIdentity !== this.dependencies.workspaceIdentity) {
 			return "workspace_identity_mismatch";

package/src/restore-engine.ts

@@ -4,8 +4,11 @@ import { lstat, mkdir, mkdtemp, readFile, readlink, realpath, rm, rmdir } from "
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
+import { writeJsonAtomic } from "./atomic-fs.ts";
 import {
 	createDurablePack,
+	hasDurablePack,
+	loadDurablePack,
 	publishCachedDurablePack,
 	removeDurablePack,
 	type DurableLeafInput,
@@ -33,11 +36,15 @@ import {
 	type ReplaceFileRequest,
 } from "./quarantine.ts";
 import { SnapshotStore, SnapshotStoreError } from "./snapshot-store.ts";
+import { WorkspaceLock } from "./workspace-lock.ts";
 
 const PREPARED_PLAN_CACHE_LIMIT = 16;
+const DURABLE_CACHE_INDEX_FILE = "index.json";
+const DURABLE_PACK_MEMORY_MAX_BYTES = 64 * 1024 * 1024;
 const RESTORE_FILE_BATCH_MAX_ENTRIES = 1_024;
 const RESTORE_FILE_BATCH_MAX_BYTES = 64 * 1024 * 1024;
 const RESTORE_FILE_PREPARE_CONCURRENCY = 32;
+const RESTORE_FILE_VERIFY_CONCURRENCY = 32;
 
 export interface RestorePlan {
 	currentManifestId: ManifestId;
@@ -73,6 +80,8 @@ export interface RestoreEngineOptions {
 	readonly store: SnapshotStore;
 	readonly discovery?: RootDiscovery;
 	readonly beforeMutation?: (mutation: RestoreMutation) => void | Promise<void>;
+	/** 仅用于测试：覆盖进程内已加载 durable pack 的内存预算。 */
+	readonly durablePackCacheMaxBytes?: number;
 }
 
 export interface RestoreMutation {
@@ -94,6 +103,40 @@ interface PreparedRestorePlan {
 	readonly targetPaths: ReadonlyMap<string, OwnedPath>;
 }
 
+interface DurableCacheIndexEntry {
+	readonly currentManifestId: ManifestId;
+	readonly targetManifestId: ManifestId;
+	readonly scopePaths: readonly string[];
+	readonly planDigest: string;
+	readonly packChecksum: string;
+}
+
+interface DurableCacheIndex {
+	readonly schemaVersion: 1;
+	entries: DurableCacheIndexEntry[];
+}
+
+interface CachedDurablePack {
+	readonly currentManifestId: ManifestId;
+	readonly targetManifestId: ManifestId;
+	readonly path: string;
+	readonly packChecksum: string;
+	readonly pinReason: string;
+	readonly pinsDeferred: boolean;
+}
+
+interface CachedDurablePair {
+	readonly planDigest: string;
+	readonly pack: DurablePack;
+	readonly bytes: number;
+}
+
+type DurableIndexDisk =
+	| { readonly kind: "ok"; readonly index: DurableCacheIndex }
+	| { readonly kind: "missing" }
+	| { readonly kind: "corrupt" }
+	| { readonly kind: "unavailable" };
+
 interface MutationContext {
 	readonly phase: RestoreMutation["phase"];
 	readonly sourceManifestId: ManifestId;
@@ -114,17 +157,17 @@ export class RestoreEngine {
 	private readonly discovery: RootDiscovery;
 	private readonly beforeMutation: RestoreEngineOptions["beforeMutation"];
 	private readonly preparedPlans = new Map<string, PreparedRestorePlan>();
-	private readonly durablePackCache = new Map<string, {
-		readonly currentManifestId: ManifestId;
-		readonly targetManifestId: ManifestId;
-		readonly path: string;
-		readonly packChecksum: string;
-		readonly pinReason: string;
-	}>();
-	private readonly durablePackByPair = new Map<string, {
-		readonly planDigest: string;
-		readonly pack: DurablePack;
-	}>();
+	private readonly durablePackCache = new Map<string, CachedDurablePack>();
+	private readonly durablePackByPair = new Map<string, CachedDurablePair>();
+	private readonly durableIndexLock = new WorkspaceLock({
+		leaseMs: 10_000,
+		retryMs: 25,
+		acquireTimeoutMs: 1_000,
+	});
+	private readonly durablePackCacheMaxBytes: number;
+	private durableIndex: DurableCacheIndex | undefined;
+	private durableIndexQueue: Promise<void> = Promise.resolve();
+	private durablePackMemoryBytes = 0;
 
 	constructor(options: RestoreEngineOptions) {
 		this.requestedWorkspaceRoot = resolve(options.workspaceRoot);
@@ -132,6 +175,10 @@ export class RestoreEngine {
 		this.store = options.store;
 		this.discovery = options.discovery ?? new RootDiscovery();
 		this.beforeMutation = options.beforeMutation;
+		this.durablePackCacheMaxBytes = options.durablePackCacheMaxBytes ?? DURABLE_PACK_MEMORY_MAX_BYTES;
+		if (!Number.isSafeInteger(this.durablePackCacheMaxBytes) || this.durablePackCacheMaxBytes <= 0) {
+			throw new Error("durable pack 内存预算必须是正整数");
+		}
 	}
 
 	private async compatibleApplyOptions(): Promise<{
@@ -225,14 +272,27 @@ export class RestoreEngine {
 		target: SnapshotManifest,
 		scopePaths: readonly string[],
 	): Promise<boolean> {
-		const cached = this.durablePackByPair.get(durablePairKey(current.manifestId, target.manifestId, scopePaths));
-		if (cached === undefined) return false;
+		const pairKey = durablePairKey(current.manifestId, target.manifestId, scopePaths);
+		let cached = this.durablePackByPair.get(pairKey);
+		if (cached !== undefined && !this.durablePackCache.has(cached.planDigest)) {
+			this.dropResidentDurablePack(pairKey);
+			cached = undefined;
+		}
+		const fromPersistentIndex = cached === undefined;
+		if (cached === undefined) {
+			cached = await this.readIndexedDurablePack(current.manifestId, target.manifestId, scopePaths);
+		}
+		if (cached === undefined || cached.pack.opId !== `cache-${cached.planDigest}`) return false;
 		const cacheJournal = new MutationJournal(
 			join(dirname(cached.pack.storagePath), "mutations.jsonl"),
 			`cache-${cached.planDigest}`,
 		);
 		try {
 			if (await this.assertWorkspaceRootIdentity() !== current.workspaceIdentity) return false;
+			if (fromPersistentIndex) {
+				const expected = await this.plan(current, target, scopePaths);
+				if (expected.planDigest !== cached.planDigest) return false;
+			}
 			const topology = await this.discovery.discover(this.workspaceRoot);
 			this.assertCurrentTopology(current, target, topology);
 			const native = await createNativeFileBatch({
@@ -240,7 +300,19 @@ export class RestoreEngine {
 				planDigest: cached.planDigest,
 				journal: cacheJournal,
 			});
-			return native !== undefined && await native.verifySource(cached.pack);
+			if (native === undefined || !await native.verifySource(cached.pack)) return false;
+			if (fromPersistentIndex) {
+				await this.rememberDurablePackInMemory(
+					cached.planDigest,
+					current,
+					target,
+					scopePaths,
+					cached.pack,
+					`durable-cache:${cached.planDigest}`,
+					false,
+				);
+			}
+			return true;
 		} catch {
 			return false;
 		}
@@ -286,7 +358,7 @@ export class RestoreEngine {
 			throw error;
 		}
 		await this.rememberDurablePack(
-			plan,
+			plan.planDigest,
 			current,
 			target,
 			scopePaths,
@@ -297,41 +369,245 @@ export class RestoreEngine {
 	}
 
 	private async rememberDurablePack(
-		plan: RestorePlan,
+		planDigest: string,
 		current: SnapshotManifest,
 		target: SnapshotManifest,
 		scopePaths: readonly string[],
 		pack: DurablePack,
 		pinReason: string,
 	): Promise<void> {
-		this.durablePackCache.set(plan.planDigest, {
+		await this.rememberDurablePackInMemory(planDigest, current, target, scopePaths, pack, pinReason, true);
+		await this.enqueueDurableIndex(async () => {
+			const lease = await this.acquireDurableIndexLease();
+			if (lease === undefined) return;
+			try {
+				const disk = await this.readDurableIndexFromDisk();
+				if (disk.kind === "unavailable") return;
+				this.durableIndex = disk.kind === "ok"
+					? disk.index
+					: { schemaVersion: 1, entries: [] };
+				this.upsertDurableIndexEntry({
+					currentManifestId: current.manifestId,
+					targetManifestId: target.manifestId,
+					scopePaths: [...scopePaths],
+					planDigest,
+					packChecksum: pack.packChecksum,
+				});
+				await this.evictPersistedDurablePacks(planDigest);
+				await this.persistDurableIndex();
+			} finally {
+				await lease.release().catch(() => {});
+			}
+		});
+	}
+
+	private async rememberDurablePackInMemory(
+		planDigest: string,
+		current: SnapshotManifest,
+		target: SnapshotManifest,
+		scopePaths: readonly string[],
+		pack: DurablePack,
+		pinReason: string,
+		pinsDeferred: boolean,
+	): Promise<void> {
+		this.durablePackCache.delete(planDigest);
+		this.durablePackCache.set(planDigest, {
 			currentManifestId: current.manifestId,
 			targetManifestId: target.manifestId,
 			path: pack.storagePath,
 			packChecksum: pack.packChecksum,
 			pinReason,
+			pinsDeferred,
 		});
-		this.durablePackByPair.set(durablePairKey(current.manifestId, target.manifestId, scopePaths), {
-			planDigest: plan.planDigest,
+		this.trimDurablePackMetadata();
+		await this.rememberResidentDurablePack(
+			durablePairKey(current.manifestId, target.manifestId, scopePaths),
+			planDigest,
 			pack,
-		});
+		);
+	}
+
+	private trimDurablePackMetadata(): void {
 		while (this.durablePackCache.size > PREPARED_PLAN_CACHE_LIMIT) {
-			const oldest = this.durablePackCache.entries().next().value as
-				| readonly [string, { readonly currentManifestId: ManifestId; readonly targetManifestId: ManifestId; readonly path: string; readonly packChecksum: string; readonly pinReason: string }]
-				| undefined;
+			const oldest = this.durablePackCache.keys().next().value as string | undefined;
 			if (oldest === undefined) break;
-			const [digest, entry] = oldest;
-			this.durablePackCache.delete(digest);
-			for (const [key, pair] of this.durablePackByPair) {
-				if (pair.planDigest === digest) this.durablePackByPair.delete(key);
+			this.durablePackCache.delete(oldest);
+			this.dropResidentDurablePacks(oldest);
+		}
+	}
+
+	private async rememberResidentDurablePack(
+		pairKey: string,
+		planDigest: string,
+		pack: DurablePack,
+	): Promise<void> {
+		const bytes = await this.durablePackFileBytes(pack.storagePath);
+		const previous = this.durablePackByPair.get(pairKey);
+		if (previous !== undefined) {
+			this.durablePackMemoryBytes -= previous.bytes;
+			this.durablePackByPair.delete(pairKey);
+		}
+		this.durablePackByPair.set(pairKey, { planDigest, pack, bytes });
+		this.durablePackMemoryBytes += bytes;
+		while (this.durablePackMemoryBytes > this.durablePackCacheMaxBytes) {
+			const oldest = this.durablePackByPair.keys().next().value as string | undefined;
+			if (oldest === undefined) break;
+			this.dropResidentDurablePack(oldest);
+		}
+	}
+
+	private dropResidentDurablePack(pairKey: string): void {
+		const cached = this.durablePackByPair.get(pairKey);
+		if (cached === undefined) return;
+		this.durablePackByPair.delete(pairKey);
+		this.durablePackMemoryBytes = Math.max(0, this.durablePackMemoryBytes - cached.bytes);
+	}
+
+	private dropResidentDurablePacks(planDigest: string): void {
+		for (const [pairKey, cached] of this.durablePackByPair) {
+			if (cached.planDigest === planDigest) this.dropResidentDurablePack(pairKey);
+		}
+	}
+
+	private async readIndexedDurablePack(
+		currentManifestId: ManifestId,
+		targetManifestId: ManifestId,
+		scopePaths: readonly string[],
+	): Promise<CachedDurablePair | undefined> {
+		const pairKey = durablePairKey(currentManifestId, targetManifestId, scopePaths);
+		const existing = this.durablePackByPair.get(pairKey);
+		if (existing !== undefined && this.durablePackCache.has(existing.planDigest)) return existing;
+		if (existing !== undefined) this.dropResidentDurablePack(pairKey);
+		const disk = await this.enqueueDurableIndex(async () => {
+			const result = await this.readDurableIndexFromDisk();
+			if (result.kind === "ok") this.durableIndex = result.index;
+			return result;
+		});
+		const entries = disk.kind === "ok"
+			? disk.index.entries
+			: disk.kind === "unavailable" ? this.durableIndex?.entries : undefined;
+		const entry = entries?.find((candidate) =>
+			durablePairKey(candidate.currentManifestId, candidate.targetManifestId, candidate.scopePaths) === pairKey);
+		if (entry === undefined || !isDigest(entry.planDigest) || !isDigest(entry.packChecksum)) return undefined;
+		try {
+			const cacheRoot = await this.store.durableCacheDirectory();
+			const journal = new MutationJournal(
+				join(cacheRoot, entry.planDigest, "mutations.jsonl"),
+				`cache-${entry.planDigest}`,
+			);
+			if (!await hasDurablePack(journal)) return undefined;
+			const pack = await loadDurablePack(journal, entry.planDigest, true);
+			if (pack.packChecksum !== entry.packChecksum || pack.planDigest !== entry.planDigest) return undefined;
+			return {
+				planDigest: entry.planDigest,
+				pack,
+				bytes: await this.durablePackFileBytes(pack.storagePath),
+			};
+		} catch {
+			return undefined;
+		}
+	}
+
+	private enqueueDurableIndex<T>(operation: () => Promise<T>): Promise<T> {
+		const run = this.durableIndexQueue.then(operation, operation);
+		this.durableIndexQueue = run.then(() => undefined, () => undefined);
+		return run;
+	}
+
+	private async acquireDurableIndexLease(): Promise<{ release(): Promise<void> } | undefined> {
+		try {
+			return await this.durableIndexLock.acquire(await this.durableIndexLockIdentity());
+		} catch {
+			return undefined;
+		}
+	}
+
+	private async durableIndexLockIdentity(): Promise<string> {
+		const cacheRoot = await this.store.durableCacheDirectory();
+		try {
+			return `durable-cache:${await realpath(cacheRoot)}`;
+		} catch {
+			return `durable-cache:${resolve(cacheRoot)}`;
+		}
+	}
+
+	private async readDurableIndexFromDisk(): Promise<DurableIndexDisk> {
+		try {
+			const cacheRoot = await this.store.durableCacheDirectory();
+			const raw = await readFile(join(cacheRoot, DURABLE_CACHE_INDEX_FILE), "utf8");
+			try {
+				return { kind: "ok", index: parseDurableCacheIndex(JSON.parse(raw)) };
+			} catch {
+				return { kind: "corrupt" };
 			}
-			await Promise.all([...new Set([entry.currentManifestId, entry.targetManifestId])].map(
-				(manifestId) => this.store.unpin(manifestId, entry.pinReason).catch(() => {}),
-			));
-			await rm(dirname(entry.path), { recursive: true, force: true }).catch(() => {});
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) return { kind: "missing" };
+			return { kind: "unavailable" };
 		}
 	}
 
+	private upsertDurableIndexEntry(entry: DurableCacheIndexEntry): void {
+		const index = this.durableIndex ?? { schemaVersion: 1, entries: [] };
+		const pairKey = durablePairKey(entry.currentManifestId, entry.targetManifestId, entry.scopePaths);
+		index.entries = index.entries.filter((candidate) =>
+			candidate.planDigest !== entry.planDigest &&
+			durablePairKey(candidate.currentManifestId, candidate.targetManifestId, candidate.scopePaths) !== pairKey);
+		index.entries.push(entry);
+		this.durableIndex = index;
+	}
+
+	private async persistDurableIndex(): Promise<void> {
+		if (this.durableIndex === undefined) return;
+		try {
+			const cacheRoot = await this.store.durableCacheDirectory();
+			await writeJsonAtomic(join(cacheRoot, DURABLE_CACHE_INDEX_FILE), {
+				schemaVersion: 1,
+				entries: this.durableIndex.entries,
+			});
+		} catch {
+			// 索引只是跨会话候选提示；写入失败不得让已经 pin 成功的 pack 准备失败。
+		}
+	}
+
+	private async evictPersistedDurablePacks(keepPlanDigest: string): Promise<void> {
+		while (this.durableIndex !== undefined && this.durableIndex.entries.length > PREPARED_PLAN_CACHE_LIMIT) {
+			const oldest = this.durableIndex.entries.find((entry) => entry.planDigest !== keepPlanDigest);
+			if (oldest === undefined) break;
+			await this.dropPersistedDurablePack(oldest.planDigest);
+		}
+	}
+
+	private async dropPersistedDurablePack(planDigest: string): Promise<void> {
+		const cached = this.durablePackCache.get(planDigest);
+		const indexed = this.durableIndex?.entries.find((entry) => entry.planDigest === planDigest);
+		this.durablePackCache.delete(planDigest);
+		this.dropResidentDurablePacks(planDigest);
+		if (this.durableIndex !== undefined) {
+			this.durableIndex.entries = this.durableIndex.entries.filter((entry) => entry.planDigest !== planDigest);
+		}
+		const pinReason = cached?.pinReason ?? `durable-cache:${planDigest}`;
+		const manifests = [...new Set([
+			...(cached === undefined ? [] : [cached.currentManifestId, cached.targetManifestId]),
+			...(indexed === undefined ? [] : [indexed.currentManifestId, indexed.targetManifestId]),
+		])];
+		await Promise.all(manifests.map((manifestId) => this.store.unpin(manifestId, pinReason).catch(() => {})));
+		try {
+			await rm(join(await this.store.durableCacheDirectory(), planDigest), { recursive: true, force: true });
+		} catch {
+			// 淘汰失败只影响缓存占用，不影响当前 restore 正确性。
+		}
+	}
+
+	private async durablePackFileBytes(path: string): Promise<number> {
+		try {
+			const stats = await lstat(path);
+			if (stats.isFile() && !stats.isSymbolicLink() && stats.size > 0) return Number(stats.size);
+		} catch {
+			// 文件可能在加载后被其他进程淘汰；不能把已加载的 pack 当作零字节常驻。
+		}
+		return this.durablePackCacheMaxBytes + 1;
+	}
+
 	private rememberPreparedPlan(
 		plan: RestorePlan,
 		currentPaths: ReadonlyMap<string, OwnedPath>,
@@ -390,8 +666,9 @@ export class RestoreEngine {
 		if (!hasValidPlanDigest(plan)) {
 			throw new Error("restore plan digest 与语义字段不匹配");
 		}
+		const cachedDurablePack = this.durablePackCache.get(plan.planDigest);
 		const pinsDeferred = effectiveOptions.deferDurability === true &&
-			this.durablePackCache.has(plan.planDigest);
+			cachedDurablePack?.pinsDeferred === true;
 		const recoveryReason = `restore:${plan.planDigest}`;
 		const attemptReason = `${recoveryReason}:attempt:${randomUUID()}`;
 		const pinned = [...new Set([plan.currentManifestId, target.manifestId])];
@@ -519,7 +796,13 @@ export class RestoreEngine {
 			return { code: "recovery_required", verifiedPaths: 0, totalPaths: currentPaths.size };
 		}
 		try {
-			await this.assertCompleteVisibleSubset(topologyBefore, [current, target], options.mutationJournal);
+			await this.assertCompleteVisibleSubset(
+				topologyBefore,
+				[current, target],
+				options.mutationJournal,
+				[],
+				this.completeCoverageOwnedPaths(plan.scopePaths, [currentPaths, targetPaths]),
+			);
 		} catch {
 			return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
 		}
@@ -588,6 +871,11 @@ export class RestoreEngine {
 			);
 			return result;
 		}
+		try {
+			await this.prefetchCompleteRestoreBlobs(plan, current, target, currentPaths, targetPaths);
+		} catch {
+			// 预取是性能优化；失败时继续走原有逐文件校验和可恢复 mutation 路径。
+		}
 		const preflight = await this.verifyKnownState(current, target, currentPaths, targetPaths, plan.scopePaths);
 		if (!preflight.ok) {
 			return {
@@ -625,7 +913,13 @@ export class RestoreEngine {
 
 			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
 			assertUnchangedTopology(topologyBefore, topologyAfter);
-			await this.assertCompleteVisibleSubset(topologyAfter, [target], options.mutationJournal);
+			await this.assertCompleteVisibleSubset(
+				topologyAfter,
+				[target],
+				options.mutationJournal,
+				[],
+				this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
+			);
 			const verification = await this.verifyTarget(
 				target,
 				currentPaths,
@@ -702,6 +996,7 @@ export class RestoreEngine {
 						? []
 						: [artifacts.source, ...(artifacts.target === null ? [] : [artifacts.target])];
 				}),
+				this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
 			);
 			const totalPaths = plan.deletePaths.length + plan.writePaths.length;
 			if ((await options.mutationJournal.load()).length !== 0) {
@@ -887,15 +1182,47 @@ export class RestoreEngine {
 		return result;
 	}
 
+	private completeCoverageOwnedPaths(
+		scopePaths: readonly string[] | undefined,
+		ownedPaths: readonly ReadonlyMap<string, OwnedPath>[],
+	): readonly ReadonlyMap<string, OwnedPath>[] | undefined {
+		return scopePaths === undefined ? ownedPaths : undefined;
+	}
+
+	private async prefetchCompleteRestoreBlobs(
+		plan: RestorePlan,
+		current: SnapshotManifest,
+		target: SnapshotManifest,
+		currentPaths: ReadonlyMap<string, OwnedPath>,
+		targetPaths: ReadonlyMap<string, OwnedPath>,
+	): Promise<void> {
+		if (plan.scopePaths !== undefined || !SnapshotStore.supportsValidatedBlobBatch(this.store)) return;
+		const requestsFor = (paths: ReadonlyMap<string, OwnedPath>, extraPaths: readonly string[] = []) => {
+			const requests = [];
+			const requested = new Set([...plan.writePaths, ...extraPaths]);
+			for (const path of requested) {
+				const owned = paths.get(path);
+				if (owned === undefined || owned.entry.kind !== "file" || owned.entry.blobId === null) continue;
+				requests.push({
+					rootPath: owned.root.relativeRoot,
+					blobId: owned.entry.blobId,
+					relativePath: owned.entry.relativePath,
+				});
+			}
+			return requests;
+		};
+		await Promise.all([
+			this.store.prefetchBlobs(current.manifestId, requestsFor(currentPaths, plan.deletePaths)),
+			this.store.prefetchBlobs(target.manifestId, requestsFor(targetPaths)),
+		]);
+	}
+
 	private assertCurrentTopology(
 		current: SnapshotManifest,
 		target: SnapshotManifest,
 		actual: RootTopology,
 	): void {
-		if (
-			actual.workspaceIdentity !== current.workspaceIdentity ||
-			actual.fingerprint !== current.topologyFingerprint
-		) {
+		if (!sameTopologyModuloIdentity(actual, current)) {
 			throw new Error("apply 前 workspace topology 与 current manifest 不一致");
 		}
 		const currentRoots = new Map(current.roots.map((root) => [root.relativeRoot, root]));
@@ -904,14 +1231,6 @@ export class RestoreEngine {
 			if (currentRoot !== undefined && targetRoot.state === "active" && currentRoot.state !== "active") {
 				throw new Error(`restore 不能把 inactive root 物化为 active：${targetRoot.relativeRoot}`);
 			}
-			if (
-				currentRoot !== undefined &&
-				targetRoot.state === "active" &&
-				(currentRoot.sourceIdentity !== targetRoot.sourceIdentity ||
-					currentRoot.privateRepositoryId !== targetRoot.privateRepositoryId)
-			) {
-				throw new Error(`restore boundary root identity 冲突：${targetRoot.relativeRoot}`);
-			}
 		}
 	}
 
@@ -926,12 +1245,13 @@ export class RestoreEngine {
 		const paths = [...new Set([...currentPaths.keys(), ...targetPaths.keys()])]
 			.filter((path) => scope === undefined || scope.has(path))
 			.sort(comparePaths);
-		let verifiedPaths = 0;
-		for (const path of paths) {
-			if (await this.pathIsShadowedByTarget(target.manifestId, path, targetPaths)) {
-				verifiedPaths += 1;
-				continue;
-			}
+		const results: Array<boolean | undefined> = new Array(paths.length);
+		let nextIndex = 0;
+		let stop = false;
+		let failure: unknown;
+		let failureIndex: number | undefined;
+		const verifyPath = async (path: string): Promise<boolean> => {
+			if (await this.pathIsShadowedByTarget(target.manifestId, path, targetPaths)) return true;
 			const currentPath = currentPaths.get(path);
 			const targetPath = targetPaths.get(path);
 			const matchesCurrent = currentPath !== undefined &&
@@ -941,7 +1261,37 @@ export class RestoreEngine {
 			const matchesAbsentSide = !matchesCurrent && !matchesTarget &&
 				(currentPath === undefined || targetPath === undefined) &&
 				await this.pathIsAbsent(path);
-			if (!matchesCurrent && !matchesTarget && !matchesAbsentSide) {
+			return matchesCurrent || matchesTarget || matchesAbsentSide;
+		};
+		const worker = async (): Promise<void> => {
+			while (!stop && nextIndex < paths.length) {
+				const index = nextIndex;
+				nextIndex += 1;
+				try {
+					const ok = await verifyPath(paths[index]!);
+					results[index] = ok;
+					if (!ok) stop = true;
+				} catch (error) {
+					if (failureIndex === undefined || index < failureIndex) {
+						failure = error;
+						failureIndex = index;
+					}
+					stop = true;
+				}
+			}
+		};
+		if (paths.length > 0) {
+			await Promise.all(Array.from(
+				{ length: Math.min(RESTORE_FILE_VERIFY_CONCURRENCY, paths.length) },
+				() => worker(),
+			));
+		}
+		let verifiedPaths = 0;
+		for (let index = 0; index < results.length; index += 1) {
+			const ok = results[index];
+			if (ok === false) return { ok: false, verifiedPaths, totalPaths: paths.length };
+			if (ok === undefined) {
+				if (failureIndex === index && failure !== undefined) throw failure;
 				return { ok: false, verifiedPaths, totalPaths: paths.length };
 			}
 			verifiedPaths += 1;
@@ -1168,7 +1518,13 @@ export class RestoreEngine {
 			await this.writePlannedPaths(current.manifestId, currentPaths, rollbackPlan.writePaths, context);
 			const topologyAfter = await this.discovery.discover(this.workspaceRoot);
 			assertUnchangedTopology(topologyBefore, topologyAfter);
-			await this.assertCompleteVisibleSubset(topologyAfter, [current], options.mutationJournal);
+			await this.assertCompleteVisibleSubset(
+				topologyAfter,
+				[current],
+				options.mutationJournal,
+				[],
+				this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+			);
 			const verification = await this.verifyTarget(
 				current,
 				targetPaths,
@@ -1205,7 +1561,13 @@ export class RestoreEngine {
 				try {
 					const topologyAfter = await this.discovery.discover(this.workspaceRoot);
 					assertUnchangedTopology(topologyBefore, topologyAfter);
-					await this.assertCompleteVisibleSubset(topologyAfter, [current], options.mutationJournal);
+					await this.assertCompleteVisibleSubset(
+						topologyAfter,
+						[current],
+						options.mutationJournal,
+						[],
+						this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
+					);
 					const verification = await this.verifyTarget(
 						current,
 						targetPaths,
@@ -1397,16 +1759,17 @@ export class RestoreEngine {
 		allowedManifests: readonly SnapshotManifest[],
 		mutationJournal?: MutationJournal,
 		extraExclusions: readonly string[] = [],
+		ownedPaths?: readonly (ReadonlyMap<string, OwnedPath> | undefined)[],
 	): Promise<void> {
 		if (allowedManifests.some((manifest) => manifest.coverage !== "complete")) {
 			return;
 		}
 		const allowedPaths = new Set<string>();
-		for (const manifest of allowedManifests) {
+		for (const [index, manifest] of allowedManifests.entries()) {
 			for (const path of ignoredWorkspacePaths(manifest)) {
 				allowedPaths.add(path);
 			}
-			const paths = await this.readOwnedPaths(manifest);
+			const paths = ownedPaths?.[index] ?? await this.readOwnedPaths(manifest);
 			for (const [path, owned] of paths) {
 				if (owned.entry.kind !== "directory") {
 					allowedPaths.add(path);
@@ -1435,23 +1798,18 @@ export class RestoreEngine {
 		deletePaths: readonly string[],
 		scopePaths?: readonly string[],
 	): Promise<{ verifiedPaths: number; totalPaths: number; pathFingerprints: string[] }> {
-		const pathFingerprints: string[] = [];
 		const scope = scopePaths === undefined ? undefined : new Set(scopePaths);
-		for (const [path, owned] of targetPaths) {
-			if (scope !== undefined && !scope.has(path)) continue;
-			pathFingerprints.push(await this.verifyEntry(target.manifestId, owned));
-		}
-		let verifiedPaths = pathFingerprints.length;
-		let totalPaths = pathFingerprints.length;
-		for (const path of deletePaths) {
-			if (
-				targetPaths.has(path) ||
-				currentPaths.get(path)?.entry.kind === "directory" ||
-				hasNonDirectoryAncestor(path, targetPaths)
-			) {
-				continue;
-			}
-			totalPaths += 1;
+		const scopedTargets = [...targetPaths].filter(([path]) => scope === undefined || scope.has(path));
+		const pathFingerprints = await mapConcurrentOrdered(
+			scopedTargets,
+			RESTORE_FILE_VERIFY_CONCURRENCY,
+			([, owned]) => this.verifyEntry(target.manifestId, owned),
+		);
+		const remainingDeletes = deletePaths.filter((path) =>
+			!targetPaths.has(path) &&
+			currentPaths.get(path)?.entry.kind !== "directory" &&
+			!hasNonDirectoryAncestor(path, targetPaths));
+		await mapConcurrentOrdered(remainingDeletes, RESTORE_FILE_VERIFY_CONCURRENCY, async (path) => {
 			try {
 				await lstat(this.absolutePath(path));
 				throw new Error(`目标应删除的路径仍然存在：${path}`);
@@ -1460,11 +1818,10 @@ export class RestoreEngine {
 					throw error;
 				}
 			}
-			verifiedPaths += 1;
-		}
+		});
 		return {
-			verifiedPaths,
-			totalPaths,
+			verifiedPaths: pathFingerprints.length + remainingDeletes.length,
+			totalPaths: pathFingerprints.length + remainingDeletes.length,
 			pathFingerprints,
 		};
 	}
@@ -1652,6 +2009,28 @@ function sameEntry(left: RestorePath, right: RestorePath): boolean {
 		left.linkText === right.linkText;
 }
 
+// sourceIdentity/privateRepositoryId 会随 git remote 配置漂移（例如后来补充 remote origin），
+// 它们是仓库元数据而非工作区内容；restore 的内容安全由逐文件校验
+// （verifyKnownState、assertCompleteVisibleSubset、verifyTarget）保证。
+// 因此这里只比较结构性拓扑字段：root 集合、parentRoot、state 与 gitlinkOid。
+function sameTopologyModuloIdentity(actual: RootTopology, expected: SnapshotManifest): boolean {
+	if (actual.workspaceIdentity !== expected.workspaceIdentity) return false;
+	const expectedRoots = new Map(expected.roots.map((root) => [root.relativeRoot, root]));
+	if (actual.roots.length !== expectedRoots.size) return false;
+	for (const root of actual.roots) {
+		const expectedRoot = expectedRoots.get(root.relativeRoot);
+		if (
+			expectedRoot === undefined ||
+			expectedRoot.parentRoot !== root.parentRoot ||
+			expectedRoot.state !== root.state ||
+			(expectedRoot.gitlinkOid ?? null) !== (root.gitlinkOid ?? null)
+		) {
+			return false;
+		}
+	}
+	return true;
+}
+
 function assertCompatibleManifests(
 	current: SnapshotManifest,
 	target: SnapshotManifest,
@@ -1903,6 +2282,40 @@ function durablePairKey(
 	return `${currentManifestId}\0${targetManifestId}\0${checksum(canonicalJson([...scopePaths].sort(comparePaths)))}`;
 }
 
+function isDigest(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+function parseDurableCacheIndex(value: unknown): DurableCacheIndex {
+	if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.entries)) {
+		throw new Error("durable cache index 无效");
+	}
+	const entries: DurableCacheIndexEntry[] = [];
+	for (const entry of value.entries) {
+		if (
+			!isRecord(entry) ||
+			!isDigest(entry.currentManifestId) ||
+			!isDigest(entry.targetManifestId) ||
+			!isDigest(entry.planDigest) ||
+			!isDigest(entry.packChecksum) ||
+			!Array.isArray(entry.scopePaths) ||
+			entry.scopePaths.some((path) => typeof path !== "string")
+		) continue;
+		entries.push({
+			currentManifestId: entry.currentManifestId as ManifestId,
+			targetManifestId: entry.targetManifestId as ManifestId,
+			scopePaths: entry.scopePaths.filter((path): path is string => typeof path === "string"),
+			planDigest: entry.planDigest,
+			packChecksum: entry.packChecksum,
+		});
+	}
+	return { schemaVersion: 1, entries };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }

package/src/root-discovery.ts

@@ -1,4 +1,4 @@
-import { lstat, readdir, realpath } from "node:fs/promises";
+import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { checksum, topologyFingerprint } from "./encoding.ts";
@@ -6,6 +6,7 @@ import { GitRunner } from "./git-runner.ts";
 import type { DiscoveryRoot } from "./model.ts";
 
 const DIRECTORY_SCAN_CONCURRENCY = 16;
+const GIT_POINTER_MAX_BYTES = 4096;
 
 interface RepositoryInfo {
 	readonly absoluteRoot: string;
@@ -17,6 +18,7 @@ interface RepositoryInfo {
 type RepositoryInspection =
 	| { readonly kind: "active"; readonly repository: RepositoryInfo }
 	| { readonly kind: "broken"; readonly absoluteRoot: string }
+	| { readonly kind: "stale"; readonly absoluteRoot: string }
 	| { readonly kind: "absent" };
 
 interface DiscoveredRoot {
@@ -68,7 +70,7 @@ export class RootDiscovery {
 				outerRepository.repository.absoluteRoot,
 				this.activeRoot(workspaceIdentity, outerRepository.repository),
 			);
-		} else if (outerRepository.kind === "broken") {
+		} else if (outerRepository.kind === "broken" || outerRepository.kind === "stale") {
 			activeRoots.set(outerRepository.absoluteRoot, brokenRoot(workspaceIdentity, outerRepository.absoluteRoot));
 		} else {
 			activeRoots.set(workspaceIdentity, syntheticRoot(workspaceIdentity));
@@ -117,6 +119,8 @@ export class RootDiscovery {
 				);
 			} else if (inspection.kind === "broken") {
 				activeRoots.set(inspection.absoluteRoot, brokenRoot(workspaceIdentity, inspection.absoluteRoot));
+			} else if (inspection.kind === "stale") {
+				activeRoots.set(inspection.absoluteRoot, staleWorktreeRoot(workspaceIdentity, inspection.absoluteRoot));
 			}
 			if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		}
@@ -145,6 +149,9 @@ export class RootDiscovery {
 		if (marker === "invalid") {
 			return { kind: "broken", absoluteRoot };
 		}
+		if (await deadWorktreePointer(absoluteRoot)) {
+			return { kind: "stale", absoluteRoot };
+		}
 
 		const details = await this.gitOutput([
 			"-C",
@@ -274,6 +281,46 @@ function brokenRoot(workspaceIdentity: string, absoluteRoot: string): Discovered
 	};
 }
 
+// git worktree 的 .git 文件是 "gitdir: <path>" 指针；项目从其他机器/位置搬移后，
+// 指针常指向本机不存在的 gitdir（例如虚拟机共享目录的绝对路径）。这种可证明失效的
+// 指针不再代表可用仓库，按未初始化根处理：内容不进入快照，也不会被 restore 触碰。
+async function deadWorktreePointer(absoluteRoot: string): Promise<boolean> {
+	const pointerPath = join(absoluteRoot, ".git");
+	let content: string;
+	try {
+		const marker = await lstat(pointerPath);
+		if (!marker.isFile()) return false;
+		content = await readFile(pointerPath, "utf8");
+	} catch {
+		return false;
+	}
+	if (content.length > GIT_POINTER_MAX_BYTES) return false;
+	const firstLine = content.split("\n", 1)[0] ?? "";
+	const match = /^gitdir: (.+)$/.exec(firstLine.trimEnd());
+	if (match === null) return false;
+	const gitDirectory = isAbsolute(match[1]) ? resolve(match[1]) : resolve(absoluteRoot, match[1]);
+	try {
+		await stat(gitDirectory);
+		return false;
+	} catch (error) {
+		return hasErrorCode(error, "ENOENT");
+	}
+}
+
+function staleWorktreeRoot(workspaceIdentity: string, absoluteRoot: string): DiscoveredRoot {
+	const relativeRoot = workspaceRelativePath(workspaceIdentity, absoluteRoot);
+	const sourceIdentity = `stale-worktree:${absoluteRoot}`;
+	return {
+		absoluteRoot,
+		relativeRoot,
+		gitBacked: true,
+		state: "uninitialized",
+		sourceIdentity,
+		privateRepositoryId: checksum(sourceIdentity),
+		treeId: null,
+	};
+}
+
 function buildRoots(discovered: readonly DiscoveredRoot[]): DiscoveryRoot[] {
 	const unique = new Map<string, DiscoveredRoot>();
 	for (const root of discovered) {

package/src/snapshot-store.ts

@@ -210,6 +210,8 @@ export class SnapshotStore {
 	private readonly blobCache = new Map<string, CachedBlob>();
 	private readonly visibleLeafCache = new Map<string, Map<string, CachedVisibleLeaf>>();
 	private readonly leafCacheDirectoriesLoaded = new Set<string>();
+	private readonly configuredPrivateRepositories = new Set<string>();
+	private readonly leafCacheDirtyDirectories = new Set<string>();
 	private blobCacheBytes = 0;
 
 	constructor(options: SnapshotStoreOptions = {}) {
@@ -741,6 +743,61 @@ export class SnapshotStore {
 		return (await this.readBlobOperation(id, [{ rootPath, blobId, relativePath }], false))[0]!;
 	}
 
+	/** 按 root 批量预取普通文件 blob；membership 与 manifest 校验仍走只读路径。 */
+	async prefetchBlobs(id: ManifestId, requests: readonly SnapshotBlobRequest[]): Promise<void> {
+		if (requests.length === 0) return;
+		for (const request of requests) {
+			relativeSafePath("/", request.rootPath);
+			if (!isObjectId(request.blobId)) {
+				throw new SnapshotStoreError("object_missing", "blob ID 无效");
+			}
+			if (request.relativePath === undefined) {
+				throw new SnapshotStoreError("object_missing", "blob 预取必须提供 root-relative path");
+			}
+		}
+		const manifestPath = await this.findManifestPath(id);
+		const manifest = await this.loadManifest(id);
+		const roots = new Map(manifest.roots.map((root) => [root.relativeRoot, root]));
+		const storeDirectory = dirname(dirname(manifestPath));
+		const byRoot = new Map<string, SnapshotBlobRequest[]>();
+		for (const request of requests) {
+			const grouped = byRoot.get(request.rootPath) ?? [];
+			grouped.push(request);
+			byRoot.set(request.rootPath, grouped);
+		}
+		try {
+			const grouped = new Map<string, Map<string, CapturedTreeEntry>>();
+			for (const [rootPath, rootRequests] of byRoot) {
+				const root = roots.get(rootPath);
+				if (root === undefined) {
+					throw new SnapshotStoreError("root_not_found", "manifest 中不存在指定 root");
+				}
+				if (root.state !== "active" || root.treeId === null) {
+					throw new SnapshotStoreError("object_missing", "指定 root 没有可读取的 tree");
+				}
+				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
+				const entries = await this.readTreeEntries(gitDirectory, root.treeId);
+				const byPath = new Map(entries.map((entry) => [entry.relativePath, entry]));
+				const unique = grouped.get(gitDirectory) ?? new Map<string, CapturedTreeEntry>();
+				for (const request of rootRequests) {
+					const safeRelativePath = relativeSafePath("/", request.relativePath!);
+					const entry = byPath.get(safeRelativePath);
+					if (entry === undefined || entry.objectId !== request.blobId) {
+						throw new SnapshotStoreError("object_missing", "blob 不属于指定 root tree path");
+					}
+					unique.set(entry.objectId, entry);
+				}
+				grouped.set(gitDirectory, unique);
+			}
+			for (const [gitDirectory, unique] of grouped) {
+				await this.preloadBlobBytes(gitDirectory, [...unique.values()]);
+			}
+		} catch (error) {
+			if (error instanceof SnapshotStoreError) throw error;
+			throw new SnapshotStoreError("object_missing", "blob 无法预取", { cause: error });
+		}
+	}
+
 	private readBlobsValidated(
 		id: ManifestId,
 		requests: readonly SnapshotBlobRequest[],
@@ -1155,9 +1212,10 @@ export class SnapshotStore {
 
 	private rememberVisibleLeaves(update: VisibleLeafCacheUpdate): void {
 		const { gitDirectory, staged, inclusions } = update;
+		const previous = this.visibleLeafCache.get(gitDirectory);
 		const cache = inclusions !== null && inclusions.length === 0
 			? new Map<string, CachedVisibleLeaf>()
-			: new Map(this.visibleLeafCache.get(gitDirectory));
+			: new Map(previous);
 		if (inclusions !== null && inclusions.length > 0) {
 			for (const relativePath of cache.keys()) {
 				if (inclusions.some((inclusion) => isPathAtOrBelow(inclusion, relativePath))) {
@@ -1174,6 +1232,9 @@ export class SnapshotStore {
 			}
 			cache.set(leaf.relativePath, { ...leaf, objectId, verifiedAtNs: staged.verifiedAtNs });
 		}
+		if (!samePersistedLeafCache(previous, cache)) {
+			this.leafCacheDirtyDirectories.add(storeDirectoryForGitDirectory(gitDirectory));
+		}
 		this.visibleLeafCache.set(gitDirectory, cache);
 	}
 
@@ -1210,6 +1271,7 @@ export class SnapshotStore {
 
 	/** 把当前 storeDirectory 范围内的叶子缓存原子写入磁盘（best-effort）。 */
 	private async persistLeafCache(storeDirectory: string): Promise<void> {
+		if (!this.leafCacheDirtyDirectories.has(storeDirectory)) return;
 		const prefix = `${storeDirectory}${sep}`;
 		const entries: Record<string, Record<string, PersistedLeafCacheEntry>> = {};
 		for (const [gitDirectory, cache] of this.visibleLeafCache) {
@@ -1235,6 +1297,7 @@ export class SnapshotStore {
 				Buffer.from(JSON.stringify({ schemaVersion: 1, entries }), "utf8"),
 				0o600,
 			);
+			this.leafCacheDirtyDirectories.delete(storeDirectory);
 		} catch {
 			// 缓存写入是 best-effort：失败只影响下次性能，不影响正确性。
 		}
@@ -1428,9 +1491,11 @@ export class SnapshotStore {
 	}
 
 	private async configurePrivateRepository(gitDirectory: string): Promise<void> {
+		if (this.configuredPrivateRepositories.has(gitDirectory)) return;
 		const environment = cleanGitEnvironment();
 		await this.runGit(["--git-dir", gitDirectory, "config", "gc.auto", "0"], { env: environment });
 		await this.runGit(["--git-dir", gitDirectory, "config", "maintenance.auto", "false"], { env: environment });
+		this.configuredPrivateRepositories.add(gitDirectory);
 	}
 
 	private async assertNoAlternates(gitDirectory: string): Promise<void> {
@@ -1982,6 +2047,35 @@ function blobCacheKey(gitDirectory: string, objectId: string): string {
 	return `${gitDirectory}\0${objectId}`;
 }
 
+function storeDirectoryForGitDirectory(gitDirectory: string): string {
+	return dirname(dirname(dirname(gitDirectory)));
+}
+
+function samePersistedLeafCache(
+	left: ReadonlyMap<string, CachedVisibleLeaf> | undefined,
+	right: ReadonlyMap<string, CachedVisibleLeaf>,
+): boolean {
+	if (left === undefined) return right.size === 0;
+	if (left.size !== right.size) return false;
+	for (const [path, entry] of right) {
+		const existing = left.get(path);
+		const existingTrusted = existing !== undefined &&
+			existing.verifiedAtNs > existing.changedAtNs + RACY_CLEAN_WINDOW_NS;
+		const entryTrusted = entry.verifiedAtNs > entry.changedAtNs + RACY_CLEAN_WINDOW_NS;
+		if (
+			existing === undefined ||
+			existing.kind !== entry.kind ||
+			existing.mode !== entry.mode ||
+			existing.fingerprint !== entry.fingerprint ||
+			existing.cacheable !== entry.cacheable ||
+			existing.objectId !== entry.objectId ||
+			existing.changedAtNs !== entry.changedAtNs ||
+			existingTrusted !== entryTrusted
+		) return false;
+	}
+	return true;
+}
+
 function blobReadBatches(entries: readonly CapturedTreeEntry[]): CapturedTreeEntry[][] {
 	const result: CapturedTreeEntry[][] = [];
 	let batch: CapturedTreeEntry[] = [];