@davideasden/pi-undo 0.2.9 → 0.2.11

package/package.json

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

package/src/encoding.ts

@@ -44,6 +44,32 @@ export function checksum(value: string | Uint8Array): string {
 	return createHash("sha256").update(input).digest("hex");
 }
 
+export function sameWorkspaceSnapshot(left: SnapshotManifest, right: SnapshotManifest): boolean {
+	if (
+		left.schemaVersion !== right.schemaVersion ||
+		left.workspaceIdentity !== right.workspaceIdentity ||
+		left.topologyFingerprint !== right.topologyFingerprint ||
+		left.coverage !== right.coverage ||
+		left.roots.length !== right.roots.length
+	) return false;
+	return left.roots.every((root, index) => {
+		const candidate = right.roots[index];
+		return candidate !== undefined &&
+			root.relativeRoot === candidate.relativeRoot &&
+			root.parentRoot === candidate.parentRoot &&
+			root.state === candidate.state &&
+			root.sourceIdentity === candidate.sourceIdentity &&
+			root.privateRepositoryId === candidate.privateRepositoryId &&
+			(root.gitlinkOid ?? null) === (candidate.gitlinkOid ?? null) &&
+			root.treeId === candidate.treeId &&
+			root.coverage === candidate.coverage &&
+			root.ignorePolicy === candidate.ignorePolicy &&
+			root.ignoreClosure === candidate.ignoreClosure &&
+			root.objectClosure === candidate.objectClosure &&
+			sameStrings(root.ignoredPresentPaths, candidate.ignoredPresentPaths);
+	});
+}
+
 export function ignoredPresentClosure(
 	root: Pick<SnapshotRoot, "coverage" | "ignorePolicy" | "ignoredPresentPaths">,
 ): string {
@@ -202,6 +228,10 @@ export function assertOperationId(value: unknown): string {
 	return value;
 }
 
+function sameStrings(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
 function encodeJson(value: unknown, ancestors: Set<object>): string {
 	if (value === null) {
 		return "null";

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/pi-runtime.ts

@@ -12,7 +12,7 @@ import {
 	type ControllerInitialState,
 } from "./controller.ts";
 import { finalizeDurablePack, hasDurablePack, loadDurablePack } from "./durable-pack.ts";
-import { assertCursor, canonicalJson, checksum } from "./encoding.ts";
+import { assertCursor, canonicalJson, checksum, sameWorkspaceSnapshot } from "./encoding.ts";
 import { JournalStore, finalizeCursorMarker, inspectCursorMarkers } from "./journal.ts";
 import type { CheckpointRecord, ManifestId, SessionFileIdentity } from "./model.ts";
 import {
@@ -223,6 +223,8 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 			return capture(scopePaths);
 		},
 		changedPaths: async (before, after) => {
+			// 完全相同的 workspace snapshot 只撤回 session 分支；无需再次展开所有 root tree。
+			if (sameWorkspaceSnapshot(before, after)) return [];
 			const plan = await restore.plan(before, after);
 			return [...new Set([...plan.deletePaths, ...plan.writePaths])].sort();
 		},

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";
 
@@ -36,12 +38,15 @@ const TREE_BLOB_MEMBERSHIP_LIMIT = 65_536;
 const HASH_BATCH_MAX_PATHS = process.platform === "win32" ? 128 : 2_048;
 const HASH_BATCH_MAX_ARGUMENT_BYTES = process.platform === "win32" ? 24 * 1024 : 128 * 1024;
 const HASH_BATCH_CONCURRENCY = 4;
+const ROOT_CAPTURE_CONCURRENCY = 4;
 const FILE_SYSTEM_INSPECTION_CONCURRENCY = 32;
+const IGNORED_METADATA_BATCH_SIZE = 1_024;
 const INDEX_BATCH_MAX_ENTRIES = 4_096;
 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 +75,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 +93,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 +125,7 @@ export interface SnapshotStoreOptions {
 	readonly discovery?: RootDiscovery;
 	readonly lock?: WorkspaceLock;
 	readonly clock?: () => number;
+	readonly nativeMetadata?: NativeMetadataPort;
 }
 
 export interface CaptureOptions {
@@ -141,11 +177,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 +193,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 {
@@ -221,28 +260,41 @@ export class SnapshotStore {
 			const transactionsRoot = join(storeDirectory, "transactions");
 			await mkdir(transactionsRoot, { recursive: true });
 			transactionDirectory = await mkdtemp(join(transactionsRoot, "capture-"));
-
-			const roots: SnapshotRoot[] = [];
-			for (const root of topology.roots) {
-				if (root.state !== "active") {
-					const coverage = rootCaptureCoverage(root.relativeRoot, scope);
-					roots.push(snapshotRoot(root, {
-						treeId: null,
-						coverage,
-						...ignoredPresentProof(coverage, []),
-						objectClosure: inactiveRootClosure(root),
-					}));
-					continue;
-				}
-				const captured = await this.captureRoot(
-					topology,
-					root,
-					transactionDirectory,
-					scope,
-					artifactExclusions,
-				);
-				roots.push(snapshotRoot(root, captured));
-			}
+			const activeTransactionDirectory = transactionDirectory;
+
+			// 每个 root 使用独立私有 ODB、index 与 worktree；结果保持输入顺序，缓存仍在整个 capture
+			// 持久化成功后统一发布，因此可并行缩短 nested-repository workspace 的关键路径。
+			const capturedRoots = await mapConcurrentOrdered(
+				topology.roots,
+				ROOT_CAPTURE_CONCURRENCY,
+				async (root): Promise<{ readonly root: SnapshotRoot; readonly cacheUpdate?: VisibleLeafCacheUpdate }> => {
+					if (root.state !== "active") {
+						const coverage = rootCaptureCoverage(root.relativeRoot, scope);
+						return {
+							root: snapshotRoot(root, {
+								treeId: null,
+								coverage,
+								...ignoredPresentProof(coverage, []),
+								objectClosure: inactiveRootClosure(root),
+							}),
+						};
+					}
+					const captured = await this.captureRoot(
+						topology,
+						root,
+						activeTransactionDirectory,
+						scope,
+						artifactExclusions,
+					);
+					return {
+						root: snapshotRoot(root, captured),
+						cacheUpdate: captured.cacheUpdate,
+					};
+				},
+			);
+			const roots = capturedRoots.map((captured) => captured.root);
+			const cacheUpdates = capturedRoots.flatMap((captured) =>
+				captured.cacheUpdate === undefined ? [] : [captured.cacheUpdate]);
 
 			await this.assertTopology(topology, "捕获期间 topology 已变化");
 			const content = {
@@ -261,6 +313,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 +677,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 +715,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(
@@ -675,6 +733,7 @@ export class SnapshotStore {
 			inclusions,
 			exclusions,
 			exactExclusions,
+			transactionDirectory,
 		);
 		const treeId = (await this.runGit(["write-tree"], { cwd: absoluteRoot, env: environment })).trim();
 		if (!isObjectId(treeId)) {
@@ -687,6 +746,7 @@ export class SnapshotStore {
 			coverage,
 			...ignoredPresentProof(coverage, ignoredPresentPaths),
 			objectClosure: treeObjectClosure(treeId, entries),
+			cacheUpdate: { gitDirectory, staged, inclusions },
 		};
 	}
 
@@ -697,6 +757,7 @@ export class SnapshotStore {
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
 		exactExclusions: ReadonlySet<string>,
+		requestDirectory: string,
 	): Promise<string[]> {
 		if (inclusions === null) {
 			return [];
@@ -715,7 +776,8 @@ export class SnapshotStore {
 			"--",
 			...pathspecs,
 		], { cwd, env: gitBacked ? sourceGitEnvironment() : environment });
-		const result = new Set<string>();
+		const candidates: string[] = [];
+		const seen = new Set<string>();
 		for (const relativePath of parseNulPaths(output)) {
 			if (
 				exclusions.some((excluded) => isPathAtOrBelow(excluded, relativePath)) ||
@@ -723,23 +785,74 @@ export class SnapshotStore {
 			) {
 				continue;
 			}
-			await assertNoSymlinkEscape(cwd, relativePath);
-			const metadata = await lstat(join(cwd, ...relativePath.split("/"))).catch((error) => {
-				if (hasErrorCode(error, "ENOENT")) return null;
-				throw error;
-			});
-			if (metadata === null) {
-				continue;
+			if (seen.has(relativePath)) {
+				throw new SnapshotStoreError("capture_failed", `ignored-present proof 包含重复路径：${relativePath}`);
 			}
-			if (!metadata.isFile() && !metadata.isSymbolicLink()) {
+			seen.add(relativePath);
+			candidates.push(relativePath);
+		}
+		// ignored build/vendor trees 常含数万叶子；复用同一批量 metadata 协议，避免逐路径重复
+		// 遍历父目录。Native 与 fallback 都在叶子扫描前后复核共享父目录。
+		const nativeEntries = await this.inspectIgnoredMetadataBatches(cwd, candidates, requestDirectory);
+		const kinds = nativeEntries === undefined
+			? await this.collectIgnoredPresentKindsFallback(cwd, candidates)
+			: nativeEntries.map((entry) => entry.kind);
+		const result: string[] = [];
+		for (let index = 0; index < candidates.length; index += 1) {
+			const relativePath = candidates[index]!;
+			const kind = kinds[index]!;
+			if (kind === "absent") continue;
+			if (kind !== "file" && kind !== "symlink") {
 				throw new SnapshotStoreError("capture_failed", `ignored-present proof 只接受叶子路径：${relativePath}`);
 			}
-			if (result.has(relativePath)) {
-				throw new SnapshotStoreError("capture_failed", `ignored-present proof 包含重复路径：${relativePath}`);
+			result.push(relativePath);
+		}
+		return result.sort(comparePaths);
+	}
+
+	private async inspectIgnoredMetadataBatches(
+		cwd: string,
+		paths: readonly string[],
+		requestDirectory: string,
+	): Promise<readonly NativeMetadataEntry[] | undefined> {
+		const result: NativeMetadataEntry[] = [];
+		for (let offset = 0; offset < paths.length; offset += IGNORED_METADATA_BATCH_SIZE) {
+			const batch = paths.slice(offset, offset + IGNORED_METADATA_BATCH_SIZE);
+			const inspected = await this.nativeMetadata.inspect(cwd, batch, requestDirectory);
+			if (inspected === undefined) {
+				if (result.length > 0) {
+					throw new SnapshotStoreError("capture_failed", "native ignored metadata 能力在批次间变化");
+				}
+				return undefined;
 			}
-			result.add(relativePath);
+			result.push(...inspected);
 		}
-		return [...result].sort(comparePaths);
+		return result;
+	}
+
+	private async collectIgnoredPresentKindsFallback(
+		cwd: string,
+		paths: readonly string[],
+	): Promise<readonly NativeMetadataEntry["kind"][]> {
+		const result: NativeMetadataEntry["kind"][] = [];
+		for (let offset = 0; offset < paths.length; offset += IGNORED_METADATA_BATCH_SIZE) {
+			const batch = paths.slice(offset, offset + IGNORED_METADATA_BATCH_SIZE);
+			await assertNoSymlinkParents(cwd, batch);
+			const kinds = await mapConcurrentOrdered(batch, FILE_SYSTEM_INSPECTION_CONCURRENCY, async (relativePath) => {
+				const metadata = await lstat(join(cwd, ...relativePath.split("/"))).catch((error) => {
+					if (hasErrorCode(error, "ENOENT")) return null;
+					throw error;
+				});
+				return metadata === null
+					? "absent" as const
+					: metadata.isFile() ? "file" as const
+					: metadata.isSymbolicLink() ? "symlink" as const
+					: "other" as const;
+			});
+			await assertNoSymlinkParents(cwd, batch);
+			result.push(...kinds);
+		}
+		return result;
 	}
 
 	private async stageWorktree(
@@ -749,7 +862,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 +872,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 +899,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 +919,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 +930,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 +1045,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 +1055,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 +1132,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 +1755,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,