@davideasden/pi-undo 0.1.1 → 0.2.0

package/README.md

@@ -1,84 +1,215 @@
 # pi-undo
 
-`pi-undo` 为 Pi 0.80.10 提供持久化的 `/undo` 和 `/redo`。一次操作对应一个完整 Agent run，并同时恢复 Pi session tree 的逻辑位置和工作区文件。
+Persistent undo and redo for [Pi](https://github.com/badlogic/pi-mono) that restores both the agent session and workspace files without requiring users to manage Git.
 
-实现使用 Pi session JSONL、私有 snapshot store 和 WAL journal。它不会在项目中创建 `.git`，也不会要求用户执行 `git commit`、`git stash`、`git reset` 或维护隐藏分支。
+Each history entry represents one completed agent run. When you undo or redo, `pi-undo` moves Pi's session tree to the matching point and restores the corresponding workspace state.
 
-## 安装与本地试用
+## Features
 
-安装本地 package：
+- Persistent `/undo` and `/redo` across Pi restarts.
+- Restores the Pi session and workspace files together.
+- Preserves redo state with a safety snapshot taken immediately before undo.
+- Integrates with Pi's native `/tree` navigation.
+- Supports ordinary directories, Git repositories, nested repositories, and initialized submodules.
+- Uses durable journals and restart recovery for interrupted operations.
+- Detects conflicting external file changes and fails closed instead of overwriting unknown content.
+- Does not require `git commit`, `git stash`, `git reset`, hidden branches, or any other user-managed Git workflow.
+
+## Requirements
+
+- Pi `0.80.10` or a compatible release.
+- Node.js `22.19.0` or later.
+- Git available on `PATH`.
+
+Git is used internally to create private, content-addressed snapshots. You do not need to initialize a repository or run Git commands yourself.
+
+## Installation
+
+Install the published Pi package from npm:
+
+```bash
+pi install npm:@davideasden/pi-undo
+```
+
+Restart Pi after installation if the extension is not loaded in the current session.
+
+To install a local checkout instead:
 
 ```bash
 pi install ./path/to/pi-undo
 ```
 
-开发时也可以直接加载 extension：
+During development, you can load the extension directly:
 
 ```bash
 pi -e /absolute/path/to/pi-undo/extensions/pi-undo.ts
 ```
 
-要求 Node.js 22.19 或更高版本，并且系统可执行 `git`。
+## Usage
+
+Work with Pi normally. `pi-undo` records a boundary after each completed agent run.
+
+### Diff
+
+```text
+/diff
+```
+
+`/diff` reviews the files changed by the most recent completed agent run. In TUI mode, select a file to open a colored, scrollable before-and-after comparison. Binary files are listed but do not receive a line-by-line diff.
+
+Use a one-based history position to inspect an earlier applied run, where `1` is the most recent:
+
+```text
+/diff 2
+```
+
+Print, JSON, and RPC modes report a one-line file and line-count summary instead of opening the interactive viewer.
+
+### Undo
+
+```text
+/undo
+```
+
+`/undo` returns to the previous completed agent run on the current branch. Before restoring that checkpoint, it captures the current workspace as a redo safety snapshot.
 
-## 使用方式
+After a successful undo, `pi-undo` tries to put the original prompt back into an empty TUI editor. It never overwrites text already present in the editor. RPC mode only reports the refill request, while print and JSON modes do not promise editor refill behavior.
 
-- `/undo`：回退当前 branch 上最后一个完整 Agent run。执行前会保存当前工作区作为 redo safety snapshot。
-- `/redo`：恢复最近一次 undo 前保存的工作区状态，而不是简单覆盖成 checkpoint 的原始 after snapshot。
-- `/tree`：仍使用 Pi 原生命令。package 在导航前预检目标 boundary 并保存 rescue snapshot，导航完成后恢复该 boundary 对应的文件状态。
+### Redo
 
-如果 Agent 正在 streaming，`/undo` 和 `/redo` 会先请求 abort，再等待 Agent idle；等待超时或工具仍未停止时不会恢复文件。streaming 中的普通 `/tree` 会被取消，用户可在 idle 后重试。
+```text
+/redo
+```
 
-undo 成功后，TUI 编辑器为空时会尝试回填原始 prompt；编辑器已有文字时不会覆盖用户输入。RPC 只报告回填请求，print/json 模式不承诺编辑器回填。
+`/redo` restores the session and workspace captured immediately before the corresponding undo. It does not simply reapply the checkpoint's original after-snapshot, so edits preserved by the redo safety snapshot are restored correctly.
 
-## 数据与 Git 边界
+### Tree Navigation
 
-私有数据位于 Pi session 目录下：
+Continue to use Pi's native command:
+
+```text
+/tree
+```
+
+Before Pi moves to another session-tree boundary, `pi-undo` validates the target and records a rescue snapshot. After navigation, it restores the workspace associated with the selected boundary.
+
+If the agent is streaming, `/undo` and `/redo` request an abort and wait for the agent to become idle. If the wait times out or tools are still running, no files are restored. Native `/tree` navigation is cancelled while streaming and can be retried when Pi is idle.
+
+The footer shows the available history, for example:
+
+```text
+undo:2 redo:1
+```
+
+## How It Works
+
+Private state is stored alongside the Pi session:
 
 ```text
 <sessionDir>/.pi-undo/
 ```
 
-snapshot 使用独立 Git object database 和临时 index，但不会写入用户仓库的 `HEAD`、index、refs、reflog、stash、config 或其他真实 Git metadata。
+For every completed agent run, `pi-undo` captures the session boundary and a workspace manifest. Snapshots use a private Git object database and temporary index. They do not use the repository's normal history.
+
+Undo, redo, and tree restoration follow the same high-level flow:
+
+1. Validate the current session, workspace topology, and target manifest.
+2. Write a durable write-ahead log (WAL) before changing files.
+3. Capture a safety or rescue snapshot when required.
+4. Move the Pi session to the target logical boundary.
+5. Restore workspace paths with fingerprint checks and no-clobber installation.
+6. Verify the resulting session and workspace before committing the journal.
 
-restore 对普通文件和 symlink 使用原路径同目录、同文件系统的 quarantine。目标安装采用 no-clobber 语义：外部进程在 restore 期间重建路径时，`pi-undo` 不会覆盖该路径，并会保留 transaction mutation WAL 与仍可验证的 source/target artifact，供重启恢复或人工诊断。
+Ordinary files and symbolic links are restored through same-directory, same-filesystem quarantine artifacts. For regular files, source capture uses a hard link and checks the path fingerprint and inode identity again immediately before removing the original path. This narrows the external-concurrency window, but cannot make the final check and unlink operation atomic in pure Node.js.
 
-普通文件的 source capture 先创建 hard link，再在删除原路径前重新检查路径 fingerprint 和 inode identity。这是纯 Node.js 能提供的 CAS-before-unlink best-effort；它显著缩小并发窗口，但不能原子合并最后一次检查与 `unlink`。
+## Safety and Recovery
 
-普通目录、outer repository、nested repository 和已初始化 submodule 都按 root forest 独立捕获和恢复。nested repository/submodule 只恢复内部工作区文件：
+`pi-undo` does not modify the user's Git `HEAD`, index, refs, reflogs, stash, configuration, or other repository metadata. Nested repositories and initialized submodules are captured as independent roots, but only their working files are restored. The extension does not switch their real `HEAD`, run `git submodule update`, or recreate deleted `.git` metadata.
 
-- 不切换真实 HEAD；
-- 不运行 `git submodule update`；
-- 不修改真实 index、refs、reflog 或 `.git`；
-- 不重建被删除的真实 `.git`。
+If Pi or the process stops during a restore, the next session startup reads the transaction journal:
 
-## 持久化与故障恢复
+- Without a trusted cursor marker, it restores the rollback manifest and marks the transaction aborted.
+- With a trusted cursor marker, it restores the target manifest, completes cursor durability, and commits the transaction.
+- If the journal, session identity, logical leaf, manifest, cursor, or workspace contents conflict, it enters `recovery required` and blocks further history mutation.
 
-每次 undo、redo 或 tree restore 都先写 WAL journal。Pi 重启后：
+When the footer reports `recovery_required`, first back up the workspace and Pi session JSONL. Transaction diagnostics are stored in:
+
+```text
+<sessionDir>/.pi-undo/transactions/
+```
 
-- 没有可信 cursor marker：恢复 rollback manifest，并把操作终止为 `ABORTED`；
-- 有可信 cursor marker：重新恢复 target manifest、补齐 cursor durability，并把操作完成为 `COMMITTED`；
-- journal、session identity、logical leaf、manifest 或 cursor payload 不一致：进入 `recovery required`，停止新的 undo/redo、tree mutation 和 Agent boundary。
+The relevant transaction may contain `descriptor.json`, `restore-plan.json`, `state.json`, and mutation journal data. Do not delete the `.pi-undo` directory without a backup: unresolved quarantine artifacts may contain the only preserved copy of a file version.
 
-故障 journal 会保留在 `<sessionDir>/.pi-undo/transactions/`，用于诊断和人工恢复。不要在未备份的情况下删除该目录。footer 显示 `recovery required` 时，应先保存工作区和 session JSONL，再检查对应 transaction 的 `descriptor.json`、`restore-plan.json` 和 `state.json`。
+## Limitations
 
-## 明确限制
+- Git-ignored files are not included in snapshots and are not created or deleted during restore.
+- Empty directories are not represented in snapshots.
+- Real `.git` metadata is never restored.
+- The workspace lock coordinates `pi-undo` instances, but cannot prevent editors, watchers, or other processes from writing files concurrently.
+- Quarantine and repeated fingerprint checks reduce, but cannot eliminate, the final check-to-unlink race with arbitrary external processes.
+- When ownership or contents cannot be proven, `pi-undo` preserves the available versions and enters `recovery required` instead of guessing, deleting, or overwriting.
+- `--no-session` mode has no durable session cursor. Undo and redo can work in-process, but crash persistence is not guaranteed.
+- Uninitialized gitlinks are not initialized automatically. A broken nested repository causes capture to fail instead of being silently skipped.
+- Workspace files and Pi JSONL are not an operating-system-level ACID transaction. Snapshots, WAL records, cursor markers, verification, and idempotent recovery are used to converge to the old or new state.
 
-- Git ignored 文件不进入 snapshot，也不会被 restore 创建或删除。
-- 空目录不属于 snapshot。
-- package 不恢复真实 `.git` metadata。
-- package 锁只能协调其他 `pi-undo` 实例，不能阻止外部编辑器、watcher 或其他进程同时写文件；无法证明安全时会 fail closed。
-- quarantine 不能消除任意外部进程带来的最终 `check -> unlink` TOCTOU 窗口。无法证明 original、target 或 artifact 的内容与归属时，package 会保留现场并进入 `recovery required`，不会猜测、强制删除或覆盖未知内容。
-- `--no-session` 模式没有可耐久验证的 session cursor，只提供进程内能力，不能承诺进程崩溃后的 undo/redo 持久化。
-- uninitialized gitlink 不会被自动初始化；broken nested root 会使 capture 失败，而不是静默遗漏。
-- package 不对工作区文件与 Pi JSONL 提供操作系统级 ACID 事务；它通过 snapshot、WAL、cursor marker 和幂等 set-state recovery 收敛到旧状态或新状态。
+## Development
 
-## 开发验证
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/DavidEasden/pi-undo.git
+cd pi-undo
+npm install
+```
+
+The development dependency for Pi points to:
+
+```text
+resources/pi-0.80.10/packages/coding-agent
+```
+
+For type checking and the real `AgentSession` integration tests, place the Pi `0.80.10` source tree at that path, install its workspace dependencies, and build the required workspace packages. The published package does not include `resources/`.
+
+Useful project paths:
+
+```text
+extensions/pi-undo.ts   Pi extension entry point
+src/                    Snapshot, journal, restore, and runtime implementation
+test/                   Unit, integration, recovery, and fault-injection tests
+```
+
+## Testing
+
+Run the complete test suite:
 
 ```bash
 npm test
+```
+
+Run tests in watch mode:
+
+```bash
+npm run test:watch
+```
+
+Run the Pi runtime and extension integration tests:
+
+```bash
 npm run test:integration
+```
+
+Run TypeScript type checking:
+
+```bash
 npm run typecheck
+```
+
+Inspect the npm package contents before publishing:
+
+```bash
 npm run pack:dry-run
 ```
 
-真实 Pi `AgentSession` 集成测试需要先安装并构建 `resources/pi-0.80.10` 的 workspace packages。
+## License
+
+[MIT](LICENSE)

package/extensions/pi-undo.ts

@@ -8,12 +8,15 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import type { UndoController } from "../src/controller.ts";
+import { browseDiff } from "../src/diff-ui.ts";
+import { computeCheckpointDiff, type DiffSource, formatDiffSummary, sanitizeDisplayText } from "../src/diff-view.ts";
 import { createPiUndoRuntime } from "../src/pi-runtime.ts";
 import { StatusReporter } from "../src/status-reporter.ts";
 
 export interface PiUndoRuntime {
 	readonly controller: UndoController;
 	readonly reporter: StatusReporter;
+	readonly diffSource?: DiffSource;
 	readonly recovery?: { readonly files?: number; readonly opId?: string };
 	setCommandContext?(context: ExtensionCommandContext | undefined): void;
 	isInternalNavigation?(): boolean;
@@ -24,13 +27,32 @@ export type PiUndoRuntimeFactory = (
 	pi: ExtensionAPI,
 ) => Promise<PiUndoRuntime>;
 
+type DeferredImage = NonNullable<InputEvent["images"]>[number];
+
+interface DeferredPrompt {
+	readonly text: string;
+	readonly images?: readonly DeferredImage[];
+}
+
 export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi: ExtensionAPI) => void {
 	return (pi) => {
 		let runtime: PiUndoRuntime | undefined;
+		let runtimeContext: ExtensionContext | undefined;
 		let generation = 0;
+		let deferredPrompts: DeferredPrompt[] = [];
+		let replaying: DeferredPrompt | undefined;
+		let acceptedReplay: DeferredPrompt | undefined;
+		let activeCommands = new Set<symbol>();
+		let activeAction: "undo" | "redo" | undefined;
 
 		const initialize = async (context: ExtensionContext): Promise<void> => {
 			const currentGeneration = ++generation;
+			runtimeContext = context;
+			deferredPrompts = [];
+			replaying = undefined;
+			acceptedReplay = undefined;
+			activeCommands = new Set<symbol>();
+			activeAction = undefined;
 			try {
 				const next = await runtimeFactory(context, pi);
 				if (currentGeneration !== generation) return;
@@ -46,6 +68,57 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			}
 		};
 
+		const dispatchDeferredPrompt = (active: PiUndoRuntime, expectedGeneration: number): void => {
+			if (
+				expectedGeneration !== generation || runtime !== active || activeCommands.size > 0 ||
+				replaying !== undefined || deferredPrompts.length === 0 || active.controller.history().locked
+			) return;
+			const prompt = deferredPrompts[0]!;
+			replaying = prompt;
+			acceptedReplay = undefined;
+			queueMicrotask(() => {
+				if (expectedGeneration !== generation || runtime !== active || replaying !== prompt) return;
+				try {
+					pi.sendUserMessage(prompt.images === undefined || prompt.images.length === 0
+						? prompt.text
+						: [{ type: "text" as const, text: prompt.text }, ...prompt.images]);
+				} catch (error) {
+					replaying = undefined;
+					acceptedReplay = undefined;
+					deferredPrompts.shift();
+					restoreEditorText(runtimeContext, prompt.text);
+					runtimeContext?.ui.notify(`Unable to replay queued prompt: ${errorMessage(error)}`, "warning");
+				}
+			});
+		};
+
+		const restoreDeferredPrompts = (context: ExtensionContext | undefined): void => {
+			if (deferredPrompts.length === 0) return;
+			const prompts = deferredPrompts.splice(0);
+			replaying = undefined;
+			acceptedReplay = undefined;
+			restoreEditorText(context, prompts.map((prompt) => prompt.text).join("\n\n"));
+			if (prompts.some((prompt) => (prompt.images?.length ?? 0) > 0)) {
+				context?.ui.notify("Queued prompt text restored; image attachments must be reattached", "warning");
+			}
+		};
+
+		const resumeDeferredPrompts = (
+			active: PiUndoRuntime,
+			expectedGeneration: number,
+			lockedReason: string,
+		): void => {
+			if (expectedGeneration !== generation || runtime !== active) return;
+			const history = active.controller.history();
+			if (history.locked) {
+				active.reporter.setRecoveryRequired(lockedReason);
+				restoreDeferredPrompts(runtimeContext);
+			} else {
+				active.reporter.setReady(history.undoCount, history.redoCount);
+				dispatchDeferredPrompt(active, expectedGeneration);
+			}
+		};
+
 		const runCommand = async (
 			action: "undo" | "redo",
 			context: ExtensionCommandContext,
@@ -56,6 +129,10 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 				context.ui.notify("pi-undo session unavailable", "warning");
 				return;
 			}
+			const commandToken = Symbol(action);
+			const commandSet = activeCommands;
+			commandSet.add(commandToken);
+			activeAction = action;
 			active.reporter.setPhase(action === "undo" ? "undoing" : "redoing");
 			active.setCommandContext?.(context);
 			let result;
@@ -65,15 +142,56 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 					: await active.controller.redo();
 			} finally {
 				active.setCommandContext?.(undefined);
+				commandSet.delete(commandToken);
+				if (commandSet === activeCommands && commandSet.size === 0) activeAction = undefined;
 			}
 			if (commandGeneration !== generation || runtime !== active) return;
 			active.reporter.result(result);
-			if (action === "undo" && result.code === "ok" && result.refillPrompt !== undefined) {
-				active.reporter.refillPrompt(result.refillPrompt);
+			const hasDeferredPrompt = deferredPrompts.length > 0 || replaying !== undefined;
+			if (
+				action === "undo" && result.code === "ok" && result.refillPrompt !== undefined &&
+				!hasDeferredPrompt
+			) active.reporter.refillPrompt(result.refillPrompt);
+			resumeDeferredPrompts(active, commandGeneration, result.message ?? result.code);
+		};
+
+		const runDiff = async (args: string, context: ExtensionCommandContext): Promise<void> => {
+			const active = runtime;
+			if (active === undefined || active.diffSource === undefined) {
+				context.ui.notify("pi-undo session unavailable", "warning");
+				return;
 			}
-			const history = active.controller.history();
-			if (history.locked) active.reporter.setRecoveryRequired(result.message ?? result.code);
-			else active.reporter.setReady(history.undoCount, history.redoCount);
+			const checkpoints = active.controller.listCheckpoints();
+			if (checkpoints.length === 0) {
+				context.ui.notify("No recorded Agent runs to diff", "info");
+				return;
+			}
+			const trimmed = args.trim();
+			const position = trimmed === "" ? 1 : Number(trimmed);
+			if (!Number.isInteger(position) || position < 1 || position > checkpoints.length) {
+				context.ui.notify(`Invalid run number; recorded runs: ${checkpoints.length}`, "warning");
+				return;
+			}
+			// 1 = 最近一次 run（栈顶）。
+			const checkpoint = checkpoints[checkpoints.length - position]!;
+			let diffs;
+			try {
+				diffs = await computeCheckpointDiff(active.diffSource, checkpoint);
+			} catch (error) {
+				context.ui.notify(`Unable to load diff: ${sanitizeDisplayText(errorMessage(error), 120)}`, "error");
+				return;
+			}
+			if (runtime !== active) return;
+			if (diffs.length === 0) {
+				context.ui.notify("This run changed no files", "info");
+				return;
+			}
+			const label = runLabel(checkpoint.rawPrompt, position);
+			if (context.mode !== "tui") {
+				context.ui.notify(`${label} — ${formatDiffSummary(diffs)}`, "info");
+				return;
+			}
+			await browseDiff(context, label, diffs);
 		};
 
 		pi.registerCommand("undo", {
@@ -84,21 +202,75 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			description: "Redo the last undone Agent run",
 			handler: async (_args: string, context: ExtensionCommandContext) => runCommand("redo", context),
 		});
+		pi.registerCommand("diff", {
+			description: "Review files changed by an Agent run (latest, or /diff N)",
+			handler: async (args: string, context: ExtensionCommandContext) => runDiff(args, context),
+		});
 
 		pi.on("session_start", async (_event: unknown, context: ExtensionContext) => initialize(context));
-		pi.on("input", async (event: InputEvent) => {
-			if (runtime === undefined) return { action: "handled" as const };
-			return runtime.controller.prepareInput(event.text, { streaming: event.streamingBehavior !== undefined });
+		pi.on("input", async (event: InputEvent, context: ExtensionContext) => {
+			const active = runtime;
+			if (active === undefined) return { action: "handled" as const };
+			const result = await active.controller.prepareInput(event.text, {
+				streaming: event.streamingBehavior !== undefined,
+			});
+			const replay = replaying;
+			if (result.action === "defer") {
+				if (replay !== undefined && event.source === "extension" && samePrompt(event.text, event.images, replay)) {
+					replaying = undefined;
+					acceptedReplay = undefined;
+					active.reporter.setPhase(`${activeAction ?? "operation"} queued:${deferredPrompts.length}`);
+					return { action: "handled" as const };
+				}
+				if (event.text.trimStart().startsWith("/")) {
+					restoreEditorText(context, event.text);
+					context.ui.notify("Command input preserved until undo/redo completes", "info");
+					return { action: "handled" as const };
+				}
+				deferredPrompts.push({
+					text: event.text,
+					...(event.images === undefined ? {} : { images: event.images.map((image) => ({ ...image })) }),
+				});
+				active.reporter.setPhase(`${activeAction ?? "operation"} queued:${deferredPrompts.length}`);
+				return { action: "handled" as const };
+			}
+			if (replay !== undefined && event.source === "extension" && samePrompt(event.text, event.images, replay)) {
+				if (result.action === "continue") {
+					acceptedReplay = replay;
+				} else {
+					removeDeferredPrompt(deferredPrompts, replay);
+					replaying = undefined;
+					acceptedReplay = undefined;
+					restoreEditorText(context, replay.text);
+					if ((replay.images?.length ?? 0) > 0) {
+						context.ui.notify("Queued prompt text restored; image attachments must be reattached", "warning");
+					}
+				}
+			}
+			return result;
+		});
+		pi.on("before_agent_start", async () => {
+			const active = runtime;
+			const startGeneration = generation;
+			if (active === undefined) return;
+			await active.controller.beforeAgentStart();
+			const replay = replaying;
+			if (
+				runtime === active && generation === startGeneration && replay !== undefined &&
+				acceptedReplay === replay
+			) {
+				removeDeferredPrompt(deferredPrompts, replay);
+				replaying = undefined;
+				acceptedReplay = undefined;
+			}
 		});
-		pi.on("before_agent_start", async () => { await runtime?.controller.beforeAgentStart(); });
 		pi.on("agent_settled", async () => {
 			const active = runtime;
+			const settledGeneration = generation;
 			if (active === undefined) return;
 			await active.controller.agentSettled();
-			if (runtime !== active) return;
-			const history = active.controller.history();
-			if (history.locked) active.reporter.setRecoveryRequired("session state ambiguous");
-			else active.reporter.setReady(history.undoCount, history.redoCount);
+			if (runtime !== active || generation !== settledGeneration) return;
+			resumeDeferredPrompts(active, settledGeneration, "session state ambiguous");
 		});
 		pi.on("session_before_tree", async (event: PiSessionBeforeTreeEvent) => {
 			if (runtime === undefined) return { cancel: true };
@@ -106,7 +278,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			const active = runtime;
 			const result = await active.controller.beforeTree({ targetLeafId: event.preparation.targetId });
 			if (result === undefined) {
-				 event.signal?.addEventListener("abort", () => { void active.controller.cancelTree?.(); }, { once: true });
+				event.signal?.addEventListener("abort", () => { void active.controller.cancelTree?.(); }, { once: true });
 			}
 			return result;
 		});
@@ -119,6 +291,12 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		});
 		pi.on("session_shutdown", async () => {
 			generation += 1;
+			deferredPrompts = [];
+			replaying = undefined;
+			acceptedReplay = undefined;
+			activeCommands = new Set<symbol>();
+			activeAction = undefined;
+			runtimeContext = undefined;
 			await runtime?.controller.cancelTree?.();
 			runtime?.reporter.clear();
 			runtime = undefined;
@@ -126,8 +304,35 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 	};
 }
 
+function samePrompt(
+	text: string,
+	images: readonly DeferredImage[] | undefined,
+	prompt: DeferredPrompt,
+): boolean {
+	if (text !== prompt.text || (images?.length ?? 0) !== (prompt.images?.length ?? 0)) return false;
+	return (images ?? []).every((image, index) => JSON.stringify(image) === JSON.stringify(prompt.images?.[index]));
+}
+
+function removeDeferredPrompt(prompts: DeferredPrompt[], prompt: DeferredPrompt): void {
+	const index = prompts.indexOf(prompt);
+	if (index >= 0) prompts.splice(index, 1);
+}
+
+function restoreEditorText(context: ExtensionContext | undefined, text: string): void {
+	if (context === undefined || text.length === 0) return;
+	const current = context.ui.getEditorText();
+	if (current === text || current.startsWith(`${text}\n\n`)) return;
+	context.ui.setEditorText(current.length === 0 ? text : `${text}\n\n${current}`);
+}
+
 function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function runLabel(rawPrompt: string, position: number): string {
+	const singleLine = sanitizeDisplayText(rawPrompt, 1_000);
+	const preview = singleLine.length > 48 ? `${singleLine.slice(0, 47)}…` : singleLine;
+	return preview === "" ? `Run #${position}` : `Run #${position}: ${preview}`;
+}
+
 export default createPiUndoExtension(createPiUndoRuntime);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [
@@ -42,7 +42,8 @@
 		"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"

package/src/controller.ts

@@ -80,9 +80,10 @@ export interface OperationResult {
 	readonly refillPrompt?: string;
 }
 
-export interface InputEventResult {
-	readonly action: "continue" | "handled";
-}
+export type InputEventResult =
+	| { readonly action: "continue" }
+	| { readonly action: "handled" }
+	| { readonly action: "defer" };
 
 export interface InputContext {
 	readonly streaming: boolean;
@@ -108,6 +109,8 @@ export interface HistoryState {
 }
 
 export interface UndoController {
+	/** 只读的 undo 栈视图（栈底在前）；仅供 /diff 等展示使用。 */
+	listCheckpoints(): readonly CheckpointRecord[];
 	prepareInput(text: string, context: InputContext): Promise<InputEventResult>;
 	beforeAgentStart(): Promise<void>;
 	agentSettled(): Promise<void>;
@@ -161,6 +164,7 @@ export class UndoControllerImpl implements UndoController {
 	private locked = false;
 	private historyPaused = false;
 	private operationInFlight = false;
+	private promptDeferralInFlight = false;
 	private lastSafetyManifestId: ManifestId | null = null;
 
 	constructor(dependencies: ControllerDependencies, initialState: ControllerInitialState = {}) {
@@ -175,7 +179,12 @@ export class UndoControllerImpl implements UndoController {
 		return { undoCount: this.undoStack.length, redoCount: this.redoStack.length, locked: this.locked };
 	}
 
+	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 (context.streaming || text.length === 0) return { action: "continue" };
 		try {
@@ -376,6 +385,7 @@ export class UndoControllerImpl implements UndoController {
 	): Promise<OperationResult> {
 		if (this.locked || this.operationInFlight) return { code: "busy", changedFiles: 0 };
 		this.operationInFlight = true;
+		this.promptDeferralInFlight = true;
 		this.lastSafetyManifestId = null;
 		let lease: { release(): Promise<void> } | undefined;
 		try {
@@ -448,6 +458,7 @@ export class UndoControllerImpl implements UndoController {
 			if (lease !== undefined) {
 				await lease.release().catch(() => { this.locked = true; });
 			}
+			this.promptDeferralInFlight = false;
 			this.operationInFlight = false;
 		}
 	}