@davideasden/pi-undo 0.1.1 → 0.1.2

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;
@@ -76,6 +79,45 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			else active.reporter.setReady(history.undoCount, history.redoCount);
 		};
 
+		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 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", {
 			description: "Undo the last completed Agent run",
 			handler: async (_args: string, context: ExtensionCommandContext) => runCommand("undo", context),
@@ -84,6 +126,10 @@ 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) => {
@@ -130,4 +176,10 @@ 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.1.2",
 	"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

@@ -108,6 +108,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>;
@@ -175,6 +177,10 @@ 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.locked || this.operationInFlight) return { action: "handled" };
 		if (context.streaming || text.length === 0) return { action: "continue" };

package/src/diff-ui.ts

@@ -0,0 +1,116 @@
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { renderDiff } from "@earendil-works/pi-coding-agent";
+import { type Component, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import { buildFileLabel, type FileDiff, sanitizeDisplayText } from "./diff-view.ts";
+
+const CLOSE_LABEL = "← Close";
+
+/**
+ * 在 TUI 中交互浏览一次 Agent run 的逐文件 diff：
+ * 上层 select 列出改动文件，选中后用可滚动彩色查看器展示该文件 diff，返回后回到列表。
+ */
+export async function browseDiff(context: ExtensionCommandContext, title: string, diffs: readonly FileDiff[]): Promise<void> {
+	const labels = new Map<string, FileDiff>();
+	const options: string[] = [];
+	for (const diff of diffs) {
+		const label = uniqueLabel(buildFileLabel(diff), labels);
+		labels.set(label, diff);
+		options.push(label);
+	}
+	options.push(CLOSE_LABEL);
+
+	for (;;) {
+		const choice = await context.ui.select(title, options);
+		if (choice === undefined || choice === CLOSE_LABEL) return;
+		const diff = labels.get(choice);
+		if (diff === undefined) return;
+		await showFileDiff(context, diff);
+	}
+}
+
+function uniqueLabel(label: string, used: ReadonlyMap<string, FileDiff>): string {
+	if (!used.has(label)) return label;
+	let index = 2;
+	while (used.has(`${label} (${index})`)) index += 1;
+	return `${label} (${index})`;
+}
+
+async function showFileDiff(context: ExtensionCommandContext, diff: FileDiff): Promise<void> {
+	await context.ui.custom<void>((tui, theme, _keybindings, done) => new DiffViewer(tui, theme, diff, done), {
+		overlay: true,
+		overlayOptions: { width: "90%", maxHeight: "90%" },
+	});
+}
+
+/** 只读、可滚动的单文件 diff 查看器；不修改任何会话或存储状态。 */
+class DiffViewer implements Component {
+	private readonly lines: readonly string[];
+	private offset = 0;
+
+	constructor(
+		private readonly tui: { requestRender(force?: boolean): void },
+		private readonly theme: Theme,
+		private readonly diff: FileDiff,
+		private readonly done: (result: void) => void,
+	) {
+		this.lines = this.buildLines();
+	}
+
+	invalidate(): void {}
+
+	private buildLines(): string[] {
+		if (this.diff.kind === "binary") return [this.theme.fg("dim", "Binary file changed; line-by-line diff unavailable.")];
+		if (this.diff.diff === "") return [this.theme.fg("dim", "No textual change (mode or type only).")];
+		return renderDiff(this.diff.diff).split("\n");
+	}
+
+	private viewportRows(): number {
+		const rows = process.stdout.rows ?? 24;
+		// 预留 overlay 边框、标题、footer 的空间。
+		return Math.max(3, Math.min(this.lines.length, rows - 8));
+	}
+
+	private maxOffset(): number {
+		return Math.max(0, this.lines.length - this.viewportRows());
+	}
+
+	handleInput(data: string): void {
+		const rows = this.viewportRows();
+		const previous = this.offset;
+		if (matchesKey(data, "escape") || matchesKey(data, "q") || matchesKey(data, "enter")) {
+			this.done();
+			return;
+		}
+		if (matchesKey(data, "up") || matchesKey(data, "k")) this.offset -= 1;
+		else if (matchesKey(data, "down") || matchesKey(data, "j")) this.offset += 1;
+		else if (matchesKey(data, "pageUp")) this.offset -= rows;
+		else if (matchesKey(data, "pageDown") || matchesKey(data, "space")) this.offset += rows;
+		else if (matchesKey(data, "home") || matchesKey(data, "g")) this.offset = 0;
+		else if (matchesKey(data, "end") || matchesKey(data, "shift+g")) this.offset = this.maxOffset();
+		this.offset = Math.max(0, Math.min(this.maxOffset(), this.offset));
+		if (this.offset !== previous) this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		const rows = this.viewportRows();
+		// 终端 resize 会改变 viewportRows，重绘时必须重新夹紧滚动位置。
+		this.offset = Math.max(0, Math.min(this.maxOffset(), this.offset));
+		const stats = this.diff.kind === "binary"
+			? "binary"
+			: `+${this.diff.additions} -${this.diff.deletions}`;
+		const safePath = sanitizeDisplayText(this.diff.path, 240);
+		const header = truncateToWidth(this.theme.fg("accent", `${this.diff.status.toUpperCase()} ${safePath}`) + this.theme.fg("dim", `  ${stats}`), width);
+		const out: string[] = [header, this.theme.fg("borderMuted", "─".repeat(Math.min(width, 80)))];
+		const visible = this.lines.slice(this.offset, this.offset + rows);
+		for (const line of visible) {
+			out.push(visibleWidth(line) > width ? truncateToWidth(line, width) : line);
+		}
+		for (let index = visible.length; index < rows; index += 1) out.push("");
+		const position = this.lines.length <= rows
+			? "all"
+			: `${this.offset + 1}-${Math.min(this.offset + rows, this.lines.length)}/${this.lines.length}`;
+		out.push(this.theme.fg("dim", `↑↓/PgUp/PgDn scroll · ${position} · Esc/q close`));
+		return out;
+	}
+}

package/src/diff-view.ts

@@ -0,0 +1,169 @@
+import { generateDiffString } from "@earendil-works/pi-coding-agent";
+
+import type { ManifestId, RestorePath, SnapshotManifest } from "./model.ts";
+
+/** SnapshotStore 的只读子集；/diff 只需要读取 manifest 与 blob，不触碰任何恢复路径。 */
+export interface DiffSource {
+	loadManifest(id: ManifestId): Promise<SnapshotManifest>;
+	listTree(id: ManifestId, root: string): Promise<readonly RestorePath[]>;
+	readBlob(id: ManifestId, root: string, blobId: string): Promise<Uint8Array>;
+}
+
+export type FileDiffStatus = "added" | "deleted" | "modified";
+export type FileDiffKind = "text" | "binary" | "symlink";
+
+export interface FileDiff {
+	readonly path: string;
+	readonly status: FileDiffStatus;
+	readonly kind: FileDiffKind;
+	readonly additions: number;
+	readonly deletions: number;
+	/** 带行号的展示 diff；二进制文件或无逐行差异时为空字符串。 */
+	readonly diff: string;
+}
+
+export interface CheckpointDiffRequest {
+	readonly beforeManifestId: ManifestId;
+	readonly afterManifestId: ManifestId;
+	readonly changedPaths: readonly string[];
+}
+
+interface LeafEntry {
+	readonly rootPath: string;
+	readonly entry: RestorePath;
+}
+
+interface LeafContent {
+	readonly binary: boolean;
+	readonly symlink: boolean;
+	readonly text: string;
+}
+
+/**
+ * 基于 checkpoint 的 before/after 快照计算逐文件 diff。
+ * changedPaths 中的目录项与两侧都不存在的路径会被跳过，只保留叶子文件与符号链接。
+ */
+export async function computeCheckpointDiff(
+	source: DiffSource,
+	request: CheckpointDiffRequest,
+): Promise<FileDiff[]> {
+	const [before, after] = await Promise.all([
+		source.loadManifest(request.beforeManifestId),
+		source.loadManifest(request.afterManifestId),
+	]);
+	const [beforePaths, afterPaths] = await Promise.all([
+		readLeafEntries(source, before),
+		readLeafEntries(source, after),
+	]);
+
+	const result: FileDiff[] = [];
+	for (const path of request.changedPaths) {
+		const beforeLeaf = beforePaths.get(path);
+		const afterLeaf = afterPaths.get(path);
+		if (beforeLeaf === undefined && afterLeaf === undefined) continue;
+		const status: FileDiffStatus = beforeLeaf === undefined
+			? "added"
+			: afterLeaf === undefined ? "deleted" : "modified";
+		const beforeContent = beforeLeaf === undefined
+			? emptyContent()
+			: await readLeafContent(source, request.beforeManifestId, beforeLeaf);
+		const afterContent = afterLeaf === undefined
+			? emptyContent()
+			: await readLeafContent(source, request.afterManifestId, afterLeaf);
+		if (beforeContent.binary || afterContent.binary) {
+			result.push({ path, status, kind: "binary", additions: 0, deletions: 0, diff: "" });
+			continue;
+		}
+		const kind: FileDiffKind = beforeContent.symlink || afterContent.symlink ? "symlink" : "text";
+		const { diff } = generateDiffString(beforeContent.text, afterContent.text);
+		result.push({ path, status, kind, ...countChanges(diff), diff });
+	}
+	return result;
+}
+
+async function readLeafEntries(source: DiffSource, manifest: SnapshotManifest): Promise<Map<string, LeafEntry>> {
+	const result = new Map<string, LeafEntry>();
+	for (const root of manifest.roots) {
+		if (root.state !== "active" || root.treeId === null) continue;
+		for (const entry of await source.listTree(manifest.manifestId, root.relativeRoot)) {
+			if (entry.kind === "directory") continue;
+			const path = root.relativeRoot === "." ? entry.relativePath : `${root.relativeRoot}/${entry.relativePath}`;
+			if (!result.has(path)) result.set(path, { rootPath: root.relativeRoot, entry });
+		}
+	}
+	return result;
+}
+
+async function readLeafContent(source: DiffSource, manifestId: ManifestId, leaf: LeafEntry): Promise<LeafContent> {
+	if (leaf.entry.kind === "symlink") {
+		return { binary: false, symlink: true, text: sanitizeDiffContent(leaf.entry.linkText ?? "") };
+	}
+	if (leaf.entry.blobId === null) {
+		return { binary: true, symlink: false, text: "" };
+	}
+	const bytes = await source.readBlob(manifestId, leaf.rootPath, leaf.entry.blobId);
+	const text = decodeLossless(bytes);
+	return text === null
+		? { binary: true, symlink: false, text: "" }
+		: { binary: false, symlink: false, text: sanitizeDiffContent(text) };
+}
+
+function emptyContent(): LeafContent {
+	return { binary: false, symlink: false, text: "" };
+}
+
+function decodeLossless(bytes: Uint8Array): string | null {
+	if (bytes.includes(0)) return null;
+	const buffer = Buffer.from(bytes);
+	const text = buffer.toString("utf8");
+	return Buffer.from(text, "utf8").equals(buffer) ? text : null;
+}
+
+function sanitizeDiffContent(text: string): string {
+	return text
+		.replace(/\x1B/g, "[ESC]")
+		.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001A\u001C-\u001F\u007F]/g, "?");
+}
+
+function countChanges(diff: string): { additions: number; deletions: number } {
+	let additions = 0;
+	let deletions = 0;
+	for (const line of diff.split("\n")) {
+		if (line.startsWith("+")) additions += 1;
+		else if (line.startsWith("-")) deletions += 1;
+	}
+	return { additions, deletions };
+}
+
+const STATUS_CHAR: Record<FileDiffStatus, string> = { added: "A", deleted: "D", modified: "M" };
+
+/** 单个文件的一行摘要，用于文件清单与非 TUI 降级展示。 */
+export function buildFileLabel(diff: FileDiff): string {
+	const stats = diff.kind === "binary"
+		? "(binary)"
+		: diff.additions === 0 && diff.deletions === 0 ? "(no textual change)" : `+${diff.additions} -${diff.deletions}`;
+	return `${STATUS_CHAR[diff.status]} ${sanitizeDisplayText(diff.path, 240)}  ${stats}`;
+}
+
+/** 整个 checkpoint 的一行摘要，用于非 TUI 模式的 notify。 */
+export function formatDiffSummary(diffs: readonly FileDiff[]): string {
+	let additions = 0;
+	let deletions = 0;
+	for (const diff of diffs) {
+		additions += diff.additions;
+		deletions += diff.deletions;
+	}
+	const paths = diffs.map((diff) => sanitizeDisplayText(diff.path, 160)).join(", ");
+	return sanitizeDisplayText(`${diffs.length} file(s), +${additions} -${deletions}: ${paths}`, 500);
+}
+
+/** 清理可能进入终端 UI 的外部文本，避免 ANSI/控制序列注入。 */
+export function sanitizeDisplayText(value: string, maxLength = 200): string {
+	return value
+		.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "")
+		.replace(/\x1B\][^\u0007]*(?:\u0007|\x1B\\)/g, "")
+		.replace(/[\u0000-\u001F\u007F]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, maxLength);
+}

package/src/pi-runtime.ts

@@ -154,6 +154,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 	return {
 		controller,
 		reporter: new StatusReporter(context),
+		diffSource: store,
 		recovery: startupRecovery.kind === "locked"
 			? { files: startupRecovery.files, opId: startupRecovery.opId }
 			: undefined,

package/src/restore-engine.ts

@@ -22,6 +22,8 @@ import {
 } from "./quarantine.ts";
 import { SnapshotStoreError, type SnapshotStore } from "./snapshot-store.ts";
 
+const PREPARED_PLAN_CACHE_LIMIT = 16;
+
 export interface RestorePlan {
 	currentManifestId: ManifestId;
 	targetManifestId: ManifestId;
@@ -69,6 +71,12 @@ interface OwnedPath {
 	readonly root: SnapshotRoot;
 }
 
+interface PreparedRestorePlan {
+	readonly plan: RestorePlan;
+	readonly currentPaths: ReadonlyMap<string, OwnedPath>;
+	readonly targetPaths: ReadonlyMap<string, OwnedPath>;
+}
+
 interface MutationContext {
 	readonly phase: RestoreMutation["phase"];
 	readonly sourceManifestId: ManifestId;
@@ -88,6 +96,7 @@ export class RestoreEngine {
 	private readonly store: SnapshotStore;
 	private readonly discovery: RootDiscovery;
 	private readonly beforeMutation: RestoreEngineOptions["beforeMutation"];
+	private readonly preparedPlans = new Map<string, PreparedRestorePlan>();
 
 	constructor(options: RestoreEngineOptions) {
 		this.requestedWorkspaceRoot = resolve(options.workspaceRoot);
@@ -174,10 +183,33 @@ export class RestoreEngine {
 			writePaths,
 			...(scope === undefined ? {} : { scopePaths: [...scope] }),
 		};
-		return {
+		const plan = {
 			...semanticPlan,
 			planDigest: checksum(canonicalJson(semanticPlan)),
 		};
+		this.rememberPreparedPlan(plan, currentPaths, targetPaths);
+		return plan;
+	}
+
+	private rememberPreparedPlan(
+		plan: RestorePlan,
+		currentPaths: ReadonlyMap<string, OwnedPath>,
+		targetPaths: ReadonlyMap<string, OwnedPath>,
+	): void {
+		const cachedPlan = cloneRestorePlan(plan);
+		this.preparedPlans.set(preparedPlanKey(cachedPlan), { plan: cachedPlan, currentPaths, targetPaths });
+		while (this.preparedPlans.size > PREPARED_PLAN_CACHE_LIMIT) {
+			const oldest = this.preparedPlans.keys().next().value as string | undefined;
+			if (oldest === undefined) break;
+			this.preparedPlans.delete(oldest);
+		}
+	}
+
+	private takePreparedPlan(plan: RestorePlan): PreparedRestorePlan | undefined {
+		const key = preparedPlanKey(plan);
+		const prepared = this.preparedPlans.get(key);
+		if (prepared !== undefined) this.preparedPlans.delete(key);
+		return prepared;
 	}
 
 	async apply(
@@ -285,8 +317,10 @@ export class RestoreEngine {
 		}
 		assertCompatibleManifests(current, target);
 		let expectedPlan: RestorePlan;
+		let prepared: PreparedRestorePlan | undefined;
 		try {
 			expectedPlan = await this.plan(current, target, plan.scopePaths);
+			prepared = this.takePreparedPlan(expectedPlan);
 		} catch (error) {
 			if (error instanceof SnapshotStoreError && error.code === "object_missing") {
 				return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
@@ -307,10 +341,9 @@ export class RestoreEngine {
 		} catch {
 			return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
 		}
-		const [currentPaths, targetPaths] = await Promise.all([
-			this.readOwnedPaths(current),
-			this.readOwnedPaths(target),
-		]);
+		const [currentPaths, targetPaths] = prepared === undefined
+			? await Promise.all([this.readOwnedPaths(current), this.readOwnedPaths(target)])
+			: [prepared.currentPaths, prepared.targetPaths];
 		const quarantine = new QuarantineManager({
 			workspaceRoot: this.requestedWorkspaceRoot,
 			journal: options.mutationJournal,
@@ -817,12 +850,11 @@ export class RestoreEngine {
 			}
 		}
 
-		const live = await this.store.capture(topology, undefined, {
+		const livePaths = await this.store.listVisibleLeafPaths(topology, {
 			excludePaths: mutationJournal === undefined ? undefined : [...await mutationJournal.activeArtifacts()],
 		});
-		await this.store.assertComplete(live.manifestId);
-		for (const [path, owned] of await this.readOwnedPaths(live)) {
-			if (owned.entry.kind !== "directory" && !allowedPaths.has(path)) {
+		for (const path of livePaths) {
+			if (!allowedPaths.has(path)) {
 				throw new Error(`complete coverage 发现 manifest 集合外路径：${path}`);
 			}
 		}
@@ -1025,6 +1057,22 @@ export class RestoreEngine {
 	}
 }
 
+function preparedPlanKey(plan: RestorePlan): string {
+	return `${plan.currentManifestId}\0${plan.targetManifestId}\0${plan.planDigest}`;
+}
+
+function cloneRestorePlan(plan: RestorePlan): RestorePlan {
+	return {
+		currentManifestId: plan.currentManifestId,
+		targetManifestId: plan.targetManifestId,
+		boundaryRoots: [...plan.boundaryRoots],
+		deletePaths: [...plan.deletePaths],
+		writePaths: [...plan.writePaths],
+		...(plan.scopePaths === undefined ? {} : { scopePaths: [...plan.scopePaths] }),
+		planDigest: plan.planDigest,
+	};
+}
+
 function sameEntry(left: RestorePath, right: RestorePath): boolean {
 	return left.kind === right.kind &&
 		left.mode === right.mode &&

package/src/root-discovery.ts

@@ -5,6 +5,8 @@ import { checksum, topologyFingerprint } from "./encoding.ts";
 import { GitRunner } from "./git-runner.ts";
 import type { DiscoveryRoot } from "./model.ts";
 
+const DIRECTORY_SCAN_CONCURRENCY = 16;
+
 interface RepositoryInfo {
 	readonly absoluteRoot: string;
 	readonly commonGitDir: string;
@@ -87,22 +89,27 @@ export class RootDiscovery {
 		directory: string,
 		activeRoots: Map<string, DiscoveredRoot>,
 	): Promise<void> {
-		if (!await isSafeDirectory(directory, workspaceIdentity)) {
-			return;
-		}
-		const entries = await readdir(directory, { withFileTypes: true });
-		if (!await isSafeDirectory(directory, workspaceIdentity)) {
-			return;
-		}
-		for (const entry of entries) {
-			if (entry.name === ".git" || entry.isSymbolicLink() || !entry.isDirectory()) {
-				continue;
-			}
-			const candidate = join(directory, entry.name);
-			if (!await isSafeDirectory(candidate, workspaceIdentity)) {
-				continue;
+		let level: Array<{ readonly path: string; readonly inspect: boolean }> = [{ path: directory, inspect: false }];
+		while (level.length > 0) {
+			const next: Array<{ readonly path: string; readonly inspect: true }> = [];
+			for (let index = 0; index < level.length; index += DIRECTORY_SCAN_CONCURRENCY) {
+				const children = await Promise.all(level.slice(index, index + DIRECTORY_SCAN_CONCURRENCY).map(
+					(candidate) => this.scanDirectoryNode(workspaceIdentity, candidate, activeRoots),
+				));
+				for (const group of children) next.push(...group);
 			}
-			const inspection = await this.inspectRepository(candidate, workspaceIdentity);
+			level = next;
+		}
+	}
+
+	private async scanDirectoryNode(
+		workspaceIdentity: string,
+		candidate: { readonly path: string; readonly inspect: boolean },
+		activeRoots: Map<string, DiscoveredRoot>,
+	): Promise<Array<{ readonly path: string; readonly inspect: true }>> {
+		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
+		if (candidate.inspect) {
+			const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
 			if (inspection.kind === "active") {
 				activeRoots.set(
 					inspection.repository.absoluteRoot,
@@ -111,8 +118,13 @@ export class RootDiscovery {
 			} else if (inspection.kind === "broken") {
 				activeRoots.set(inspection.absoluteRoot, brokenRoot(workspaceIdentity, inspection.absoluteRoot));
 			}
-			await this.scanDirectory(workspaceIdentity, candidate, activeRoots);
+			if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		}
+		const entries = await readdir(candidate.path, { withFileTypes: true });
+		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
+		return entries
+			.filter((entry) => entry.name !== ".git" && !entry.isSymbolicLink() && entry.isDirectory())
+			.map((entry) => ({ path: join(candidate.path, entry.name), inspect: true as const }));
 	}
 
 	private async inspectRepository(candidate: string, workspaceIdentity: string): Promise<RepositoryInspection> {

package/src/snapshot-store.ts

@@ -1,3 +1,4 @@
+import type { Stats } from "node:fs";
 import { lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -30,6 +31,11 @@ const GC_METADATA_FILE = "gc.json";
 const GC_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
 const IGNORE_POLICY = "git-check-ignore-v1";
 const NULL_DEVICE = process.platform === "win32" ? "NUL" : "/dev/null";
+const TREE_CACHE_LIMIT = 256;
+const HASH_BATCH_MAX_PATHS = 128;
+const HASH_BATCH_MAX_ARGUMENT_BYTES = 24 * 1024;
+const INDEX_BATCH_MAX_ENTRIES = 4_096;
+const INDEX_BATCH_MAX_BYTES = 8 * 1024 * 1024;
 
 interface PinRecord {
 	readonly schemaVersion: 1;
@@ -60,6 +66,13 @@ interface CapturedRootResult {
 	readonly objectClosure: string;
 }
 
+interface VisibleLeaf {
+	readonly relativePath: string;
+	readonly kind: "file" | "symlink";
+	readonly mode: number;
+	readonly fingerprint: string;
+}
+
 export interface SnapshotStoreOptions {
 	readonly storeRoot?: string;
 	readonly git?: GitRunner;
@@ -93,6 +106,7 @@ export class SnapshotStoreError extends Error {
 
 export interface SnapshotStore {
 	capture(topology: RootTopology, scope?: readonly string[], options?: CaptureOptions): Promise<SnapshotManifest>;
+	listVisibleLeafPaths(topology: RootTopology, options?: CaptureOptions): Promise<readonly string[]>;
 	loadManifest(id: ManifestId): Promise<SnapshotManifest>;
 	assertComplete(id: ManifestId): Promise<void>;
 	listTree(id: ManifestId, root: string): Promise<readonly RestorePath[]>;
@@ -110,6 +124,8 @@ export class SnapshotStore {
 	private readonly lock: WorkspaceLock;
 	private readonly clock: () => number;
 	private readonly manifestLocations = new Map<string, string>();
+	// Tree ID 是内容寻址且不可变；这里只缓存解析元数据，blob bytes 与完整性仍逐次读取/校验。
+	private readonly treeEntriesCache = new Map<string, Promise<CapturedTreeEntry[]>>();
 
 	constructor(options: SnapshotStoreOptions = {}) {
 		this.storeRoot = resolve(options.storeRoot ?? join(tmpdir(), "pi-undo-snapshot-store"));
@@ -204,6 +220,72 @@ export class SnapshotStore {
 		}
 	}
 
+	async listVisibleLeafPaths(
+		topology: RootTopology,
+		options: CaptureOptions = {},
+	): Promise<readonly string[]> {
+		await this.assertPrivateStore(topology.workspaceIdentity);
+		const lockIdentity = `snapshot-store:${await prospectiveCanonicalPath(this.storesRoot)}`;
+		return this.lock.withLock(lockIdentity, () => this.listVisibleLeafPathsLocked(topology, options));
+	}
+
+	private async listVisibleLeafPathsLocked(
+		topology: RootTopology,
+		options: CaptureOptions,
+	): Promise<readonly string[]> {
+		let transactionDirectory: string | undefined;
+		try {
+			if (topology.fingerprint !== topologyFingerprint(topology.workspaceIdentity, topology.roots)) {
+				throw new SnapshotStoreError("capture_failed", "topology fingerprint 与 roots 不匹配");
+			}
+			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 storeDirectory = this.storeDirectory(topology);
+			const transactionsRoot = join(storeDirectory, "transactions");
+			await mkdir(transactionsRoot, { recursive: true });
+			transactionDirectory = await mkdtemp(join(transactionsRoot, "visible-"));
+			const result = new Set<string>();
+			for (const root of topology.roots) {
+				if (root.state !== "active") continue;
+				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
+				await this.ensurePrivateRepository(gitDirectory);
+				await this.assertNoAlternates(gitDirectory);
+				const absoluteRoot = workspaceRootPath(topology.workspaceIdentity, root.relativeRoot);
+				const indexPath = join(transactionDirectory, `${rootStoreId(root)}.index`);
+				const environment = privateGitEnvironment(gitDirectory, absoluteRoot, indexPath);
+				await this.runGit(["read-tree", "--empty"], { cwd: absoluteRoot, env: environment });
+				await this.validateIgnoreQuery(absoluteRoot, environment, root.gitBacked);
+				const exclusions = topology.roots
+					.filter((candidate) => isStrictRootAncestor(root.relativeRoot, candidate.relativeRoot))
+					.map((candidate) => rootRelativePath(root.relativeRoot, candidate.relativeRoot));
+				const exactExclusions = ownedArtifactExclusions(topology.roots, root.relativeRoot, artifactExclusions);
+				for (const leaf of await this.collectVisibleLeaves(
+					absoluteRoot,
+					environment,
+					root.gitBacked,
+					[],
+					exclusions,
+					exactExclusions,
+				)) {
+					result.add(workspaceRelativePath(root.relativeRoot, leaf.relativePath));
+				}
+			}
+			await this.assertTopology(topology, "可见路径枚举期间 topology 已变化");
+			return [...result].sort(comparePaths);
+		} catch (error) {
+			if (error instanceof SnapshotStoreError) throw error;
+			throw new SnapshotStoreError("capture_failed", errorMessage(error), { cause: error });
+		} finally {
+			if (transactionDirectory !== undefined) {
+				await rm(transactionDirectory, { recursive: true, force: true }).catch(() => {});
+			}
+		}
+	}
+
 	async loadManifest(id: ManifestId): Promise<SnapshotManifest> {
 		const manifestPath = await this.findManifestPath(id);
 		try {
@@ -242,7 +324,6 @@ export class SnapshotStore {
 				}
 				const gitDirectory = this.rootGitDirectory(storeDirectory, root);
 				await this.assertNoAlternates(gitDirectory);
-				await this.runPrivateGit(gitDirectory, ["cat-file", "-e", `${root.treeId}^{tree}`]);
 				const entries = await this.readTreeEntries(gitDirectory, root.treeId);
 				if (root.ignoredPresentPaths.some((ignoredPath) => entries.some(
 					(entry) => isPathAtOrBelow(ignoredPath, entry.relativePath) ||
@@ -250,9 +331,7 @@ export class SnapshotStore {
 				))) {
 					throw new SnapshotStoreError("object_missing", "ignored-present proof 与 root tree 冲突");
 				}
-				for (const entry of entries) {
-					await this.runPrivateGit(gitDirectory, ["cat-file", "-e", `${entry.objectId}^{blob}`]);
-				}
+				await this.assertObjectsComplete(gitDirectory, root.treeId, entries);
 				if (root.objectClosure !== treeObjectClosure(root.treeId, entries)) {
 					throw new SnapshotStoreError("object_missing", "root tree 对象闭包校验失败");
 				}
@@ -493,10 +572,7 @@ export class SnapshotStore {
 			throw new SnapshotStoreError("capture_failed", "git write-tree 未返回有效对象 ID");
 		}
 		const entries = await this.readTreeEntries(gitDirectory, treeId);
-		await this.runPrivateGit(gitDirectory, ["cat-file", "-e", `${treeId}^{tree}`]);
-		for (const entry of entries) {
-			await this.runPrivateGit(gitDirectory, ["cat-file", "-e", `${entry.objectId}^{blob}`]);
-		}
+		await this.assertObjectsComplete(gitDirectory, treeId, entries);
 		return {
 			treeId,
 			coverage,
@@ -565,13 +641,77 @@ export class SnapshotStore {
 		exclusions: readonly string[],
 		exactExclusions: readonly string[],
 	): Promise<void> {
-		if (inclusions === null) {
-			return;
+		const leaves = await this.collectVisibleLeaves(
+			cwd,
+			environment,
+			gitBacked,
+			inclusions,
+			exclusions,
+			exactExclusions,
+		);
+		const objectIds = new Map<string, string>();
+		for (const batch of hashPathBatches(leaves.filter((leaf) => leaf.kind === "file"))) {
+			for (const leaf of batch) await this.assertVisibleLeafUnchanged(cwd, leaf);
+			const output = await this.runGit([
+				"hash-object",
+				"-w",
+				"--no-filters",
+				"--",
+				...batch.map((leaf) => leaf.relativePath),
+			], { cwd, env: environment });
+			const hashes = parseObjectIdLines(output, batch.length);
+			for (const leaf of batch) await this.assertVisibleLeafUnchanged(cwd, leaf);
+			for (let index = 0; index < batch.length; index += 1) {
+				objectIds.set(batch[index]!.relativePath, hashes[index]!);
+			}
 		}
-		const pathspecs = inclusions.length === 0 ? ["."] : inclusions.map(literalPathspec);
-		for (const excluded of exclusions) {
-			pathspecs.push(excludeLiteralPathspec(excluded));
+		for (const leaf of leaves) {
+			if (leaf.kind !== "symlink") continue;
+			await this.assertVisibleLeafUnchanged(cwd, leaf);
+			const linkText = await readlink(join(cwd, ...leaf.relativePath.split("/")), { encoding: "buffer" });
+			decodeUtf8(linkText, "symlink target 不是可无损表示的 UTF-8");
+			const objectId = (await this.runGit(["hash-object", "-w", "--stdin"], {
+				cwd,
+				env: environment,
+				stdin: linkText,
+			})).trim();
+			if (!isObjectId(objectId)) {
+				throw new SnapshotStoreError("capture_failed", `文件对象 materialize 失败：${leaf.relativePath}`);
+			}
+			await this.assertVisibleLeafUnchanged(cwd, leaf);
+			objectIds.set(leaf.relativePath, objectId);
+		}
+		for (const indexInput of indexInfoBatches(leaves, objectIds)) {
+			await this.runGit(["update-index", "-z", "--index-info"], {
+				cwd,
+				env: environment,
+				stdin: indexInput,
+			});
+		}
+	}
+
+	private async assertVisibleLeafUnchanged(cwd: string, leaf: VisibleLeaf): Promise<void> {
+		await assertNoSymlinkEscape(cwd, leaf.relativePath);
+		const metadata = await lstat(join(cwd, ...leaf.relativePath.split("/"))).catch((error) => {
+			if (hasErrorCode(error, "ENOENT")) return null;
+			throw error;
+		});
+		if (metadata === null || visibleLeafFingerprint(metadata) !== leaf.fingerprint) {
+			throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化：${leaf.relativePath}`);
 		}
+	}
+
+	private async collectVisibleLeaves(
+		cwd: string,
+		environment: Readonly<Record<string, string | undefined>>,
+		gitBacked: boolean,
+		inclusions: readonly string[] | null,
+		exclusions: readonly string[],
+		exactExclusions: readonly string[],
+	): Promise<VisibleLeaf[]> {
+		if (inclusions === null) return [];
+		const pathspecs = inclusions.length === 0 ? ["."] : inclusions.map(literalPathspec);
+		for (const excluded of exclusions) pathspecs.push(excludeLiteralPathspec(excluded));
 		const queryEnvironment = gitBacked ? sourceGitEnvironment() : environment;
 		const output = await this.runGitBytes([
 			...(gitBacked ? ["-c", "core.fsmonitor=false"] : []),
@@ -583,53 +723,38 @@ export class SnapshotStore {
 			"--",
 			...pathspecs,
 		], { cwd, env: queryEnvironment });
+		const result: VisibleLeaf[] = [];
 		for (const relativePath of parseNulPaths(output)) {
 			if (
 				exclusions.some((excluded) => isPathAtOrBelow(excluded, relativePath)) ||
 				exactExclusions.includes(relativePath)
-			) {
-				continue;
-			}
+			) continue;
 			relativeSafePath(cwd, relativePath);
 			await assertNoSymlinkEscape(cwd, relativePath);
-			const absolutePath = join(cwd, ...relativePath.split("/"));
-			const metadata = await lstat(absolutePath).catch((error) => {
-				if (hasErrorCode(error, "ENOENT")) {
-					return null;
-				}
+			const metadata = await lstat(join(cwd, ...relativePath.split("/"))).catch((error) => {
+				if (hasErrorCode(error, "ENOENT")) return null;
 				throw error;
 			});
-			if (metadata === null) {
-				continue;
-			}
-			let mode: string;
-			let objectId: string;
+			if (metadata === null) continue;
 			if (metadata.isSymbolicLink()) {
-				mode = "120000";
-				const linkText = await readlink(absolutePath, { encoding: "buffer" });
-				decodeUtf8(linkText, "symlink target 不是可无损表示的 UTF-8");
-				objectId = (await this.runGit(["hash-object", "-w", "--stdin"], {
-					cwd,
-					env: environment,
-					stdin: linkText,
-				})).trim();
+				result.push({
+					relativePath,
+					kind: "symlink",
+					mode: 0o120000,
+					fingerprint: visibleLeafFingerprint(metadata),
+				});
 			} else if (metadata.isFile()) {
-				mode = (metadata.mode & 0o111) === 0 ? "100644" : "100755";
-				objectId = (await this.runGit(["hash-object", "-w", "--no-filters", "--", relativePath], {
-					cwd,
-					env: environment,
-				})).trim();
+				result.push({
+					relativePath,
+					kind: "file",
+					mode: (metadata.mode & 0o111) === 0 ? 0o100644 : 0o100755,
+					fingerprint: visibleLeafFingerprint(metadata),
+				});
 			} else {
 				throw new SnapshotStoreError("capture_failed", `不支持的工作区文件类型：${relativePath}`);
 			}
-			if (!isObjectId(objectId)) {
-				throw new SnapshotStoreError("capture_failed", `文件对象 materialize 失败：${relativePath}`);
-			}
-			await this.runGit(["update-index", "--add", "--cacheinfo", mode, objectId, relativePath], {
-				cwd,
-				env: environment,
-			});
 		}
+		return result;
 	}
 
 	private async validateIgnoreQuery(
@@ -688,8 +813,52 @@ export class SnapshotStore {
 	}
 
 	private async readTreeEntries(gitDirectory: string, treeId: string): Promise<CapturedTreeEntry[]> {
-		const output = await this.runPrivateGitBytes(gitDirectory, ["ls-tree", "-r", "-l", "-z", treeId]);
-		return parseTreeEntries(output);
+		const key = `${gitDirectory}\0${treeId}`;
+		const cached = this.treeEntriesCache.get(key);
+		if (cached !== undefined) return cached;
+		const pending = this.runPrivateGitBytes(gitDirectory, ["ls-tree", "-r", "-l", "-z", treeId])
+			.then(parseTreeEntries);
+		this.treeEntriesCache.set(key, pending);
+		while (this.treeEntriesCache.size > TREE_CACHE_LIMIT) {
+			const oldest = this.treeEntriesCache.keys().next().value as string | undefined;
+			if (oldest === undefined || oldest === key) break;
+			this.treeEntriesCache.delete(oldest);
+		}
+		try {
+			return await pending;
+		} catch (error) {
+			if (this.treeEntriesCache.get(key) === pending) this.treeEntriesCache.delete(key);
+			throw error;
+		}
+	}
+
+	private async assertObjectsComplete(
+		gitDirectory: string,
+		treeId: string,
+		entries: readonly CapturedTreeEntry[],
+	): Promise<void> {
+		const expected = [
+			{ objectId: treeId, type: "tree" },
+			...[...new Set(entries.map((entry) => entry.objectId))].map((objectId) => ({ objectId, type: "blob" })),
+		];
+		const output = await this.runGit(["cat-file", "--batch-check"], {
+			env: privateObjectEnvironment(gitDirectory),
+			stdin: `${expected.map((object) => object.objectId).join("\n")}\n`,
+		});
+		const lines = output.endsWith("\n") ? output.slice(0, -1).split("\n") : output.split("\n");
+		if (lines.length !== expected.length) throw new Error("Git object batch-check 输出数量不匹配");
+		for (let index = 0; index < expected.length; index += 1) {
+			const object = expected[index]!;
+			const match = lines[index]!.match(/^([0-9a-f]{40,64}) (blob|tree) ([0-9]+)$/);
+			if (
+				match === null ||
+				match[1] !== object.objectId ||
+				match[2] !== object.type ||
+				!Number.isSafeInteger(Number(match[3]))
+			) {
+				throw new Error(`Git object batch-check 校验失败：${object.objectId}`);
+			}
+		}
 	}
 
 	private async readBlobText(gitDirectory: string, objectId: string): Promise<string> {
@@ -980,6 +1149,10 @@ function workspaceRootPath(workspaceIdentity: string, rootPath: string): string
 	return safe === "." ? workspaceIdentity : join(workspaceIdentity, ...safe.split("/"));
 }
 
+function workspaceRelativePath(rootPath: string, relativePath: string): string {
+	return rootPath === "." ? relativePath : `${rootPath}/${relativePath}`;
+}
+
 function rootStoreId(root: RootTopologyIdentity): string {
 	return checksum(canonicalJson({
 		relativeRoot: root.relativeRoot,
@@ -1061,6 +1234,76 @@ function isolatedGitConfiguration(): Readonly<Record<string, string | undefined>
 	};
 }
 
+function indexInfoBatches(
+	leaves: readonly VisibleLeaf[],
+	objectIds: ReadonlyMap<string, string>,
+): Buffer[] {
+	const result: Buffer[] = [];
+	let records: string[] = [];
+	let bytes = 0;
+	for (const leaf of leaves) {
+		const objectId = objectIds.get(leaf.relativePath);
+		if (objectId === undefined) {
+			throw new SnapshotStoreError("capture_failed", `文件对象 materialize 结果缺失：${leaf.relativePath}`);
+		}
+		const record = `${leaf.mode.toString(8)} ${objectId}\t${leaf.relativePath}\0`;
+		const recordBytes = Buffer.byteLength(record, "utf8");
+		if (
+			records.length > 0 &&
+			(records.length >= INDEX_BATCH_MAX_ENTRIES || bytes + recordBytes > INDEX_BATCH_MAX_BYTES)
+		) {
+			result.push(Buffer.from(records.join(""), "utf8"));
+			records = [];
+			bytes = 0;
+		}
+		records.push(record);
+		bytes += recordBytes;
+	}
+	if (records.length > 0) result.push(Buffer.from(records.join(""), "utf8"));
+	return result;
+}
+
+function visibleLeafFingerprint(metadata: Stats): string {
+	return checksum(canonicalJson({
+		kind: metadata.isSymbolicLink() ? "symlink" : metadata.isFile() ? "file" : "other",
+		dev: metadata.dev,
+		ino: metadata.ino,
+		mode: metadata.mode,
+		size: metadata.size,
+		mtimeMs: metadata.mtimeMs,
+		ctimeMs: metadata.ctimeMs,
+	}));
+}
+
+function hashPathBatches(leaves: readonly VisibleLeaf[]): VisibleLeaf[][] {
+	const result: VisibleLeaf[][] = [];
+	let current: VisibleLeaf[] = [];
+	let argumentBytes = 0;
+	for (const leaf of leaves) {
+		const leafBytes = Buffer.byteLength(leaf.relativePath, "utf8") + 1;
+		if (
+			current.length > 0 &&
+			(current.length >= HASH_BATCH_MAX_PATHS || argumentBytes + leafBytes > HASH_BATCH_MAX_ARGUMENT_BYTES)
+		) {
+			result.push(current);
+			current = [];
+			argumentBytes = 0;
+		}
+		current.push(leaf);
+		argumentBytes += leafBytes;
+	}
+	if (current.length > 0) result.push(current);
+	return result;
+}
+
+function parseObjectIdLines(output: string, expectedCount: number): string[] {
+	const lines = output.endsWith("\n") ? output.slice(0, -1).split("\n") : output.split("\n");
+	if (lines.length !== expectedCount || lines.some((line) => !isObjectId(line))) {
+		throw new SnapshotStoreError("capture_failed", "git hash-object 批量输出无效");
+	}
+	return lines;
+}
+
 function parseTreeEntries(output: Uint8Array): CapturedTreeEntry[] {
 	const entries: CapturedTreeEntry[] = [];
 	for (const record of splitNulRecords(output)) {