@davideasden/pi-undo 0.2.25 → 0.2.26

package/README.md

@@ -161,7 +161,11 @@ recovery_required
 
 ### Performance Notes
 
-本次优化将普通文件原生恢复路径的完整拓扑扫描从 7 次减到 5 次，并以有界并发枚举目录。仍会发现 Git 忽略目录中的嵌套仓库，保留路径枚举后与文件恢复后的拓扑复核。没有使用 TTL 缓存或默认跳过 `node_modules`。
+普通文件原生恢复路径保留 5 次完整拓扑扫描。macOS/Linux 的新版 helper 使用不跟随符号链接的目录句柄扫描，仍会发现 Git 忽略目录中的嵌套仓库。小工作区根据上次扫描规模选择 TypeScript 完整重扫，避免进程启动开销；没有使用 TTL 缓存或默认跳过 `node_modules`。
+
+原生恢复现支持已有父目录中的普通文件删除，以及覆盖、创建、删除混合计划。扩展能力通过 `restore-files-v2` 探测；旧 helper、缺少二进制、目录操作及超出句柄预算的计划继续走 TypeScript 路径。pack 持久化、内容校验、no-clobber 与恢复依据均保留。
+
+本机 macOS arm64 的三次 undo 中位数：3,000 包／1 文件从 1,976 ms 降至 924 ms，10,000 包／1 文件从 5,857 ms 降至 2,755 ms；100 文件的子目录撤销从 517 ms 降至 180 ms，混合撤销从 711 ms 降至 186 ms。测量方法和限制见 [原生性能验证记录](docs/native-performance.md)。
 
 可通过真实 Pi 0.86.1 SDK 和离线 faux provider 运行大型工作区基准；它覆盖 3,000／10,000 个依赖包、修改 1／100 个文件，每组撤回三次并验证重做：
 

package/docs/native-performance.md

@@ -0,0 +1,52 @@
+# 原生目录扫描与普通文件恢复性能验证
+
+这批优化基于 `d7d80230`，保留 undo 的五个拓扑检查点，降低完整目录扫描成本，并扩大已有父目录中的普通文件原生恢复范围。
+
+## 实现与边界
+
+- `scan-directories-v1` 在 macOS/Linux 上通过 `openat(O_DIRECTORY | O_NOFOLLOW)` 逐级打开目录，以目录流识别 Git 标记候选。扫描 ignored 目录，不进入名称恰为 `.git` 的元数据目录，不跟随符号链接；标记大小写、损坏仓库、失效 worktree 指针、Git index 与 submodule 仍由现有 TypeScript/Git 逻辑解释。
+- 每次重新扫描。上次目录数量仅选择执行器：小于 64 个目录时使用 TypeScript 完整遍历；增长后可重新进入原生扫描。没有缓存拓扑结果，也没有省略任何检查点。
+- 目录句柄、父目录绑定与扫描前后目录时间戳必须一致。扫描时并发增删目录项会使原生扫描失败，防止静默接受不完整结果；它不提供跨整个工作区的原子快照。能力确认后的路径错误向上传递。超过 128 层时，helper 明确返回 `depth_limit`，丢弃部分结果，由 TypeScript 从根重扫。
+- 原生扫描使用操作剩余预算，并遵守 `PI_UNDO_OPERATION_TIMEOUT_MS`（默认 300 秒）。能力探测只在私有目录运行，缺失能力时回退；取消、超时及无法确认子进程终止均保留现有错误处理契约。探测取消不会永久污染能力缓存。
+- `restore-files-v2` 支持普通文件覆盖、创建、删除的混合计划，以及子目录中的文件删除。父目录必须已经存在。读取、校验、no-clobber 安装及隔离均绑定同一组父目录句柄；最多保留 128 个非根父目录句柄。目录创建/删除、类型替换、过多父目录与不支持的平台继续使用 TypeScript。
+- durable pack 格式与恢复协议保持不变。仍在修改前发布并持久化 pack，逐项校验内容和 mode，保留同 inode 的 ownership artifacts。失败时由现有 packed recovery 回滚；外来冲突文件不会被当成本次产物删除。
+
+## 实测结果
+
+环境为本机 macOS arm64、Node 23.11.1、真实 Pi 0.86.1 SDK 与离线 faux provider。每个场景执行三次 undo，中间执行 redo 并等待后台恢复/持久化清理结束；校验文件内容、撤回/重做历史状态和扫描次数。表内为中位数，单位毫秒。基线与优化版本在同一机器先后执行，未施加墙钟性能断言。
+
+| 场景 | 优化前 | 优化后 | 耗时降低 |
+| --- | ---: | ---: | ---: |
+| 无依赖目录，修改 1 文件 | 146 | 148 | 约持平 |
+| 3,000 包，修改 1 文件 | 1,976 | 924 | 53% |
+| 10,000 包，修改 1 文件 | 5,857 | 2,755 | 53% |
+| 100 文件全部覆盖 | 179 | 182 | 约持平 |
+| 100 文件在根目录新增后撤销 | 177 | 174 | 约持平 |
+| 100 文件在已有子目录新增后撤销 | 517 | 180 | 65% |
+| 50 文件覆盖、50 文件新增后混合撤销 | 711 | 186 | 74% |
+
+分阶段计时中，3,000 包场景五次扫描合计从 1,759 ms 降至 716 ms；10,000 包从 5,470 ms 降至 2,398 ms。全部测量仍为五次扫描。新增目录的撤销测试保留父目录中的 `keep.txt`，因此测量的是文件删除，不含目录删除。混合与子目录场景原先未进入 native，优化后三次均调用原生恢复一次。
+
+另一个既有大型工作区基准覆盖 3,000／10,000 包 × 1／100 文件，四组均通过内容、redo 和 `[5, 5, 5]` 扫描次数断言。该次单独运行的中位数依次为 878、923、2,582、2,673 ms；与分阶段诊断是不同批次，不把两批耗时混作同一组数据。
+
+这些是三次采样的本机结果，主要证明已观察到的热路径得到改善。磁盘、目录结构、并发写入和机器负载会影响绝对耗时；没有从这些结果推断其他操作系统上的收益。
+
+## 复现与验证
+
+最终验证通过：默认原生路径 617 项、强制 TypeScript 回退 586 项、Rust 单测 8 项；TypeScript 类型检查、四组大型工作区基准及 npm 打包内容检查通过。跳过项为不适用平台/能力及按需基准，不计入通过数。
+
+```bash
+npm run build:native
+cp native/pi-undo-fs/target/release/pi-undo-fs native/bin/pi-undo-fs-darwin-arm64
+npm run test:native
+npm test
+PI_UNDO_DISABLE_NATIVE=1 npm test
+npm run typecheck
+PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts
+```
+
+上面的二进制复制路径用于本次 macOS arm64 环境；其他平台须使用对应构建产物。此批已更新仓库现有的 macOS arm64 二进制。Linux、其他架构和 Windows 的源码构建/运行不在本机验证范围内；缺少二进制或扩展能力时会回退，发布时仍需现有六平台构建流程提供对应产物。
+
+补充测试覆盖：原生/TypeScript 拓扑一致性、ignored 嵌套仓库、大小写不同的 Git 标记、符号链接及目录删除/替换、深度回退、取消后重新探测、超时、混合计划回滚/前滚、外来文件冲突、旧 helper 门控，以及 128／129 个父目录的边界。
+
+独立审查运行器异常退出，正式审查结果未能落盘。已保留失败运行的状态与补丁证据，并人工核对日志中的具体意见；这不计为独立审查通过。已修复候选错误类型与扫描预算，补充句柄边界测试。旧 helper 在混合计划中仍可能先准备 pack 再回退，存在额外准备开销；兼容性分类与平台发布覆盖也仍需后续维护。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.25",
+	"version": "0.2.26",
 	"description": "Persistent workspace undo and redo for Pi",
 	"license": "MIT",
 	"type": "module",
@@ -34,13 +34,14 @@
 		"extensions",
 		"src",
 		"native/bin",
-		"README.md"
+		"README.md",
+		"docs/native-performance.md"
 	],
 	"scripts": {
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"test:integration": "vitest run test/extension.integration.test.ts test/pi-runtime.test.ts test/pi-sdk.integration.test.ts",
-		"test:native": "cargo test --manifest-path native/pi-undo-fs/Cargo.toml && vitest run test/native-restore.test.ts test/durable-pack.test.ts test/packed-recovery.test.ts",
+		"test:native": "cargo test --manifest-path native/pi-undo-fs/Cargo.toml && vitest run test/native-restore.test.ts test/native-directory-scan.test.ts test/root-discovery.test.ts test/durable-pack.test.ts test/packed-recovery.test.ts",
 		"build:native": "cargo build --release --manifest-path native/pi-undo-fs/Cargo.toml",
 		"typecheck": "tsc --noEmit",
 		"pack:dry-run": "npm pack --dry-run"

package/src/native-capabilities.ts

@@ -0,0 +1,34 @@
+import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
+import { checkOperation, OperationError, operationProcessOptions, rethrowOperationFailure } from "./operation-context.ts";
+
+/** 在私有目录探测，防止旧 helper 把 --capabilities 当成工作区里的请求文件。 */
+export async function probeNativeCapability(
+	executable: string,
+	capability: string,
+	isolatedDirectory: string,
+): Promise<boolean> {
+	const budget = operationProcessOptions(5_000);
+	try {
+		const result = await runSupervisedProcess({
+			command: executable,
+			args: ["--capabilities"],
+			cwd: isolatedDirectory,
+			...budget,
+			outputLimitBytes: 64 * 1024,
+			outputOverflow: "terminate",
+		});
+		if (!result.stopped) throw new GitRunError("git_termination_failed", "native 能力探测进程未能确认终止");
+		if (result.outcome === "cancelled") {
+			checkOperation();
+			throw new OperationError("operation_cancelled", "native 能力探测已被取消");
+		}
+		checkOperation();
+		if (result.outcome !== "exit" || result.code !== 0) return false;
+		const value: unknown = JSON.parse(result.stdout.toString("utf8"));
+		return typeof value === "object" && value !== null && "ok" in value && value.ok === true &&
+			"capabilities" in value && Array.isArray(value.capabilities) && value.capabilities.includes(capability);
+	} catch (error) {
+		rethrowOperationFailure(error);
+		return false;
+	}
+}

package/src/native-directory-scan.ts

@@ -0,0 +1,114 @@
+import { constants } from "node:fs";
+import { access, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
+import { probeNativeCapability } from "./native-capabilities.ts";
+import { nativeExecutable } from "./native-restore.ts";
+import { checkOperation, configuredTimeout, OperationError, operationProcessOptions } from "./operation-context.ts";
+
+export interface NativeRepositoryCandidate {
+	readonly path: string;
+	readonly dev: bigint;
+	readonly ino: bigint;
+}
+
+export interface NativeDirectoryScan {
+	readonly directories: number;
+	readonly repositories: readonly NativeRepositoryCandidate[];
+}
+
+export interface NativeDirectoryScanPort {
+	scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined>;
+}
+
+/** 只缓存 helper 能力；每个拓扑检查点均重新完整扫描工作区，包括 ignored 目录。 */
+export class NativeDirectoryScanner implements NativeDirectoryScanPort {
+	private readonly executable: string | undefined;
+	private capability: Promise<boolean> | undefined;
+
+	constructor(executable = nativeExecutable()) {
+		this.executable = process.env.PI_UNDO_DISABLE_NATIVE === "1" || process.platform === "win32"
+			? undefined : executable;
+	}
+
+	async scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined> {
+		checkOperation();
+		if (this.executable === undefined || (this.capability !== undefined && !await this.capability)) return undefined;
+		const requestDirectory = await mkdtemp(join(tmpdir(), "pi-undo-native-scan-"));
+		try {
+			this.capability ??= this.supportsScan(requestDirectory).catch((error) => {
+				// 取消或未确认终止不能污染后续操作的能力缓存。
+				this.capability = undefined;
+				throw error;
+			});
+			if (!await this.capability) return undefined;
+			const budget = operationProcessOptions(configuredTimeout("PI_UNDO_OPERATION_TIMEOUT_MS", 300_000));
+			const requestPath = join(requestDirectory, "request.json");
+			await writeFile(requestPath, JSON.stringify({ schemaVersion: 1, workspaceRoot }), { mode: 0o600, flag: "wx" });
+			const result = await runSupervisedProcess({
+				command: this.executable,
+				args: ["--scan-directories", requestPath],
+				...budget,
+				outputLimitBytes: 32 * 1024 * 1024,
+				outputOverflow: "terminate",
+			});
+			if (!result.stopped) throw new GitRunError("git_termination_failed", "native 目录扫描进程未能确认终止");
+			if (result.outcome === "cancelled") {
+				checkOperation();
+				throw new OperationError("operation_cancelled", "native 目录扫描已被取消");
+			}
+			if (result.outcome === "timeout") throw new OperationError("operation_timeout", "native 目录扫描超时");
+			if (result.outcome !== "exit" || result.code !== 0) {
+				throw new Error(`native 目录扫描失败：${result.stderr.toString("utf8").trim() || result.outcome}`);
+			}
+			checkOperation();
+			return parseScanResponse(result.stdout.toString("utf8"));
+		} finally {
+			await rm(requestDirectory, { recursive: true, force: true }).catch(() => {});
+		}
+	}
+
+	private async supportsScan(directory: string): Promise<boolean> {
+		try {
+			await access(this.executable!, constants.X_OK);
+		} catch {
+			return false;
+		}
+		return probeNativeCapability(this.executable!, "scan-directories-v1", directory);
+	}
+}
+
+function parseScanResponse(text: string): NativeDirectoryScan | undefined {
+	const value: unknown = JSON.parse(text);
+	// 深度上限是执行器的资源边界；此时丢弃部分结果，由 TypeScript 从根完整重扫。
+	if (isRecord(value) && value.ok === false && value.code === "depth_limit") return undefined;
+	if (!isRecord(value) || value.ok !== true || !Number.isSafeInteger(value.directories) ||
+		(value.directories as number) < 1 || !Array.isArray(value.repositories) ||
+		value.repositories.length >= (value.directories as number)) {
+		throw new Error("native 目录扫描响应无效");
+	}
+	const seen = new Set<string>();
+	const repositories = value.repositories.map((candidate): NativeRepositoryCandidate => {
+		if (!isRecord(candidate) || typeof candidate.path !== "string" || candidate.path.includes("\0") ||
+			candidate.path.split("/").some((part) => part === "" || part === "." || part === ".." || part === ".git") ||
+			seen.has(candidate.path)) {
+			throw new Error("native 仓库候选路径无效");
+		}
+		seen.add(candidate.path);
+		return { path: candidate.path, dev: parseIdentity(candidate.dev), ino: parseIdentity(candidate.ino) };
+	});
+	return { directories: value.directories as number, repositories };
+}
+
+function parseIdentity(value: unknown): bigint {
+	if (typeof value !== "string" || !/^(?:0|[1-9][0-9]{0,19})$/.test(value) || BigInt(value) > (1n << 64n) - 1n) {
+		throw new Error("native 目录身份字段无效");
+	}
+	return BigInt(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/native-restore.ts

@@ -6,6 +6,7 @@ import { dirname, join } from "node:path";
 import type { DurablePack } from "./durable-pack.ts";
 import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
 import { OperationError, type OperationProcessOptions, operationProcessOptions, rethrowOperationFailure } from "./operation-context.ts";
+import { probeNativeCapability } from "./native-capabilities.ts";
 import type { MutationJournal } from "./mutation-journal.ts";
 
 const NATIVE_TIMEOUT_MS = 120_000;
@@ -23,6 +24,7 @@ export async function createNativeFileBatch(options: {
 	readonly journal: MutationJournal;
 	/** 测试注入用；默认使用随包分发的平台二进制。 */
 	readonly executable?: string;
+	readonly requiredCapability?: "restore-files-v2";
 }): Promise<NativeFileBatch | undefined> {
 	if (process.env.PI_UNDO_DISABLE_NATIVE === "1") return undefined;
 	const executable = options.executable ?? nativeExecutable();
@@ -32,6 +34,9 @@ export async function createNativeFileBatch(options: {
 	} catch {
 		return undefined;
 	}
+	if (options.requiredCapability !== undefined && !await probeNativeCapability(
+		executable, options.requiredCapability, dirname(options.journal.storagePath),
+	)) return undefined;
 	const execute = async (pack: DurablePack, requestPath: string, verifyOnly: boolean): Promise<void> => {
 		const paths = pack.paths();
 		if (paths.length === 0) return;
@@ -85,6 +90,13 @@ export async function createNativeFileBatch(options: {
 	};
 }
 
+export function nativeRestoreCapability(pack: DurablePack): "restore-files-v2" | undefined {
+	const paths = pack.paths();
+	const deletes = paths.filter((path) => pack.artifacts(path)?.target === null);
+	return deletes.some((path) => path.includes("/")) || (deletes.length > 0 && deletes.length < paths.length)
+		? "restore-files-v2" : undefined;
+}
+
 export function nativeExecutable(): string | undefined {
 	const platform = process.platform === "darwin"
 		? "darwin"

package/src/restore-engine.ts

@@ -18,7 +18,7 @@ import {
 import { assertManifest, assertOperationId, canonicalJson, checksum } from "./encoding.ts";
 import { MutationJournal } from "./mutation-journal.ts";
 import { allCompleted, checkOperation, rethrowOperationFailure, isUnconfirmedExit, operationFailure, withRecoveryBudget } from "./operation-context.ts";
-import { createNativeFileBatch } from "./native-restore.ts";
+import { createNativeFileBatch, nativeRestoreCapability } from "./native-restore.ts";
 import { recoverPackedMutations } from "./packed-recovery.ts";
 import type { ManifestId, RestorePath, SnapshotManifest, SnapshotRoot } from "./model.ts";
 import {
@@ -311,6 +311,7 @@ export class RestoreEngine {
 				workspaceRoot: this.workspaceRoot,
 				planDigest: cached.planDigest,
 				journal: cacheJournal,
+				requiredCapability: nativeRestoreCapability(cached.pack),
 			});
 			if (native === undefined || !await native.verifySource(cached.pack)) return false;
 			if (fromPersistentIndex) {
@@ -862,6 +863,7 @@ export class RestoreEngine {
 				workspaceRoot: this.workspaceRoot,
 				planDigest: plan.planDigest,
 				journal: options.mutationJournal,
+				requiredCapability: nativeRestoreCapability(durablePack),
 			})
 			: undefined;
 		if (durablePack !== undefined && nativeFileBatch === undefined) {
@@ -978,17 +980,16 @@ export class RestoreEngine {
 		currentPaths: ReadonlyMap<string, OwnedPath>,
 		targetPaths: ReadonlyMap<string, OwnedPath>,
 	): boolean {
-		const writeOnly = plan.deletePaths.length === 0 &&
-			plan.writePaths.length > 0 &&
-			plan.writePaths.every((path) => targetPaths.get(path)?.entry.kind === "file");
-		const deleteOnly = process.platform !== "win32" &&
-			plan.writePaths.length === 0 &&
-			plan.deletePaths.length > 0 &&
-			plan.deletePaths.every((path) =>
-				currentPaths.get(path)?.entry.kind === "file" &&
-				targetPaths.get(path) === undefined &&
-				!path.includes("/"));
-		return writeOnly || deleteOnly;
+		if (plan.deletePaths.length + plan.writePaths.length === 0) return false;
+		if (process.platform === "win32" && plan.deletePaths.length > 0) return false;
+		if (!plan.deletePaths.every((path) =>
+			currentPaths.get(path)?.entry.kind === "file" && targetPaths.get(path) === undefined)) return false;
+		if (!plan.writePaths.every((path) =>
+			targetPaths.get(path)?.entry.kind === "file" &&
+			(currentPaths.get(path) === undefined || currentPaths.get(path)?.entry.kind === "file"))) return false;
+		// 与 helper 的句柄上限一致；目录创建、类型替换及过多父目录继续使用 TypeScript。
+		const parents = new Set([...plan.deletePaths, ...plan.writePaths].flatMap(strictPathAncestors));
+		return process.platform === "win32" || parents.size <= 128;
 	}
 
 	private async applyNativeFilePlan(

package/src/root-discovery.ts

@@ -4,9 +4,11 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { checksum, topologyFingerprint } from "./encoding.ts";
 import { GitRunError, GitRunner } from "./git-runner.ts";
 import type { DiscoveryRoot } from "./model.ts";
+import { NativeDirectoryScanner, type NativeDirectoryScanPort, type NativeRepositoryCandidate } from "./native-directory-scan.ts";
 import { allCompleted, checkOperation, OperationError, reportOperationProgress } from "./operation-context.ts";
 
 const DIRECTORY_SCAN_CONCURRENCY = 16;
+const NATIVE_SCAN_MIN_DIRECTORIES = 64;
 const GIT_POINTER_MAX_BYTES = 4096;
 
 interface RepositoryInfo {
@@ -57,8 +59,8 @@ export type RootDiscoveryErrorCode = "workspace_not_found" | "discovery_failed";
 export class RootDiscoveryError extends Error {
 	readonly code: RootDiscoveryErrorCode;
 
-	constructor(code: RootDiscoveryErrorCode, message: string) {
-		super(message);
+	constructor(code: RootDiscoveryErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
 		this.name = "RootDiscoveryError";
 		this.code = code;
 	}
@@ -70,8 +72,9 @@ export interface RootDiscovery {
 
 export class RootDiscovery {
 	private readonly git: GitRunner;
+	private lastDirectoryCount: number | undefined;
 
-	constructor(git = new GitRunner()) {
+	constructor(git = new GitRunner(), private readonly nativeScan: NativeDirectoryScanPort = new NativeDirectoryScanner()) {
 		this.git = git;
 	}
 
@@ -114,6 +117,24 @@ export class RootDiscovery {
 		let level: Array<{ readonly path: string; readonly inspect: boolean }> = [{ path: directory, inspect: false }];
 		let scanned = 0;
 		reportOperationProgress("scan_directories");
+		// 上次规模只选择执行器；小工作区仍完整重扫，目录增长后会重新使用 native。
+		const native = this.lastDirectoryCount !== undefined && this.lastDirectoryCount < NATIVE_SCAN_MIN_DIRECTORIES
+			? undefined : await this.nativeScan.scan(workspaceIdentity);
+		if (native !== undefined) {
+			this.lastDirectoryCount = native.directories;
+			for (let index = 0; index < native.repositories.length; index += DIRECTORY_SCAN_CONCURRENCY) {
+				await allCompleted(native.repositories.slice(index, index + DIRECTORY_SCAN_CONCURRENCY).map(async (candidate) => {
+					checkOperation();
+					const path = join(workspaceIdentity, candidate.path);
+					await assertNativeCandidate(path, candidate);
+					const inspection = await this.inspectRepository(path, workspaceIdentity);
+					await assertNativeCandidate(path, candidate);
+					this.recordInspection(workspaceIdentity, inspection, activeRoots);
+				}));
+			}
+			reportOperationProgress(`scan_directories:${native.directories}`);
+			return;
+		}
 		while (level.length > 0) {
 			checkOperation();
 			const next: Array<{ readonly path: string; readonly inspect: true }> = [];
@@ -128,6 +149,7 @@ export class RootDiscovery {
 			}
 			level = next;
 		}
+		this.lastDirectoryCount = scanned;
 	}
 
 	private async scanDirectoryNode(
@@ -139,16 +161,7 @@ export class RootDiscovery {
 		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		if (candidate.inspect) {
 			const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
-			if (inspection.kind === "active") {
-				activeRoots.set(
-					inspection.repository.absoluteRoot,
-					this.activeRoot(workspaceIdentity, inspection.repository),
-				);
-			} else if (inspection.kind === "broken") {
-				activeRoots.set(inspection.absoluteRoot, brokenRoot(workspaceIdentity, inspection.absoluteRoot));
-			} else if (inspection.kind === "stale") {
-				activeRoots.set(inspection.absoluteRoot, staleWorktreeRoot(workspaceIdentity, inspection.absoluteRoot));
-			}
+			this.recordInspection(workspaceIdentity, inspection, activeRoots);
 			if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		}
 		checkOperation();
@@ -159,6 +172,20 @@ export class RootDiscovery {
 			.map((entry) => ({ path: join(candidate.path, entry.name), inspect: true as const }));
 	}
 
+	private recordInspection(
+		workspaceIdentity: string,
+		inspection: RepositoryInspection,
+		activeRoots: Map<string, DiscoveredRoot>,
+	): void {
+		if (inspection.kind === "active") {
+			activeRoots.set(inspection.repository.absoluteRoot, this.activeRoot(workspaceIdentity, inspection.repository));
+		} else if (inspection.kind === "broken") {
+			activeRoots.set(inspection.absoluteRoot, brokenRoot(workspaceIdentity, inspection.absoluteRoot));
+		} else if (inspection.kind === "stale") {
+			activeRoots.set(inspection.absoluteRoot, staleWorktreeRoot(workspaceIdentity, inspection.absoluteRoot));
+		}
+	}
+
 	private async inspectRepository(candidate: string, workspaceIdentity: string): Promise<RepositoryInspection> {
 		const marker = await gitMarkerState(candidate);
 		if (marker === "absent") {
@@ -295,6 +322,19 @@ export class RootDiscovery {
 	}
 }
 
+async function assertNativeCandidate(path: string, candidate: NativeRepositoryCandidate): Promise<void> {
+	try {
+		const metadata = await lstat(path, { bigint: true });
+		if (!metadata.isDirectory() || metadata.dev !== candidate.dev || metadata.ino !== candidate.ino ||
+			await realpath(path) !== path) {
+			throw new RootDiscoveryError("discovery_failed", `native 扫描后仓库目录身份发生变化：${candidate.path}`);
+		}
+	} catch (error) {
+		if (error instanceof RootDiscoveryError) throw error;
+		throw new RootDiscoveryError("discovery_failed", `无法复核 native 仓库候选：${candidate.path}`, { cause: error });
+	}
+}
+
 function syntheticRoot(workspaceIdentity: string): DiscoveredRoot {
 	return {
 		absoluteRoot: workspaceIdentity,