@davideasden/pi-undo 0.2.11 → 0.2.15

package/README.md

@@ -19,7 +19,7 @@ Each completed agent run creates a checkpoint that captures both the Pi session
 
 ## Requirements
 
-- Pi `0.80.10` or a compatible release.
+- Pi `0.80.10` 或更高版本（已在 0.84.4 上验证）。
 - Node.js `22.19.0` or later.
 - Git available on `PATH` (used internally for content-addressed snapshots).
 

package/extensions/pi-undo.ts

@@ -46,6 +46,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		let acceptedReplay: DeferredPrompt | undefined;
 		let activeCommands = new Set<symbol>();
 		let activeAction: "undo" | "redo" | undefined;
+		let captureFailureNotified = false;
 
 		const initialize = async (context: ExtensionContext): Promise<void> => {
 			const currentGeneration = ++generation;
@@ -55,6 +56,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			acceptedReplay = undefined;
 			activeCommands = new Set<symbol>();
 			activeAction = undefined;
+			captureFailureNotified = false;
 			try {
 				const next = await runtimeFactory(context, pi);
 				if (currentGeneration !== generation) return;
@@ -63,6 +65,8 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 				const history = next.controller.history();
 				if (history.locked) next.reporter.setRecoveryRequired("pending journal", next.recovery);
 				else next.reporter.setReady(history.undoCount, history.redoCount);
+				// 后台预热快照缓存，把新会话首次冷 capture 移出第一条 prompt 的关键路径。
+				next.controller.warmUp();
 			} catch (error) {
 				if (currentGeneration !== generation) return;
 				runtime = undefined;
@@ -213,7 +217,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		pi.on("session_start", async (_event: unknown, context: ExtensionContext) => initialize(context));
 		pi.on("input", async (event: InputEvent, context: ExtensionContext) => {
 			const active = runtime;
-			if (active === undefined) return { action: "handled" as const };
+			if (active === undefined) return { action: "continue" as const };
 			const result = await active.controller.prepareInput(event.text, {
 				streaming: event.streamingBehavior !== undefined,
 			});
@@ -250,6 +254,14 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 					}
 				}
 			}
+			if (result.action === "continue" && 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",
+				);
+			}
 			return result;
 		});
 		pi.on("before_agent_start", async () => {
@@ -286,11 +298,16 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			return result;
 		});
 		pi.on("session_tree", async (event: PiSessionTreeEvent) => {
-			if (runtime?.isInternalNavigation?.()) return;
-			await runtime?.controller.afterTree({
+			const active = runtime;
+			if (active?.isInternalNavigation?.()) return;
+			const treeGeneration = generation;
+			await active?.controller.afterTree({
 				newLeafId: event.newLeafId,
 				navigationTargetLeafId: event.summaryEntry?.parentId ?? event.newLeafId,
 			});
+			if (active !== undefined && runtime === active && generation === treeGeneration) {
+				resumeDeferredPrompts(active, treeGeneration, "session state ambiguous");
+			}
 		});
 		pi.on("session_shutdown", async () => {
 			generation += 1;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.11",
+	"version": "0.2.15",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [
@@ -45,14 +45,15 @@
 		"pack:dry-run": "npm pack --dry-run"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "^0.80.10",
+		"@earendil-works/pi-coding-agent": ">=0.80.10",
 		"@earendil-works/pi-tui": "*"
 	},
 	"dependencies": {
 		"proper-lockfile": "4.1.2"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@earendil-works/pi-coding-agent": "0.84.4",
+		"@earendil-works/pi-tui": "0.84.4",
 		"@types/node": "24.12.4",
 		"@types/proper-lockfile": "4.1.4",
 		"typescript": "5.9.3",

package/src/atomic-fs.ts

@@ -86,10 +86,28 @@ export async function fsyncFile(file: string): Promise<void> {
 	}
 }
 
+/** 不支持目录 fsync 的平台/文件系统（Windows/NTFS、网络盘、exFAT、FUSE 等）返回的 errno。 */
+const TOLERATED_DIR_FSYNC_CODES = new Set(["EPERM", "EINVAL", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+
+/** 目录 fsync 失败是否因平台/文件系统不支持而可以安全降级跳过。 */
+export function isToleratedDirFsyncError(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error &&
+		typeof (error as { code?: unknown }).code === "string" &&
+		TOLERATED_DIR_FSYNC_CODES.has((error as { code: string }).code);
+}
+
 export async function fsyncDirectory(directory: string): Promise<void> {
+	if (process.platform === "win32") {
+		// Windows 对目录句柄调用 fsync 必然返回 EPERM；rename 的持久性由文件系统自身保证。
+		return;
+	}
 	const handle = await open(directory, "r");
 	try {
 		await handle.sync();
+	} catch (error) {
+		// 目录 fsync 只是崩溃持久性的 best-effort 强化，文件内容的 fsync 不受影响：
+		// 不支持目录 fsync 的文件系统降级跳过，其余错误照常传播。
+		if (!isToleratedDirFsyncError(error)) throw error;
 	} finally {
 		await handle.close();
 	}

package/src/controller.ts

@@ -145,6 +145,12 @@ export interface UndoController {
 	cancelTree?(): Promise<void>;
 	recover(): Promise<void>;
 	history(): HistoryState;
+	/** 后台预热快照缓存：立即返回，失败静默；后续 capture 会先等预热完成。 */
+	warmUp(): void;
+	/** 最近一次输入前快照是否失败（此时本次 run 不可 undo，但输入不受影响）。 */
+	captureFailed(): boolean;
+	/** 最近一次输入前快照失败的原因（截断后的错误消息）；成功时为 undefined。 */
+	captureFailureReason(): string | undefined;
 }
 
 interface StagedRun {
@@ -192,6 +198,9 @@ export class UndoControllerImpl implements UndoController {
 	private operationProfiler: OperationProfiler | undefined;
 	private promptDeferralInFlight = false;
 	private lastSafetyManifestId: ManifestId | null = null;
+	private lastCaptureFailed = false;
+	private lastCaptureFailureMessage: string | undefined;
+	private warmUpInFlight: Promise<void> | undefined;
 
 	constructor(dependencies: ControllerDependencies, initialState: ControllerInitialState = {}) {
 		this.dependencies = dependencies;
@@ -205,22 +214,46 @@ export class UndoControllerImpl implements UndoController {
 		return { undoCount: this.undoStack.length, redoCount: this.redoStack.length, locked: this.locked };
 	}
 
+	captureFailed(): boolean {
+		return this.lastCaptureFailed;
+	}
+
+	warmUp(): void {
+		if (this.locked || this.warmUpInFlight !== undefined) return;
+		this.warmUpInFlight = (async () => {
+			try {
+				await this.captureWithWorkspaceLock();
+			} catch {
+				// 预热是 best-effort：失败静默，正式 capture 会再次尝试并上报。
+			}
+		})();
+	}
+
+	captureFailureReason(): string | undefined {
+		return this.lastCaptureFailed ? this.lastCaptureFailureMessage : undefined;
+	}
+
 	listCheckpoints(): readonly CheckpointRecord[] {
 		return [...this.undoStack];
 	}
 
 	async prepareInput(text: string, context: InputContext): Promise<InputEventResult> {
 		if (this.promptDeferralInFlight) return { action: "defer" };
-		if (this.locked || this.operationInFlight) return { action: "handled" };
+		if (this.locked) return { action: "continue" };
+		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() };
 			return { action: "continue" };
-		} catch {
-			// 无法证明输入前状态时保留编辑器输入；本轮尚未开始，可由用户直接重试。
-			return { action: "handled" };
+		} catch (error) {
+			// 无法证明输入前状态：放弃记录本次历史，但绝不吞掉用户输入。
+			this.lastCaptureFailed = true;
+			this.lastCaptureFailureMessage = truncateReason(error instanceof Error ? error.message : String(error));
+			return { action: "continue" };
 		}
 	}
 
@@ -658,6 +691,10 @@ export class UndoControllerImpl implements UndoController {
 	}
 
 	private async captureWithWorkspaceLock(): Promise<SnapshotManifest> {
+		// 预热可能仍持有 workspace lock：先等它完成再 acquire，避免排队超时；
+		// 此时进程内缓存已暖，本次 capture 只需指纹校验。
+		const warmUp = this.warmUpInFlight;
+		if (warmUp !== undefined) await warmUp;
 		const lease = await this.dependencies.acquireWorkspaceLock();
 		try {
 			return await this.dependencies.capture();
@@ -844,3 +881,7 @@ class OperationProfiler {
 function noop(): OperationResult {
 	return { code: "noop", changedFiles: 0 };
 }
+
+function truncateReason(reason: string): string {
+	return reason.replace(/[\u0000-\u001F\u007F]+/g, " ").trim().slice(0, 120);
+}

package/src/restore-engine.ts

@@ -1661,7 +1661,10 @@ function assertCompatibleManifests(
 		throw new Error("restore manifest 不属于同一 workspace");
 	}
 	if (current.roots.some((root) => root.state === "broken") || target.roots.some((root) => root.state === "broken")) {
-		throw new Error("broken root 不能用于 restore");
+		const brokenRoots = [...current.roots, ...target.roots]
+			.filter((root, index, all) => root.state === "broken" && all.findIndex((candidate) => candidate.relativeRoot === root.relativeRoot) === index)
+			.map((root) => root.relativeRoot);
+		throw new Error(`broken root 不能用于 restore: ${brokenRoots.join(", ")}`);
 	}
 	const scopedCoverage = scope === undefined
 		? undefined

package/src/root-discovery.ts

@@ -333,10 +333,35 @@ async function isSafeDirectory(directory: string, workspaceIdentity: string): Pr
 async function gitlinkState(absolutePath: string): Promise<DiscoveryRoot["state"]> {
 	try {
 		await lstat(absolutePath);
-		return "broken";
 	} catch {
 		return "uninitialized";
 	}
+	// git worktree / 部分 checkout 会为 gitlink 留下空目录骨架（可能含指向共享依赖的 symlink）；
+	// 内容寻址快照只跟踪文件，不含任何文件的目录与未初始化等价，避免整个 workspace 无法快照。
+	return (await directoryTreeContainsFile(absolutePath)) ? "broken" : "uninitialized";
+}
+
+const SKELETON_NOISE_FILES = new Set([".DS_Store", "desktop.ini", "Thumbs.db"]);
+
+async function directoryTreeContainsFile(directory: string): Promise<boolean> {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return true;
+	}
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			if (await directoryTreeContainsFile(join(directory, entry.name))) return true;
+		} else if (entry.isSymbolicLink() || SKELETON_NOISE_FILES.has(entry.name)) {
+			// symlink 不适随也不计内容：uninitialized 根下的内容不被捕获也不会被 restore 触碰，
+			// 原样保留不会丢失；OS 噪音文件不应让整个 workspace 无法快照。
+			continue;
+		} else {
+			return true;
+		}
+	}
+	return false;
 }
 
 function cleanGitEnvironment(): Readonly<Record<string, string | undefined>> {

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;
@@ -184,6 +201,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 = {}) {
@@ -252,11 +270,14 @@ export class SnapshotStore {
 			const coverage = captureCoverage(topology.workspaceIdentity, scope);
 			const artifactExclusions = captureExclusions(topology.workspaceIdentity, options.excludePaths);
 			await this.assertTopology(topology, "捕获前 topology 已变化");
-			if (topology.roots.some((root) => root.state === "broken")) {
-				throw new SnapshotStoreError("capture_failed", "broken root 不能静默进入快照");
+			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-"));
@@ -314,6 +335,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) {
@@ -347,8 +370,9 @@ export class SnapshotStore {
 			}
 			const artifactExclusions = captureExclusions(topology.workspaceIdentity, options.excludePaths);
 			await this.assertTopology(topology, "可见路径枚举前 topology 已变化");
-			if (topology.roots.some((root) => root.state === "broken")) {
-				throw new SnapshotStoreError("capture_failed", "broken root 不能静默进入可见路径枚举");
+			const brokenRoots = brokenRootPaths(topology);
+			if (brokenRoots.length > 0) {
+				throw new SnapshotStoreError("capture_failed", `broken root 不能静默进入可见路径枚举: ${brokenRoots.join(", ")}`);
 			}
 
 			const storeDirectory = this.storeDirectory(topology);
@@ -958,6 +982,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[],
@@ -1572,6 +1659,10 @@ function ignoredPresentProof(coverage: string, ignoredPresentPaths: readonly str
 	};
 }
 
+function brokenRootPaths(topology: Pick<RootTopology, "roots">): string[] {
+	return topology.roots.filter((root) => root.state === "broken").map((root) => root.relativeRoot);
+}
+
 function inactiveRootClosure(root: Pick<RootTopologyIdentity, "relativeRoot" | "state">): string {
 	return checksum(canonicalJson({
 		relativeRoot: root.relativeRoot,
@@ -1786,6 +1877,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,
@@ -1879,11 +1997,16 @@ function parseTreeEntries(output: Uint8Array): CapturedTreeEntry[] {
 }
 
 function parseNulPaths(output: Uint8Array): string[] {
-	return splitNulRecords(output).map((record) => {
+	const paths: string[] = [];
+	for (const record of splitNulRecords(output)) {
 		const path = decodeUtf8(record);
+		// git 在嵌套仓库边界会输出折叠的目录项（如 "dir/"）；该目录由 root discovery
+		// 作为独立 root 捕获，不属于本仓库的路径枚举，直接跳过。
+		if (path.endsWith("/")) continue;
 		relativeSafePath("/", path);
-		return path;
-	});
+		paths.push(path);
+	}
+	return paths;
 }
 
 function splitNulRecords(output: Uint8Array): Uint8Array[] {