@davideasden/pi-undo 0.2.20 → 0.2.22

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;
@@ -168,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 &&
@@ -227,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.20",
+	"version": "0.2.22",
 	"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) {
@@ -450,7 +452,9 @@ export class UndoControllerImpl implements UndoController {
 	}
 
 	async beforeTree(event: SessionBeforeTreeEvent): Promise<SessionBeforeTreeResult | undefined> {
-		if (!this.dependencies.isAgentIdle()) {
+		// Pi 0.86+ 在树导航期间也会让 isIdle() 暂时返回 false；只有 pi-undo
+		// 已经记录了尚未 settle 的 run 时，才需要中止并取消导航。
+		if (this.staged !== undefined) {
 			await this.dependencies.abortAgent();
 			return { cancel: true };
 		}
@@ -830,6 +834,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 +1031,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/pi-runtime.ts

@@ -285,7 +285,13 @@ function rebuildControllerState(
 	identity: SessionFileIdentity,
 ): ControllerInitialState {
 	const state = sessionStateFor(manager);
-	const checkpoints = state.getCheckpoints(identity);
+	const branch = physicalBranch(manager, manager.getLeafId());
+	const checkpoints = checkpointFrontierAfterDetachedRun(
+		manager,
+		identity,
+		branch,
+		state.getCheckpoints(identity),
+	);
 	const cursor = state.getCursor(identity);
 	let undoStack = [...checkpoints];
 	if (cursor !== null) {
@@ -305,12 +311,34 @@ function rebuildControllerState(
 		if (sourceCursor === undefined) throw new Error("cursor redo safety manifest 缺失");
 		return { checkpoint, targetManifestId: sourceCursor.rollbackManifestId };
 	});
-	const branch = physicalBranch(manager, manager.getLeafId());
 	const lastBarrier = findLastIndex(branch, (entry) => entry.type === "custom" && entry.customType === "pi-undo:barrier");
 	const lastCheckpoint = findLastIndex(branch, (entry) => entry.type === "custom" && entry.customType === "pi-undo:checkpoint");
 	return { undoStack, redoStack, historyPaused: lastBarrier > lastCheckpoint };
 }
 
+/**
+ * redo 或树导航后的新 run 会挂在 cursor 后面，使前一个 checkpoint 脱离当前物理 branch。
+ * start entry 保存了 run 前的逻辑叶，利用它恢复可信的 checkpoint frontier，再接上当前 branch。
+ */
+function checkpointFrontierAfterDetachedRun(
+	manager: ReadonlySessionManager,
+	identity: SessionFileIdentity,
+	branch: readonly Record<string, unknown>[],
+	current: readonly CheckpointRecord[],
+): CheckpointRecord[] {
+	const start = [...branch].reverse().find((entry) => entry.type === "custom" && entry.customType === "pi-undo:start");
+	if (start === undefined || !isRecord(start.data)) return [...current];
+	const sourceLogicalLeaf = start.data.sourceLogicalLeaf;
+	if (typeof sourceLogicalLeaf !== "string") return [...current];
+	const sourceCheckpoint = findCheckpointByEndLeaf(manager, identity, sourceLogicalLeaf);
+	if (sourceCheckpoint === undefined) return [...current];
+	const inherited = checkpointFrontierById(manager, identity, sourceCheckpoint.checkpointId);
+	return [
+		...inherited,
+		...current.filter((checkpoint) => !inherited.some((candidate) => candidate.checkpointId === checkpoint.checkpointId)),
+	].filter((checkpoint, index, all) => all.findIndex((candidate) => candidate.checkpointId === checkpoint.checkpointId) === index);
+}
+
 function checkpointFrontierById(
 	manager: ReadonlySessionManager,
 	identity: SessionFileIdentity,