@davideasden/pi-undo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DavidEasden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# pi-undo
+
+`pi-undo` 为 Pi 0.80.10 提供持久化的 `/undo` 和 `/redo`。一次操作对应一个完整 Agent run，并同时恢复 Pi session tree 的逻辑位置和工作区文件。
+
+实现使用 Pi session JSONL、私有 snapshot store 和 WAL journal。它不会在项目中创建 `.git`，也不会要求用户执行 `git commit`、`git stash`、`git reset` 或维护隐藏分支。
+
+## 安装与本地试用
+
+安装本地 package：
+
+```bash
+pi install ./path/to/pi-undo
+```
+
+开发时也可以直接加载 extension：
+
+```bash
+pi -e /absolute/path/to/pi-undo/extensions/pi-undo.ts
+```
+
+要求 Node.js 22.19 或更高版本，并且系统可执行 `git`。
+
+## 使用方式
+
+- `/undo`：回退当前 branch 上最后一个完整 Agent run。执行前会保存当前工作区作为 redo safety snapshot。
+- `/redo`：恢复最近一次 undo 前保存的工作区状态，而不是简单覆盖成 checkpoint 的原始 after snapshot。
+- `/tree`：仍使用 Pi 原生命令。package 在导航前预检目标 boundary 并保存 rescue snapshot，导航完成后恢复该 boundary 对应的文件状态。
+
+如果 Agent 正在 streaming，`/undo` 和 `/redo` 会先请求 abort，再等待 Agent idle；等待超时或工具仍未停止时不会恢复文件。streaming 中的普通 `/tree` 会被取消，用户可在 idle 后重试。
+
+undo 成功后，TUI 编辑器为空时会尝试回填原始 prompt；编辑器已有文字时不会覆盖用户输入。RPC 只报告回填请求，print/json 模式不承诺编辑器回填。
+
+## 数据与 Git 边界
+
+私有数据位于 Pi session 目录下：
+
+```text
+<sessionDir>/.pi-undo/
+```
+
+snapshot 使用独立 Git object database 和临时 index，但不会写入用户仓库的 `HEAD`、index、refs、reflog、stash、config 或其他真实 Git metadata。
+
+restore 对普通文件和 symlink 使用原路径同目录、同文件系统的 quarantine。目标安装采用 no-clobber 语义：外部进程在 restore 期间重建路径时，`pi-undo` 不会覆盖该路径，并会保留 transaction mutation WAL 与仍可验证的 source/target artifact，供重启恢复或人工诊断。
+
+普通文件的 source capture 先创建 hard link，再在删除原路径前重新检查路径 fingerprint 和 inode identity。这是纯 Node.js 能提供的 CAS-before-unlink best-effort；它显著缩小并发窗口，但不能原子合并最后一次检查与 `unlink`。
+
+普通目录、outer repository、nested repository 和已初始化 submodule 都按 root forest 独立捕获和恢复。nested repository/submodule 只恢复内部工作区文件：
+
+- 不切换真实 HEAD；
+- 不运行 `git submodule update`；
+- 不修改真实 index、refs、reflog 或 `.git`；
+- 不重建被删除的真实 `.git`。
+
+## 持久化与故障恢复
+
+每次 undo、redo 或 tree restore 都先写 WAL journal。Pi 重启后：
+
+- 没有可信 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。
+
+故障 journal 会保留在 `<sessionDir>/.pi-undo/transactions/`，用于诊断和人工恢复。不要在未备份的情况下删除该目录。footer 显示 `recovery required` 时，应先保存工作区和 session JSONL，再检查对应 transaction 的 `descriptor.json`、`restore-plan.json` 和 `state.json`。
+
+## 明确限制
+
+- 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 收敛到旧状态或新状态。
+
+## 开发验证
+
+```bash
+npm test
+npm run test:integration
+npm run typecheck
+npm run pack:dry-run
+```
+
+真实 Pi `AgentSession` 集成测试需要先安装并构建 `resources/pi-0.80.10` 的 workspace packages。

package/extensions/pi-undo.ts

@@ -0,0 +1,133 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	InputEvent,
+	SessionBeforeTreeEvent as PiSessionBeforeTreeEvent,
+	SessionTreeEvent as PiSessionTreeEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import type { UndoController } from "../src/controller.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 recovery?: { readonly files?: number; readonly opId?: string };
+	setCommandContext?(context: ExtensionCommandContext | undefined): void;
+	isInternalNavigation?(): boolean;
+}
+
+export type PiUndoRuntimeFactory = (
+	context: ExtensionContext,
+	pi: ExtensionAPI,
+) => Promise<PiUndoRuntime>;
+
+export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi: ExtensionAPI) => void {
+	return (pi) => {
+		let runtime: PiUndoRuntime | undefined;
+		let generation = 0;
+
+		const initialize = async (context: ExtensionContext): Promise<void> => {
+			const currentGeneration = ++generation;
+			try {
+				const next = await runtimeFactory(context, pi);
+				if (currentGeneration !== generation) return;
+				runtime = next;
+				await next.controller.recover();
+				const history = next.controller.history();
+				if (history.locked) next.reporter.setRecoveryRequired("pending journal", next.recovery);
+				else next.reporter.setReady(history.undoCount, history.redoCount);
+			} catch (error) {
+				if (currentGeneration !== generation) return;
+				runtime = undefined;
+				new StatusReporter(context).setRecoveryRequired(errorMessage(error));
+			}
+		};
+
+		const runCommand = async (
+			action: "undo" | "redo",
+			context: ExtensionCommandContext,
+		): Promise<void> => {
+			const active = runtime;
+			const commandGeneration = generation;
+			if (active === undefined) {
+				context.ui.notify("pi-undo session unavailable", "warning");
+				return;
+			}
+			active.reporter.setPhase(action === "undo" ? "undoing" : "redoing");
+			active.setCommandContext?.(context);
+			let result;
+			try {
+				result = action === "undo"
+					? await active.controller.undo()
+					: await active.controller.redo();
+			} finally {
+				active.setCommandContext?.(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 history = active.controller.history();
+			if (history.locked) active.reporter.setRecoveryRequired(result.message ?? result.code);
+			else active.reporter.setReady(history.undoCount, history.redoCount);
+		};
+
+		pi.registerCommand("undo", {
+			description: "Undo the last completed Agent run",
+			handler: async (_args: string, context: ExtensionCommandContext) => runCommand("undo", context),
+		});
+		pi.registerCommand("redo", {
+			description: "Redo the last undone Agent run",
+			handler: async (_args: string, context: ExtensionCommandContext) => runCommand("redo", 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("before_agent_start", async () => { await runtime?.controller.beforeAgentStart(); });
+		pi.on("agent_settled", async () => {
+			const active = runtime;
+			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);
+		});
+		pi.on("session_before_tree", async (event: PiSessionBeforeTreeEvent) => {
+			if (runtime === undefined) return { cancel: true };
+			if (runtime.isInternalNavigation?.()) return undefined;
+			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 });
+			}
+			return result;
+		});
+		pi.on("session_tree", async (event: PiSessionTreeEvent) => {
+			if (runtime?.isInternalNavigation?.()) return;
+			await runtime?.controller.afterTree({
+				newLeafId: event.newLeafId,
+				navigationTargetLeafId: event.summaryEntry?.parentId ?? event.newLeafId,
+			});
+		});
+		pi.on("session_shutdown", async () => {
+			generation += 1;
+			await runtime?.controller.cancelTree?.();
+			runtime?.reporter.clear();
+			runtime = undefined;
+		});
+	};
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export default createPiUndoExtension(createPiUndoRuntime);

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@davideasden/pi-undo",
+	"version": "0.1.0",
+	"description": "Persistent workspace undo and redo for Pi",
+	"type": "module",
+	"keywords": [
+		"pi-package"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DavidEasden/pi-undo.git"
+	},
+	"homepage": "https://github.com/DavidEasden/pi-undo#readme",
+	"bugs": {
+		"url": "https://github.com/DavidEasden/pi-undo/issues"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/pi-undo.ts"
+		]
+	},
+	"files": [
+		"extensions",
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:integration": "vitest run test/extension.integration.test.ts test/pi-runtime.test.ts",
+		"typecheck": "tsc --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.80.10"
+	},
+	"dependencies": {
+		"proper-lockfile": "4.1.2"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "file:resources/pi-0.80.10/packages/coding-agent",
+		"@types/node": "24.12.4",
+		"@types/proper-lockfile": "4.1.4",
+		"typescript": "5.9.3",
+		"vitest": "4.1.9"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/src/atomic-fs.ts

@@ -0,0 +1,156 @@
+import { randomBytes } from "node:crypto";
+import { link, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import { canonicalJson } from "./encoding.ts";
+
+export type AtomicFileErrorCode = "content_mismatch" | "invalid_mode";
+
+export class AtomicFileError extends Error {
+	readonly code: AtomicFileErrorCode;
+
+	constructor(code: AtomicFileErrorCode, message: string) {
+		super(message);
+		this.name = "AtomicFileError";
+		this.code = code;
+	}
+}
+
+export async function writeJsonAtomic(file: string, value: unknown): Promise<void> {
+	await writeBytesAtomic(file, Buffer.from(canonicalJson(value), "utf8"));
+}
+
+export async function writeBytesAtomic(file: string, bytes: Uint8Array, mode?: number): Promise<void> {
+	const directory = dirname(file);
+	await mkdir(directory, { recursive: true });
+	const fileMode = await targetMode(file, mode);
+	const temporary = await writeTemporary(directory, basename(file), bytes, fileMode);
+	let published = false;
+
+	try {
+		await rename(temporary, file);
+		published = true;
+		await fsyncDirectory(directory);
+	} finally {
+		if (!published) {
+			await rm(temporary, { force: true }).catch(() => {});
+		}
+	}
+}
+
+export async function writeContentAddressed(file: string, bytes: Uint8Array, mode?: number): Promise<void> {
+	const expected = Buffer.from(bytes);
+	try {
+		const existing = await readFile(file);
+		if (!existing.equals(expected)) {
+			throw new AtomicFileError("content_mismatch", "内容寻址文件已存在但内容不同");
+		}
+		return;
+	} catch (error) {
+		if (!hasErrorCode(error, "ENOENT")) {
+			throw error;
+		}
+	}
+
+	const directory = dirname(file);
+	await mkdir(directory, { recursive: true });
+	const temporary = await writeTemporary(directory, basename(file), expected, await targetMode(file, mode));
+	let linked = false;
+	try {
+		await link(temporary, file);
+		linked = true;
+	} catch (error) {
+		if (!hasErrorCode(error, "EEXIST")) {
+			throw error;
+		}
+		const published = await readFile(file);
+		if (!published.equals(expected)) {
+			throw new AtomicFileError("content_mismatch", "内容寻址文件已存在但内容不同");
+		}
+	} finally {
+		await rm(temporary, { force: true }).catch(() => {});
+	}
+
+	if (linked) {
+		await fsyncDirectory(directory);
+	}
+}
+
+export async function fsyncFile(file: string): Promise<void> {
+	const handle = await open(file, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+export async function fsyncDirectory(directory: string): Promise<void> {
+	const handle = await open(directory, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+export async function writeBytesExclusive(file: string, bytes: Uint8Array, mode: number): Promise<void> {
+	const handle = await open(file, "wx", mode);
+	try {
+		await handle.writeFile(Buffer.from(bytes));
+		await handle.chmod(mode);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	await fsyncDirectory(dirname(file));
+}
+
+async function targetMode(file: string, mode: number | undefined): Promise<number> {
+	if (mode !== undefined) {
+		if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
+			throw new AtomicFileError("invalid_mode", "文件 mode 无效");
+		}
+		return mode;
+	}
+
+	try {
+		return (await stat(file)).mode & 0o7777;
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) {
+			return 0o600;
+		}
+		throw error;
+	}
+}
+
+async function writeTemporary(
+	directory: string,
+	fileName: string,
+	bytes: Uint8Array,
+	mode: number,
+): Promise<string> {
+	const temporary = join(
+		directory,
+		`.${fileName}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+	);
+	let handle: FileHandle | undefined;
+	try {
+		handle = await open(temporary, "wx", mode);
+		await handle.writeFile(Buffer.from(bytes));
+		await handle.chmod(mode);
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		return temporary;
+	} catch (error) {
+		await handle?.close().catch(() => {});
+		await rm(temporary, { force: true }).catch(() => {});
+		throw error;
+	}
+}
+
+function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}