@davideasden/pi-undo 0.2.11 → 0.2.14

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.14",
 	"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

@@ -252,8 +252,9 @@ 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);
@@ -347,8 +348,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);
@@ -1572,6 +1574,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,
@@ -1879,11 +1885,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[] {