@davideasden/pi-undo 0.2.20 → 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;
@@ -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.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));
+}