@davideasden/pi-undo 0.2.9 → 0.2.10

package/package.json

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

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,