@davideasden/pi-undo 0.2.8 → 0.2.10

package/README.md

@@ -23,11 +23,11 @@ Each completed agent run creates a checkpoint that captures both the Pi session
 - Node.js `22.19.0` or later.
 - Git available on `PATH` (used internally for content-addressed snapshots).
 
-### Rust 原生加速
+### Native Rust Acceleration
 
-pi-undo 包含跨平台 Rust 原生 helper（`pi-undo-fs`），用于加速文件系统操作。发布包会同时包含以下六个预编译二进制：
+pi-undo includes a cross-platform native Rust helper (`pi-undo-fs`) to accelerate filesystem operations. The published package contains these six precompiled binaries:
 
-| 平台 | 架构 | 二进制名称 |
+| Platform | Architecture | Binary |
 |---|---|---|
 | macOS | arm64 | `pi-undo-fs-darwin-arm64` |
 | macOS | x64 | `pi-undo-fs-darwin-x64` |
@@ -36,33 +36,33 @@ pi-undo 包含跨平台 Rust 原生 helper（`pi-undo-fs`），用于加速文
 | Windows | arm64 | `pi-undo-fs-win32-arm64.exe` |
 | Windows | x64 | `pi-undo-fs-win32-x64.exe` |
 
-扩展会根据当前运行环境自动选择对应二进制，因此用户无需安装 Rust，也无需手动选择平台。Windows 二进制带有 `.exe` 后缀。对于尚未提供预编译二进制的平台，扩展会自动回退到 TypeScript 路径，功能仍然可用。
+The extension automatically selects the correct binary for the current runtime, so users do not need to install Rust or choose a platform manually. Windows binaries use the `.exe` suffix. On platforms without a precompiled binary, the extension automatically falls back to the TypeScript implementation with the same functionality.
 
 ## Installation
 
-### 从 npm 安装（推荐）
+### Install from npm (Recommended)
 
-所有受支持的平台使用同一个安装命令；npm 包会包含 macOS/Linux/Windows 的 arm64/x64 预编译 Rust helper，扩展启动时自动选择当前平台的版本：
+All supported platforms use the same installation command. The npm package includes precompiled arm64 and x64 Rust helpers for macOS, Linux, and Windows, and the extension selects the correct version at startup:
 
 ```bash
 pi install npm:@davideasden/pi-undo
 ```
 
-重启 Pi 即可加载扩展。用户不需要安装 Rust，也不需要手动选择或安装平台专用包。
+Restart Pi to load the extension. Users do not need to install Rust or select and install a platform-specific package.
 
-### 从本地源码安装
+### Install from Local Source
 
 ```bash
 pi install /path/to/pi-undo
 ```
 
-### 开发模式直接加载
+### Load Directly for Development
 
 ```bash
 pi -e /absolute/path/to/pi-undo/extensions/pi-undo.ts
 ```
 
-> **注意**：`pi install` 会将整个包（包括 `native/bin/` 下的预编译二进制）复制到 Pi 的扩展目录。如果你从源码构建后想要包含新编译的原生二进制，确保运行 `npm run build:native` 后再执行 `pi install`。
+> **Note:** `pi install` copies the entire package, including the precompiled binaries under `native/bin/`, into Pi's extension directory. To include a newly compiled native binary in a source installation, run `npm run build:native` before `pi install`.
 
 ## Usage
 
@@ -233,6 +233,46 @@ When `recovery_required` appears, first back up the workspace and Pi session JSO
 
 A transaction directory may contain `descriptor.json`, `restore-plan.json`, `state.json`, `mutations.jsonl`, `durable-pack-v1.bin`, and a native helper request. Do not delete `.pi-undo` without a backup: unresolved packs or quarantine artifacts may be the only surviving copy of a file version.
 
+### Troubleshooting `recovery_required`
+
+First stop other Pi instances, editors, formatters, and watchers that may write to the same workspace. Then completely quit and restart Pi once. Startup recovery is idempotent and normally finishes an interrupted transaction automatically. Deleting `.pi-undo` while Pi is still running does not clear the in-memory recovery lock, and the active process may recreate the directory.
+
+If the footer includes an `opId`, locate that exact transaction first. Recovery data is stored under the session directory for each workspace. Inspecting `.pi-undo` for a different workspace can therefore produce a misleading result that no pending journal exists:
+
+```bash
+OP_ID="op-..."; TX="$(find "${PI_AGENT_DIR:-$HOME/.pi/agent}/sessions" -type d -path "*/.pi-undo/transactions/$OP_ID" -print -quit)"; test -n "$TX" && printf 'transaction=%s\n' "$TX"
+```
+
+Back up the workspace before continuing. Inspect the transaction phase and descriptor without editing them:
+
+```bash
+jq '{opId,phase,revision,observedLogicalLeaf}' "$TX/state.json"
+jq '{action,fromLogicalLeaf,toLogicalLeaf,workspaceIdentity,sessionIdentity,scopeCount:(.scopePaths | length)}' "$TX/descriptor.json"
+```
+
+List every non-terminal transaction under the same `.pi-undo` root. This command is intentionally kept on one line because trailing whitespace after a continuation backslash can break `find -exec` when a multiline command is pasted:
+
+```bash
+ROOT="$(dirname "$(dirname "$TX")")"; find "$ROOT/transactions" -name state.json -type f -exec jq -r 'select(.phase != "COMMITTED" and .phase != "ABORTED") | "\(.opId) \(.phase)"' {} +
+```
+
+If `mutations.jsonl` exists, summarize the final state of each mutation ordinal and list mutations that have not been cleaned:
+
+```bash
+jq -s 'group_by(.ordinal) | map(.[-1]) | group_by(.state) | map({state: .[0].state, count: length})' "$TX/mutations.jsonl"
+jq -s 'group_by(.ordinal) | map(.[-1]) | map(select(.state != "CLEANED")) | .[] | {ordinal,path,kind,state}' "$TX/mutations.jsonl"
+```
+
+- If the second command prints any records, artifacts or file mutations are still active. Do not delete or move the transaction. Preserve the workspace, session JSONL, transaction directory, and same-directory `.pi-undo-*` artifacts for manual recovery.
+- If the second command prints nothing, every WAL mutation is already `CLEANED`. A footer such as `recovery_required files:1 op:...` may still appear because the conflict path count has a minimum fallback of one. `files:1` alone does not prove that one active file remains.
+- Only when every mutation is `CLEANED`, the transaction phase is still `RECOVERY_REQUIRED`, and you have independently verified that the current workspace and Pi session are the result you want to keep, back up and isolate that transaction:
+
+```bash
+SESSION="$(jq -r '.sessionIdentity.path' "$TX/descriptor.json")"; STAMP="$(date '+%Y%m%d-%H%M%S')"; BACKUP="$ROOT/recovery-backup/$STAMP"; mkdir -p "$BACKUP"; cp -p "$SESSION" "$BACKUP/$(basename "$SESSION").backup"; mv "$TX" "$BACKUP/"
+```
+
+After isolating a fully cleaned transaction, completely quit every Pi process for that workspace and start Pi again. Reloading the session alone may retain the in-memory recovery lock. Do not edit `state.json` by hand because journal states and descriptors are checksum-bound. Do not remove the entire `.pi-undo` directory because it may still contain committed history, snapshots, packs, or the only recoverable copy of a file.
+
 ## Limitations
 
 - Git-ignored files are not included in snapshots and are not created or deleted during restore.
@@ -246,7 +286,7 @@ A transaction directory may contain `descriptor.json`, `restore-plan.json`, `sta
 
 ## Development
 
-### 依赖
+### Dependencies
 
 Clone the repository and install dependencies:
 
@@ -256,24 +296,24 @@ cd pi-undo
 npm install
 ```
 
-### 构建 Rust 原生 helper
+### Build the Native Rust Helper
 
-如果需要构建或更新原生二进制，确保已安装 [Rust 工具链](https://rustup.rs/)：
+Install the [Rust toolchain](https://rustup.rs/) before building or updating a native binary:
 
 ```bash
 npm run build:native
 ```
 
-`npm run build:native` 会在 `native/pi-undo-fs/target/release/` 下生成当前构建平台的 `pi-undo-fs`。发布流程会在 macOS、Linux 和 Windows runner 上分别构建 arm64/x64 版本，统一重命名后放入 `native/bin/`，再打包成包含六个二进制的 npm 包。
+`npm run build:native` creates `pi-undo-fs` for the current build platform under `native/pi-undo-fs/target/release/`. The release workflow builds arm64 and x64 versions on macOS, Linux, and Windows runners, renames them consistently under `native/bin/`, and packages all six binaries in the npm package.
 
-本地开发时，如果只需要验证当前平台，可以将生成的文件复制到 `native/bin/` 并按平台重命名，例如：Windows 生成的文件应使用对应的 `.exe` 文件名。
+For local development on the current platform, copy the generated file into `native/bin/` and rename it for the platform. For example, a Windows build must use the corresponding `.exe` filename.
 
 ```bash
 cp native/pi-undo-fs/target/release/pi-undo-fs native/bin/pi-undo-fs-darwin-arm64
 chmod +x native/bin/pi-undo-fs-darwin-arm64
 ```
 
-发布包必须包含 Requirements 中列出的六个平台二进制；CI 会在打包前检查这一点，并在推送 `v*` tag 时发布该 CI 构建的完整 npm 包。npm 仓库需要为此 GitHub Actions workflow 配置 npm Trusted Publishing（OIDC）。如果当前平台没有对应二进制，扩展会自动使用 TypeScript 回退路径。
+The published package must contain all six platform binaries listed under Requirements. CI verifies them before packaging and publishes the complete CI-built npm package when a `v*` tag is pushed. The npm package must configure Trusted Publishing (OIDC) for this GitHub Actions workflow. If no binary is available for the current platform, the extension automatically uses the TypeScript fallback.
 
 ### Project Layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.8",
+	"version": "0.2.10",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [

package/src/controller.ts

@@ -188,6 +188,8 @@ export class UndoControllerImpl implements UndoController {
 	private locked = false;
 	private historyPaused = false;
 	private operationInFlight = false;
+	private operationAction: "undo" | "redo" | undefined;
+	private operationProfiler: OperationProfiler | undefined;
 	private promptDeferralInFlight = false;
 	private lastSafetyManifestId: ManifestId | null = null;
 
@@ -261,18 +263,30 @@ export class UndoControllerImpl implements UndoController {
 			await this.dependencies.appendControl("pi-undo:barrier", { reason: "user_entry_missing" }).catch(() => {});
 			return;
 		}
+		const profiler = this.operationProfiler;
+		const measure = <T>(phase: string, operation: () => Promise<T>): Promise<T> =>
+			profiler === undefined ? operation() : profiler.measure(phase, operation);
 		try {
-			const after = await this.captureWithWorkspaceLock();
-			const changedPaths = await this.dependencies.changedPaths(staged.before, after);
+			const after = await measure("settled.capture", () => this.captureWithWorkspaceLock());
+			const changedPaths = await measure("settled.changedPaths", () =>
+				this.dependencies.changedPaths(staged.before, after));
 			if (changedPaths.length > 0 && this.dependencies.prepareDurableRestore !== undefined) {
-				await Promise.all([
-					this.dependencies.prepareDurableRestore(staged.before, after, changedPaths),
-					this.dependencies.prepareDurableRestore(after, staged.before, changedPaths),
-				]).catch(() => {});
+				// /undo 在流式中断后正等待本次 settled；关键路径只预制立即使用的 after → before。
+				const preparations = this.operationAction === "undo"
+					? [measure("settled.prepareUndo", () =>
+						this.dependencies.prepareDurableRestore!(after, staged.before, changedPaths))]
+					: [
+						measure("settled.prepareRedo", () =>
+							this.dependencies.prepareDurableRestore!(staged.before, after, changedPaths)),
+						measure("settled.prepareUndo", () =>
+							this.dependencies.prepareDurableRestore!(after, staged.before, changedPaths)),
+					];
+				await Promise.allSettled(preparations);
 			}
 			const endLeafId = this.dependencies.getLogicalLeafId() ?? staged.startEntryId;
 			const checkpoint = this.createCheckpoint(staged, after, changedPaths, userEntryId, endLeafId);
-			const checkpointEntryId = await this.dependencies.appendControl("pi-undo:checkpoint", checkpoint);
+			const checkpointEntryId = await measure("settled.checkpoint", () =>
+				this.dependencies.appendControl("pi-undo:checkpoint", checkpoint));
 			if (checkpointEntryId === null) {
 				this.locked = true;
 				await this.dependencies.appendControl("pi-undo:barrier", { reason: "checkpoint_entry_missing" }).catch(() => {});
@@ -289,27 +303,14 @@ export class UndoControllerImpl implements UndoController {
 
 	async undo(): Promise<OperationResult> {
 		if (this.historyPaused) return { code: "history_paused", changedFiles: 0 };
-		const checkpoint = this.undoStack.at(-1);
-		if (checkpoint === undefined) return noop();
-		const result = await this.runOperation("undo", checkpoint);
-		if (result.code === "ok" && this.lastSafetyManifestId !== null) {
-			this.undoStack.pop();
-			this.redoStack.push({ checkpoint, targetManifestId: this.lastSafetyManifestId });
-			return { ...result, refillPrompt: checkpoint.rawPrompt };
-		}
-		return result;
+		return this.runOperation("undo");
 	}
 
 	async redo(): Promise<OperationResult> {
 		if (this.historyPaused) return { code: "history_paused", changedFiles: 0 };
-		const redo = this.redoStack.at(-1);
-		if (redo === undefined) return noop();
-		const result = await this.runOperation("redo", redo.checkpoint, redo.targetManifestId);
-		if (result.code === "ok") {
-			this.redoStack.pop();
-			this.undoStack.push(redo.checkpoint);
-		}
-		return result;
+		// 新 run 开始时 redo frontier 已失效；空栈命令不得为了确认 noop 而中断正在运行的 Agent。
+		if (this.redoStack.length === 0) return noop();
+		return this.runOperation("redo");
 	}
 
 	async beforeTree(event: SessionBeforeTreeEvent): Promise<SessionBeforeTreeResult | undefined> {
@@ -408,15 +409,13 @@ export class UndoControllerImpl implements UndoController {
 		}
 	}
 
-	private async runOperation(
-		action: "undo" | "redo",
-		checkpoint: CheckpointRecord,
-		targetManifestId?: ManifestId,
-	): Promise<OperationResult> {
+	private async runOperation(action: "undo" | "redo"): Promise<OperationResult> {
 		if (this.locked || this.operationInFlight) return { code: "busy", changedFiles: 0 };
 		const profile = new OperationProfiler();
 		const done = (result: OperationResult): OperationResult => profile.attach(result);
 		this.operationInFlight = true;
+		this.operationAction = action;
+		this.operationProfiler = profile;
 		this.promptDeferralInFlight = true;
 		this.lastSafetyManifestId = null;
 		let lease: { release(): Promise<void> } | undefined;
@@ -424,13 +423,19 @@ export class UndoControllerImpl implements UndoController {
 			if (!await profile.measure("idle", () => this.ensureIdle())) {
 				return done({ code: "idle_timeout", changedFiles: 0 });
 			}
+			// 中断中的 run 会在 waitForIdle() 内由 agentSettled() 推入栈，必须在此之后选择目标。
+			const redo = action === "redo" ? this.redoStack.at(-1) : undefined;
+			const checkpoint = action === "undo" ? this.undoStack.at(-1) : redo?.checkpoint;
+			if (checkpoint === undefined) return done(noop());
+			const targetManifestId = redo?.targetManifestId;
 			try {
 				lease = await profile.measure("lock", () => this.dependencies.acquireWorkspaceLock());
 			} catch {
 				return done({ code: "busy", changedFiles: 0 });
 			}
 			if (checkpoint.changedPaths.length === 0) {
-				return done(await this.runSessionOnlyOperation(action, checkpoint, targetManifestId, profile));
+				const result = await this.runSessionOnlyOperation(action, checkpoint, targetManifestId, profile);
+				return done(this.advanceHistory(action, checkpoint, result));
 			}
 			const restoreTargetManifestId = targetManifestId ?? (
 				action === "undo" ? checkpoint.beforeManifestId : checkpoint.afterManifestId
@@ -512,7 +517,7 @@ export class UndoControllerImpl implements UndoController {
 				await this.dependencies.journal.markCommitted(descriptor.opId);
 			});
 			this.lastSafetyManifestId = rollback.manifestId;
-			return done({ code: "ok", changedFiles: applied.verifiedPaths });
+			return done(this.advanceHistory(action, checkpoint, { code: "ok", changedFiles: applied.verifiedPaths }));
 		} catch {
 			this.locked = true;
 			return done({ code: "recovery_required", changedFiles: 0 });
@@ -522,11 +527,30 @@ export class UndoControllerImpl implements UndoController {
 				await profile.measure("unlock", () =>
 					activeLease.release().catch(() => { this.locked = true; }));
 			}
+			if (this.operationProfiler === profile) this.operationProfiler = undefined;
+			this.operationAction = undefined;
 			this.promptDeferralInFlight = false;
 			this.operationInFlight = false;
 		}
 	}
 
+	private advanceHistory(
+		action: "undo" | "redo",
+		checkpoint: CheckpointRecord,
+		result: OperationResult,
+	): OperationResult {
+		if (result.code !== "ok") return result;
+		if (action === "undo") {
+			if (this.lastSafetyManifestId === null) return result;
+			this.undoStack.pop();
+			this.redoStack.push({ checkpoint, targetManifestId: this.lastSafetyManifestId });
+			return { ...result, refillPrompt: checkpoint.rawPrompt };
+		}
+		this.redoStack.pop();
+		this.undoStack.push(checkpoint);
+		return result;
+	}
+
 	private async runSessionOnlyOperation(
 		action: "undo" | "redo",
 		checkpoint: CheckpointRecord,

package/src/native-metadata.ts

@@ -0,0 +1,231 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { nativeExecutable } from "./native-restore.ts";
+
+const NATIVE_INSPECT_TIMEOUT_MS = 30_000;
+const NATIVE_INSPECT_OUTPUT_LIMIT = 32 * 1024 * 1024;
+
+export interface NativeMetadataEntry {
+	readonly path: string;
+	readonly kind: "absent" | "file" | "symlink" | "other";
+	readonly dev?: bigint;
+	readonly ino?: bigint;
+	readonly mode?: bigint;
+	readonly size?: bigint;
+	readonly mtimeNs?: bigint;
+	readonly ctimeNs?: bigint;
+}
+
+export interface NativeMetadataPort {
+	inspect(
+		workspaceRoot: string,
+		paths: readonly string[],
+		requestDirectory: string,
+	): Promise<readonly NativeMetadataEntry[] | undefined>;
+}
+
+/** 能力探测不支持时回退 TypeScript；已确认支持后的 inspect 错误保持 fail-closed。 */
+export class NativeMetadataInspector implements NativeMetadataPort {
+	private readonly executable: string | undefined;
+	private capability: Promise<boolean> | undefined;
+
+	constructor(executable = nativeExecutable()) {
+		this.executable = process.env.PI_UNDO_DISABLE_NATIVE === "1" ? undefined : executable;
+	}
+
+	async inspect(
+		workspaceRoot: string,
+		paths: readonly string[],
+		requestDirectory: string,
+	): Promise<readonly NativeMetadataEntry[] | undefined> {
+		if (paths.length === 0) return [];
+		if (!await this.supportsInspect(requestDirectory)) return undefined;
+		const executable = this.executable!;
+		const requestPath = join(requestDirectory, `native-inspect-${process.pid}-${randomUUID()}.json`);
+		try {
+			await writeFile(requestPath, JSON.stringify({
+				schemaVersion: 1,
+				workspaceRoot,
+				paths,
+			}), { mode: 0o600, flag: "wx" });
+			return await runNativeInspect(executable, requestPath, paths);
+		} finally {
+			await rm(requestPath, { force: true }).catch(() => {});
+		}
+	}
+
+	private supportsInspect(requestDirectory: string): Promise<boolean> {
+		if (this.capability !== undefined) return this.capability;
+		this.capability = (async () => {
+			if (this.executable === undefined) return false;
+			try {
+				await access(this.executable, constants.X_OK);
+				return await probeNativeInspect(this.executable, requestDirectory);
+			} catch {
+				return false;
+			}
+		})();
+		return this.capability;
+	}
+}
+
+function probeNativeInspect(executable: string, isolatedDirectory: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const child = spawn(executable, ["--capabilities"], {
+			cwd: isolatedDirectory,
+			shell: false,
+			stdio: ["ignore", "pipe", "ignore"],
+			windowsHide: true,
+		});
+		const stdout: Buffer[] = [];
+		let bytes = 0;
+		let settled = false;
+		const timeout = setTimeout(() => child.kill("SIGKILL"), 5_000);
+		child.stdout?.on("data", (chunk: Buffer | string) => {
+			const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			bytes += value.length;
+			if (bytes <= 64 * 1024) stdout.push(value);
+			else child.kill("SIGKILL");
+		});
+		child.once("error", () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			resolve(false);
+		});
+		child.once("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (code !== 0 || bytes > 64 * 1024) return resolve(false);
+			try {
+				const value: unknown = JSON.parse(Buffer.concat(stdout).toString("utf8"));
+				resolve(isRecord(value) && value.ok === true && Array.isArray(value.capabilities) &&
+					value.capabilities.includes("inspect-v1"));
+			} catch {
+				resolve(false);
+			}
+		});
+	});
+}
+
+function runNativeInspect(
+	executable: string,
+	requestPath: string,
+	expectedPaths: readonly string[],
+): Promise<readonly NativeMetadataEntry[]> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(executable, ["--inspect", requestPath], {
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		});
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+		let outputBytes = 0;
+		let settled = false;
+		let overflow = false;
+		const timeout = setTimeout(() => child.kill("SIGKILL"), NATIVE_INSPECT_TIMEOUT_MS);
+		const capture = (target: Buffer[]) => (chunk: Buffer | string): void => {
+			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			if (outputBytes + bytes.length > NATIVE_INSPECT_OUTPUT_LIMIT) {
+				overflow = true;
+				child.kill("SIGKILL");
+				return;
+			}
+			target.push(bytes);
+			outputBytes += bytes.length;
+		};
+		child.stdout?.on("data", capture(stdout));
+		child.stderr?.on("data", capture(stderr));
+		child.once("error", (error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			reject(error);
+		});
+		child.once("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (overflow) {
+				reject(new Error("native metadata inspect 输出超过限制"));
+				return;
+			}
+			if (code !== 0) {
+				reject(new Error(`native metadata inspect 失败：${Buffer.concat(stderr).toString("utf8").trim()}`));
+				return;
+			}
+			try {
+				resolve(parseInspectResponse(Buffer.concat(stdout).toString("utf8"), expectedPaths));
+			} catch (error) {
+				reject(error);
+			}
+		});
+	});
+}
+
+function parseInspectResponse(text: string, expectedPaths: readonly string[]): readonly NativeMetadataEntry[] {
+	const value: unknown = JSON.parse(text);
+	if (!isRecord(value) || value.ok !== true || value.processed !== expectedPaths.length || !Array.isArray(value.entries)) {
+		throw new Error("native metadata inspect 响应无效");
+	}
+	if (value.entries.length !== expectedPaths.length) throw new Error("native metadata inspect 条目数量不匹配");
+	return value.entries.map((candidate, index) => {
+		if (!isRecord(candidate) || candidate.path !== expectedPaths[index] ||
+			!isMetadataKind(candidate.kind)) {
+			throw new Error("native metadata inspect 条目无效");
+		}
+		if (candidate.kind === "absent") {
+			if ([candidate.dev, candidate.ino, candidate.mode, candidate.size, candidate.mtimeNs, candidate.ctimeNs]
+				.some((field) => field !== null && field !== undefined)) {
+				throw new Error("native metadata absent 条目包含 metadata");
+			}
+			return { path: candidate.path as string, kind: "absent" as const };
+		}
+		return {
+			path: candidate.path as string,
+			kind: candidate.kind,
+			dev: parseUnsigned(candidate.dev, 64),
+			ino: parseUnsigned(candidate.ino, 64),
+			mode: parseUnsigned(candidate.mode, 32),
+			size: parseUnsigned(candidate.size, 64),
+			mtimeNs: parseTimestamp(candidate.mtimeNs),
+			ctimeNs: parseTimestamp(candidate.ctimeNs),
+		};
+	});
+}
+
+function parseUnsigned(value: unknown, bits: 32 | 64): bigint {
+	const maxDigits = bits === 32 ? 10 : 20;
+	if (typeof value !== "string" || value.length > maxDigits || !/^(?:0|[1-9][0-9]*)$/.test(value)) {
+		throw new Error("native metadata unsigned 字段无效");
+	}
+	const parsed = BigInt(value);
+	if (parsed > (1n << BigInt(bits)) - 1n) throw new Error("native metadata unsigned 字段越界");
+	return parsed;
+}
+
+function parseTimestamp(value: unknown): bigint {
+	if (typeof value !== "string" || value.length > 30 || !/^-?(?:0|[1-9][0-9]*)$/.test(value)) {
+		throw new Error("native metadata timestamp 字段无效");
+	}
+	const parsed = BigInt(value);
+	const billion = 1_000_000_000n;
+	const minimum = -(1n << 63n) * billion;
+	const maximum = ((1n << 63n) - 1n) * billion + (billion - 1n);
+	if (parsed < minimum || parsed > maximum) throw new Error("native metadata timestamp 字段越界");
+	return parsed;
+}
+
+function isMetadataKind(value: unknown): value is NativeMetadataEntry["kind"] {
+	return value === "absent" || value === "file" || value === "symlink" || value === "other";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/native-restore.ts

@@ -79,7 +79,7 @@ export async function createNativeFileBatch(options: {
 	};
 }
 
-function nativeExecutable(): string | undefined {
+export function nativeExecutable(): string | undefined {
 	const platform = process.platform === "darwin"
 		? "darwin"
 		: process.platform === "linux" ? "linux"

package/src/path-safety.ts

@@ -64,6 +64,30 @@ export async function assertNoSymlinkEscape(root: string, relativePath: string):
 	}
 }
 
+/** 批量核验叶子路径的全部父目录；共享目录只执行一次 lstat。 */
+export async function assertNoSymlinkParents(root: string, relativePaths: readonly string[]): Promise<void> {
+	const directories = new Set<string>();
+	for (const relativePath of relativePaths) {
+		const safePath = relativeSafePath(root, relativePath);
+		if (safePath === ".") continue;
+		const parts = safePath.split("/");
+		for (let index = 1; index < parts.length; index += 1) {
+			directories.add(parts.slice(0, index).join("/"));
+		}
+	}
+	const ordered = [...directories].sort((left, right) => pathDepth(left) - pathDepth(right) || left.localeCompare(right));
+	for (const directory of ordered) {
+		try {
+			const metadata = await lstat(join(resolve(root), ...directory.split("/")));
+			if (metadata.isSymbolicLink()) fail("symlink_escape", "中间路径组件不能是 symlink");
+			if (!metadata.isDirectory()) fail("unsafe_path", "中间路径组件不是目录");
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) continue;
+			throw error;
+		}
+	}
+}
+
 export function pathSetsOverlap(leftPaths: readonly string[], rightPaths: readonly string[]): boolean {
 	for (const path of leftPaths) assertRelativeCandidate(path);
 	for (const path of rightPaths) assertRelativeCandidate(path);

package/src/snapshot-store.ts

@@ -1,4 +1,4 @@
-import type { Stats } from "node:fs";
+import type { BigIntStats } 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";
@@ -20,7 +20,9 @@ import type {
 	SnapshotManifest,
 	SnapshotRoot,
 } from "./model.ts";
-import { assertNoSymlinkEscape, pathSetsOverlap, relativeSafePath } from "./path-safety.ts";
+import type { NativeMetadataEntry, NativeMetadataPort } from "./native-metadata.ts";
+import { NativeMetadataInspector } from "./native-metadata.ts";
+import { assertNoSymlinkEscape, assertNoSymlinkParents, pathSetsOverlap, relativeSafePath } from "./path-safety.ts";
 import { RootDiscovery, type RootTopology } from "./root-discovery.ts";
 import { WorkspaceLock } from "./workspace-lock.ts";
 
@@ -42,6 +44,7 @@ const INDEX_BATCH_MAX_BYTES = 8 * 1024 * 1024;
 const BLOB_CACHE_MAX_BYTES = 128 * 1024 * 1024;
 const BLOB_BATCH_MAX_BYTES = 16 * 1024 * 1024;
 const BLOB_BATCH_MAX_ENTRIES = process.platform === "win32" ? 256 : 2_048;
+const RACY_CLEAN_WINDOW_NS = 2_000_000_000n;
 
 interface PinRecord {
 	readonly schemaVersion: 1;
@@ -70,6 +73,17 @@ interface CapturedRootResult {
 	readonly ignoredPresentPaths: readonly string[];
 	readonly ignoreClosure: string;
 	readonly objectClosure: string;
+	readonly cacheUpdate: VisibleLeafCacheUpdate;
+}
+
+interface VisibleLeafMetadata {
+	readonly kind: "file" | "symlink" | "other";
+	readonly dev: bigint;
+	readonly ino: bigint;
+	readonly mode: bigint;
+	readonly size: bigint;
+	readonly mtimeNs: bigint;
+	readonly ctimeNs: bigint;
 }
 
 interface VisibleLeaf {
@@ -77,6 +91,25 @@ interface VisibleLeaf {
 	readonly kind: "file" | "symlink";
 	readonly mode: number;
 	readonly fingerprint: string;
+	readonly changedAtNs: bigint;
+	readonly cacheable: boolean;
+}
+
+interface CachedVisibleLeaf extends VisibleLeaf {
+	readonly objectId: string;
+	readonly verifiedAtNs: bigint;
+}
+
+interface StagedWorktree {
+	readonly leaves: readonly VisibleLeaf[];
+	readonly objectIds: ReadonlyMap<string, string>;
+	readonly verifiedAtNs: bigint;
+}
+
+interface VisibleLeafCacheUpdate {
+	readonly gitDirectory: string;
+	readonly staged: StagedWorktree;
+	readonly inclusions: readonly string[] | null;
 }
 
 interface CachedBlob {
@@ -90,6 +123,7 @@ export interface SnapshotStoreOptions {
 	readonly discovery?: RootDiscovery;
 	readonly lock?: WorkspaceLock;
 	readonly clock?: () => number;
+	readonly nativeMetadata?: NativeMetadataPort;
 }
 
 export interface CaptureOptions {
@@ -141,11 +175,13 @@ export class SnapshotStore {
 	private readonly discovery: RootDiscovery;
 	private readonly lock: WorkspaceLock;
 	private readonly clock: () => number;
+	private readonly nativeMetadata: NativeMetadataPort;
 	private readonly manifestLocations = new Map<string, string>();
 	// Tree 与 blob 都由 object ID 内容寻址；缓存只复用已从私有 ODB 读取的不可变内容。
 	private readonly treeEntriesCache = new Map<string, Promise<CapturedTreeEntry[]>>();
 	private readonly treeBlobMembership = new Map<string, string>();
 	private readonly blobCache = new Map<string, CachedBlob>();
+	private readonly visibleLeafCache = new Map<string, Map<string, CachedVisibleLeaf>>();
 	private blobCacheBytes = 0;
 
 	constructor(options: SnapshotStoreOptions = {}) {
@@ -155,6 +191,7 @@ export class SnapshotStore {
 		this.discovery = options.discovery ?? new RootDiscovery(this.git);
 		this.lock = options.lock ?? new WorkspaceLock();
 		this.clock = options.clock ?? Date.now;
+		this.nativeMetadata = options.nativeMetadata ?? new NativeMetadataInspector();
 	}
 
 	static supportsValidatedBlobBatch(store: SnapshotStore): boolean {
@@ -223,6 +260,7 @@ export class SnapshotStore {
 			transactionDirectory = await mkdtemp(join(transactionsRoot, "capture-"));
 
 			const roots: SnapshotRoot[] = [];
+			const cacheUpdates: VisibleLeafCacheUpdate[] = [];
 			for (const root of topology.roots) {
 				if (root.state !== "active") {
 					const coverage = rootCaptureCoverage(root.relativeRoot, scope);
@@ -242,6 +280,7 @@ export class SnapshotStore {
 					artifactExclusions,
 				);
 				roots.push(snapshotRoot(root, captured));
+				cacheUpdates.push(captured.cacheUpdate);
 			}
 
 			await this.assertTopology(topology, "捕获期间 topology 已变化");
@@ -261,6 +300,7 @@ export class SnapshotStore {
 			await this.touchStore(storeDirectory);
 			await writeContentAddressed(manifestPath, Buffer.from(canonicalJson(manifest), "utf8"));
 			this.manifestLocations.set(manifestId, manifestPath);
+			for (const update of cacheUpdates) this.rememberVisibleLeaves(update);
 			return manifest;
 		} catch (error) {
 			if (error instanceof SnapshotStoreError) {
@@ -624,6 +664,9 @@ export class SnapshotStore {
 						this.manifestLocations.delete(id);
 					}
 				}
+				for (const gitDirectory of this.visibleLeafCache.keys()) {
+					if (gitDirectory.startsWith(`${storeDirectory}${sep}`)) this.visibleLeafCache.delete(gitDirectory);
+				}
 			} catch (error) {
 				await writeJsonAtomic(join(storeDirectory, GC_METADATA_FILE), {
 					schemaVersion: SCHEMA_VERSION,
@@ -659,13 +702,15 @@ export class SnapshotStore {
 			.map((candidate) => rootRelativePath(root.relativeRoot, candidate.relativeRoot));
 		const exactExclusions = ownedArtifactExclusions(topology.roots, root.relativeRoot, artifactExclusions);
 		const inclusions = ownedRootInclusions(requestedInclusions, exclusions);
-		await this.stageWorktree(
+		const staged = await this.stageWorktree(
 			absoluteRoot,
 			environment,
 			root.gitBacked,
 			inclusions,
 			exclusions,
 			exactExclusions,
+			this.visibleLeafCache.get(gitDirectory),
+			transactionDirectory,
 		);
 		const coverage = rootCoverageFromInclusions(inclusions);
 		const ignoredPresentPaths = await this.captureIgnoredPresentPaths(
@@ -687,6 +732,7 @@ export class SnapshotStore {
 			coverage,
 			...ignoredPresentProof(coverage, ignoredPresentPaths),
 			objectClosure: treeObjectClosure(treeId, entries),
+			cacheUpdate: { gitDirectory, staged, inclusions },
 		};
 	}
 
@@ -749,7 +795,9 @@ export class SnapshotStore {
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
 		exactExclusions: ReadonlySet<string>,
-	): Promise<void> {
+		cache: ReadonlyMap<string, CachedVisibleLeaf> | undefined,
+		requestDirectory: string,
+	): Promise<StagedWorktree> {
 		const leaves = await this.collectVisibleLeaves(
 			cwd,
 			environment,
@@ -757,12 +805,25 @@ export class SnapshotStore {
 			inclusions,
 			exclusions,
 			exactExclusions,
+			requestDirectory,
 		);
 		const objectIds = new Map<string, string>();
-		const hashBatches = hashPathBatches(leaves.filter((leaf) => leaf.kind === "file"));
+		const uncached: VisibleLeaf[] = [];
+		for (const leaf of leaves) {
+			const cached = cache?.get(leaf.relativePath);
+			if (
+				leaf.cacheable && cached?.cacheable === true && cached.kind === leaf.kind &&
+				cached.mode === leaf.mode && cached.fingerprint === leaf.fingerprint &&
+				cached.verifiedAtNs > cached.changedAtNs + RACY_CLEAN_WINDOW_NS
+			) {
+				objectIds.set(leaf.relativePath, cached.objectId);
+			} else {
+				uncached.push(leaf);
+			}
+		}
+		const hashBatches = hashPathBatches(uncached.filter((leaf) => leaf.kind === "file"));
 		const hashedBatches = await mapConcurrentOrdered(hashBatches, HASH_BATCH_CONCURRENCY, async (batch) => {
-			await mapConcurrentOrdered(batch, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
-				this.assertVisibleLeafUnchanged(cwd, leaf));
+			await this.assertVisibleLeavesUnchanged(cwd, batch);
 			const output = await this.runGit([
 				"hash-object",
 				"-w",
@@ -771,15 +832,15 @@ export class SnapshotStore {
 				...batch.map((leaf) => leaf.relativePath),
 			], { cwd, env: environment });
 			const hashes = parseObjectIdLines(output, batch.length);
-			await mapConcurrentOrdered(batch, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
-				this.assertVisibleLeafUnchanged(cwd, leaf));
+			await this.assertVisibleLeavesUnchanged(cwd, batch);
 			return batch.map((leaf, index) => [leaf.relativePath, hashes[index]!] as const);
 		});
 		for (const batch of hashedBatches) {
 			for (const [relativePath, objectId] of batch) objectIds.set(relativePath, objectId);
 		}
-		for (const leaf of leaves) {
+		for (const leaf of uncached) {
 			if (leaf.kind !== "symlink") continue;
+			await assertNoSymlinkEscape(cwd, leaf.relativePath);
 			await this.assertVisibleLeafUnchanged(cwd, leaf);
 			const linkText = await readlink(join(cwd, ...leaf.relativePath.split("/")), { encoding: "buffer" });
 			decodeUtf8(linkText, "symlink target 不是可无损表示的 UTF-8");
@@ -791,6 +852,7 @@ export class SnapshotStore {
 			if (!isObjectId(objectId)) {
 				throw new SnapshotStoreError("capture_failed", `文件对象 materialize 失败：${leaf.relativePath}`);
 			}
+			await assertNoSymlinkEscape(cwd, leaf.relativePath);
 			await this.assertVisibleLeafUnchanged(cwd, leaf);
 			objectIds.set(leaf.relativePath, objectId);
 		}
@@ -801,15 +863,67 @@ export class SnapshotStore {
 				stdin: indexInput,
 			});
 		}
+		await this.assertVisibleLeavesUnchanged(cwd, leaves, requestDirectory);
+		return { leaves, objectIds, verifiedAtNs: BigInt(Date.now()) * 1_000_000n };
+	}
+
+	private rememberVisibleLeaves(update: VisibleLeafCacheUpdate): void {
+		const { gitDirectory, staged, inclusions } = update;
+		const cache = inclusions !== null && inclusions.length === 0
+			? new Map<string, CachedVisibleLeaf>()
+			: new Map(this.visibleLeafCache.get(gitDirectory));
+		if (inclusions !== null && inclusions.length > 0) {
+			for (const relativePath of cache.keys()) {
+				if (inclusions.some((inclusion) => isPathAtOrBelow(inclusion, relativePath))) {
+					cache.delete(relativePath);
+				}
+			}
+		}
+		for (const leaf of staged.leaves) {
+			const objectId = staged.objectIds.get(leaf.relativePath);
+			if (objectId === undefined) continue;
+			if (!leaf.cacheable) {
+				cache.delete(leaf.relativePath);
+				continue;
+			}
+			cache.set(leaf.relativePath, { ...leaf, objectId, verifiedAtNs: staged.verifiedAtNs });
+		}
+		this.visibleLeafCache.set(gitDirectory, cache);
+	}
+
+	private async assertVisibleLeavesUnchanged(
+		cwd: string,
+		leaves: readonly VisibleLeaf[],
+		requestDirectory?: string,
+	): Promise<void> {
+		if (requestDirectory !== undefined) {
+			const inspected = await this.nativeMetadata.inspect(
+				cwd,
+				leaves.map((leaf) => leaf.relativePath),
+				requestDirectory,
+			);
+			if (inspected !== undefined) {
+				for (let index = 0; index < leaves.length; index += 1) {
+					const leaf = leaves[index]!;
+					const metadata = nativeVisibleLeafMetadata(inspected[index]!);
+					if (metadata === null || visibleLeafFingerprint(metadata) !== leaf.fingerprint) {
+						throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化：${leaf.relativePath}`);
+					}
+				}
+				return;
+			}
+		}
+		await assertNoSymlinkParents(cwd, leaves.map((leaf) => leaf.relativePath));
+		await mapConcurrentOrdered(leaves, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
+			this.assertVisibleLeafUnchanged(cwd, leaf));
 	}
 
 	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) => {
+		const metadata = await lstat(join(cwd, ...leaf.relativePath.split("/")), { bigint: true }).catch((error) => {
 			if (hasErrorCode(error, "ENOENT")) return null;
 			throw error;
 		});
-		if (metadata === null || visibleLeafFingerprint(metadata) !== leaf.fingerprint) {
+		if (metadata === null || visibleLeafFingerprint(visibleLeafMetadataFromStats(metadata)) !== leaf.fingerprint) {
 			throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化：${leaf.relativePath}`);
 		}
 	}
@@ -864,6 +978,7 @@ export class SnapshotStore {
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
 		exactExclusions: ReadonlySet<string>,
+		requestDirectory: string,
 	): Promise<VisibleLeaf[]> {
 		const paths = await this.queryVisibleLeafPaths(
 			cwd,
@@ -873,33 +988,46 @@ export class SnapshotStore {
 			exclusions,
 			exactExclusions,
 		);
-		const leaves = await mapConcurrentOrdered(paths, FILE_SYSTEM_INSPECTION_CONCURRENCY, async (relativePath) => {
+		const nativeEntries = await this.nativeMetadata.inspect(cwd, paths, requestDirectory);
+		const metadataEntries = nativeEntries === undefined
+			? await this.collectVisibleLeafMetadataFallback(cwd, paths)
+			: nativeEntries.map((entry) => nativeVisibleLeafMetadata(entry));
+		const leaves: VisibleLeaf[] = [];
+		for (let index = 0; index < paths.length; index += 1) {
+			const relativePath = paths[index]!;
+			const metadata = metadataEntries[index]!;
+			if (metadata === null) continue;
+			if (metadata.kind === "other") {
+				throw new SnapshotStoreError("capture_failed", `不支持的工作区文件类型：${relativePath}`);
+			}
+			const cacheable = visibleLeafMetadataCacheable(metadata);
+			leaves.push({
+				relativePath,
+				kind: metadata.kind,
+				mode: metadata.kind === "symlink"
+					? 0o120000
+					: (metadata.mode & 0o111n) === 0n ? 0o100644 : 0o100755,
+				fingerprint: visibleLeafFingerprint(metadata),
+				changedAtNs: metadata.mtimeNs > metadata.ctimeNs ? metadata.mtimeNs : metadata.ctimeNs,
+				cacheable,
+			});
+		}
+		return leaves;
+	}
+
+	private async collectVisibleLeafMetadataFallback(
+		cwd: string,
+		paths: readonly string[],
+	): Promise<readonly (VisibleLeafMetadata | null)[]> {
+		await assertNoSymlinkParents(cwd, paths);
+		return mapConcurrentOrdered(paths, FILE_SYSTEM_INSPECTION_CONCURRENCY, async (relativePath) => {
 			relativeSafePath(cwd, relativePath);
-			await assertNoSymlinkEscape(cwd, relativePath);
-			const metadata = await lstat(join(cwd, ...relativePath.split("/"))).catch((error) => {
+			const metadata = await lstat(join(cwd, ...relativePath.split("/")), { bigint: true }).catch((error) => {
 				if (hasErrorCode(error, "ENOENT")) return null;
 				throw error;
 			});
-			if (metadata === null) return null;
-			if (metadata.isSymbolicLink()) {
-				return {
-					relativePath,
-					kind: "symlink" as const,
-					mode: 0o120000,
-					fingerprint: visibleLeafFingerprint(metadata),
-				};
-			}
-			if (metadata.isFile()) {
-				return {
-					relativePath,
-					kind: "file" as const,
-					mode: (metadata.mode & 0o111) === 0 ? 0o100644 : 0o100755,
-					fingerprint: visibleLeafFingerprint(metadata),
-				};
-			}
-			throw new SnapshotStoreError("capture_failed", `不支持的工作区文件类型：${relativePath}`);
+			return metadata === null ? null : visibleLeafMetadataFromStats(metadata);
 		});
-		return leaves.filter((leaf): leaf is VisibleLeaf => leaf !== null);
 	}
 
 	private async validateIgnoreQuery(
@@ -937,6 +1065,7 @@ export class SnapshotStore {
 		}
 		await mkdir(dirname(gitDirectory), { recursive: true });
 		await this.runGit(["init", "--bare", "--quiet", gitDirectory], { env: cleanGitEnvironment() });
+		this.visibleLeafCache.delete(gitDirectory);
 		await this.configurePrivateRepository(gitDirectory);
 	}
 
@@ -1559,18 +1688,54 @@ function indexInfoBatches(
 	return result;
 }
 
-function visibleLeafFingerprint(metadata: Stats): string {
-	return checksum(canonicalJson({
+function visibleLeafMetadataFromStats(metadata: BigIntStats): VisibleLeafMetadata {
+	return {
 		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,
+		mtimeNs: metadata.mtimeNs,
+		ctimeNs: metadata.ctimeNs,
+	};
+}
+
+function nativeVisibleLeafMetadata(entry: NativeMetadataEntry): VisibleLeafMetadata | null {
+	if (entry.kind === "absent") return null;
+	if (
+		entry.dev === undefined || entry.ino === undefined || entry.mode === undefined ||
+		entry.size === undefined || entry.mtimeNs === undefined || entry.ctimeNs === undefined
+	) {
+		throw new SnapshotStoreError("capture_failed", `native metadata 缺少字段：${entry.path}`);
+	}
+	return {
+		kind: entry.kind,
+		dev: entry.dev,
+		ino: entry.ino,
+		mode: entry.mode,
+		size: entry.size,
+		mtimeNs: entry.mtimeNs,
+		ctimeNs: entry.ctimeNs,
+	};
+}
+
+function visibleLeafFingerprint(metadata: VisibleLeafMetadata): string {
+	return checksum(canonicalJson({
+		kind: metadata.kind,
+		dev: metadata.dev.toString(),
+		ino: metadata.ino.toString(),
+		mode: metadata.mode.toString(),
+		size: metadata.size.toString(),
+		mtimeNs: metadata.mtimeNs.toString(),
+		ctimeNs: metadata.ctimeNs.toString(),
 	}));
 }
 
+function visibleLeafMetadataCacheable(metadata: VisibleLeafMetadata): boolean {
+	// dev/ino/ctime 缺失时无法证明路径仍指向同一未修改对象，必须回退内容 hash。
+	return metadata.dev !== 0n && metadata.ino !== 0n && metadata.ctimeNs > 0n;
+}
+
 async function mapConcurrentOrdered<T, R>(
 	values: readonly T[],
 	concurrency: number,