@davideasden/pi-undo 0.2.18 → 0.2.21

package/README.md

@@ -68,6 +68,16 @@ pi -e /absolute/path/to/pi-undo/extensions/pi-undo.ts
 
 Work with Pi normally. `pi-undo` automatically records a boundary after each completed agent run.
 
+### Recovery
+
+If an operation fails mid-flight (for example, the process is killed while files are being restored), pi-undo locks undo history and reports `recovery_required`. Run:
+
+```text
+/undo-recover
+```
+
+to re-run recovery in place: it re-verifies pending journals, settles provably-safe transactions, rebuilds the undo/redo stacks, and refreshes the status line — the in-process equivalent of restarting the session window. If the workspace is still locked afterwards, the blocking transaction belongs to another session in the same workspace; open (or restart) that session and run `/undo-recover` there.
+
 ### Diff
 
 ```text

package/extensions/pi-undo.ts

@@ -38,6 +38,13 @@ interface DeferredPrompt {
 
 export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi: ExtensionAPI) => void {
 	return (pi) => {
+		if (process.env.PI_SUBAGENT_CHILD === "1") {
+			// pi-subagents 的 runner 子进程会加载 ambient extensions，并用该环境变量
+			// 标记自身（其父扩展据此保持惰性）。pi-undo 只在主会话生效：避免子进程
+			// 重复 capture 争用 workspace lock。子代理的工作区变更由父会话的 run 级
+			// before/after 快照覆盖，撤回语义不受影响。
+			return;
+		}
 		let runtime: PiUndoRuntime | undefined;
 		let runtimeContext: ExtensionContext | undefined;
 		let generation = 0;
@@ -47,6 +54,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		let activeCommands = new Set<symbol>();
 		let activeAction: "undo" | "redo" | undefined;
 		let captureFailureNotified = false;
+		let recoveryHintNotified = false;
 
 		const initialize = async (context: ExtensionContext): Promise<void> => {
 			const currentGeneration = ++generation;
@@ -57,6 +65,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			activeCommands = new Set<symbol>();
 			activeAction = undefined;
 			captureFailureNotified = false;
+			recoveryHintNotified = false;
 			try {
 				const next = await runtimeFactory(context, pi);
 				if (currentGeneration !== generation) return;
@@ -69,8 +78,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;
@@ -170,6 +177,10 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 				};
 			}
 			active.reporter.result(result, performance.now() - commandStarted);
+			if (result.code === "recovery_required" && !recoveryHintNotified) {
+				recoveryHintNotified = true;
+				context.ui.notify("pi-undo: run /undo-recover to retry recovery", "info");
+			}
 			const hasDeferredPrompt = deferredPrompts.length > 0 || replaying !== undefined;
 			if (
 				action === "undo" && result.code === "ok" && result.refillPrompt !== undefined &&
@@ -229,6 +240,28 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			description: "Review files changed by an Agent run (latest, or /diff N)",
 			handler: async (args: string, context: ExtensionCommandContext) => runDiff(args, context),
 		});
+		pi.registerCommand("undo-recover", {
+			description: "Re-run pi-undo recovery and refresh undo history",
+			handler: async (_args: string, context: ExtensionCommandContext) => {
+				if (activeCommands.size > 0) {
+					context.ui.notify("pi-undo: wait for the current operation to finish before recovering", "warning");
+					return;
+				}
+				// 原地重建 runtime：等价于重启窗口，复用启动 recovery 语义。
+				await initialize(context);
+				const active = runtime;
+				if (active === undefined) return;
+				const history = active.controller.history();
+				if (history.locked) {
+					context.ui.notify(
+						`pi-undo: still locked (${active.controller.recoveryReason?.() ?? "pending journal"}); resolve the blocking session, then run /undo-recover again`,
+						"warning",
+					);
+					return;
+				}
+				context.ui.notify(`pi-undo: recovery complete (undo:${history.undoCount} redo:${history.redoCount})`, "info");
+			},
+		});
 
 		pi.on("session_start", async (_event: unknown, context: ExtensionContext) => initialize(context));
 		pi.on("input", async (event: InputEvent, context: ExtensionContext) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.18",
+	"version": "0.2.21",
 	"description": "Persistent workspace undo and redo for Pi",
 	"license": "MIT",
 	"type": "module",

package/src/controller.ts

@@ -401,7 +401,9 @@ export class UndoControllerImpl implements UndoController {
 			profiler === undefined ? operation() : profiler.measure(phase, operation);
 		try {
 			// settled 复用 run 开始时的 before；helper 在缺少 captureBaseline 时回退完整 capture。
-			const after = await measure("settled.capture", () => this.captureBaselineWithWorkspaceLock(staged.before));
+			// 撕裂捕获（并发写撞上断言窗口）是暂态的：短暂退避后重试一次，成功则不清空历史。
+			const after = await measure("settled.capture", () =>
+				this.captureSettledBaselineWithRetry(staged.before));
 			const changedPaths = await measure("settled.changedPaths", () =>
 				this.dependencies.changedPaths(staged.before, after));
 			if (changedPaths.length > 0 && this.dependencies.prepareDurableRestore !== undefined) {
@@ -830,6 +832,21 @@ export class UndoControllerImpl implements UndoController {
 		}
 	}
 
+	/**
+	 * settled capture 对暂态失败重试一次：async subagent 等并发写入者可能撞上撕裂断言
+	 * （捕获期间叶子变化）或短暂持有 workspace lock。settled 失败会清空整个 undo 历史，
+	 * 不能因一次暂态冲突就放弃；持续失败仍由调用方走原有 historyPaused 路径。
+	 */
+	private async captureSettledBaselineWithRetry(baseline: SnapshotManifest): Promise<SnapshotManifest> {
+		try {
+			return await this.captureBaselineWithWorkspaceLock(baseline);
+		} catch (error) {
+			if (!isTransientCaptureFailure(error)) throw error;
+			await sleep(250);
+			return await this.captureBaselineWithWorkspaceLock(baseline);
+		}
+	}
+
 	private async compensate(
 		descriptor: OperationDescriptor,
 		rollback: SnapshotManifest,
@@ -1012,3 +1029,20 @@ function noop(): OperationResult {
 function truncateReason(reason: string): string {
 	return reason.replace(/[\u0000-\u001F\u007F]+/g, " ").trim().slice(0, 120);
 }
+
+/**
+ * 判断 capture 失败是否为并发写入者导致的暂态失败：撕裂断言
+ * （SnapshotStoreError capture_failed，如“捕获期间工作区叶子已变化”）与
+ * workspace lock 超时（WorkspaceLockError lock_timeout）。用 name/code 鸭子类型
+ * 判断以保持 controller 对存储实现的解耦。
+ */
+function isTransientCaptureFailure(error: unknown): boolean {
+	if (typeof error !== "object" || error === null) return false;
+	const { name, code } = error as { name?: unknown; code?: unknown };
+	return (name === "SnapshotStoreError" && code === "capture_failed") ||
+		(name === "WorkspaceLockError" && code === "lock_timeout");
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

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,8 +36,11 @@ 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;
@@ -74,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 {
@@ -95,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;
@@ -115,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);
@@ -133,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<{
@@ -226,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({
@@ -241,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;
 		}
@@ -287,7 +358,7 @@ export class RestoreEngine {
 			throw error;
 		}
 		await this.rememberDurablePack(
-			plan,
+			plan.planDigest,
 			current,
 			target,
 			scopePaths,
@@ -298,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;
+			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;
-			const [digest, entry] = oldest;
-			this.durablePackCache.delete(digest);
-			for (const [key, pair] of this.durablePackByPair) {
-				if (pair.planDigest === digest) this.durablePackByPair.delete(key);
+			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>,
@@ -391,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])];
@@ -946,10 +1222,7 @@ export class RestoreEngine {
 		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]));
@@ -958,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}`);
-			}
 		}
 	}
 
@@ -1744,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,
@@ -1995,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) {