@davideasden/pi-undo 0.2.10 → 0.2.14

package/README.md

@@ -19,7 +19,7 @@ Each completed agent run creates a checkpoint that captures both the Pi session
 
 ## Requirements
 
-- Pi `0.80.10` or a compatible release.
+- Pi `0.80.10` 或更高版本（已在 0.84.4 上验证）。
 - Node.js `22.19.0` or later.
 - Git available on `PATH` (used internally for content-addressed snapshots).
 

package/extensions/pi-undo.ts

@@ -46,6 +46,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		let acceptedReplay: DeferredPrompt | undefined;
 		let activeCommands = new Set<symbol>();
 		let activeAction: "undo" | "redo" | undefined;
+		let captureFailureNotified = false;
 
 		const initialize = async (context: ExtensionContext): Promise<void> => {
 			const currentGeneration = ++generation;
@@ -55,6 +56,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			acceptedReplay = undefined;
 			activeCommands = new Set<symbol>();
 			activeAction = undefined;
+			captureFailureNotified = false;
 			try {
 				const next = await runtimeFactory(context, pi);
 				if (currentGeneration !== generation) return;
@@ -63,6 +65,8 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 				const history = next.controller.history();
 				if (history.locked) next.reporter.setRecoveryRequired("pending journal", next.recovery);
 				else next.reporter.setReady(history.undoCount, history.redoCount);
+				// 后台预热快照缓存，把新会话首次冷 capture 移出第一条 prompt 的关键路径。
+				next.controller.warmUp();
 			} catch (error) {
 				if (currentGeneration !== generation) return;
 				runtime = undefined;
@@ -213,7 +217,7 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 		pi.on("session_start", async (_event: unknown, context: ExtensionContext) => initialize(context));
 		pi.on("input", async (event: InputEvent, context: ExtensionContext) => {
 			const active = runtime;
-			if (active === undefined) return { action: "handled" as const };
+			if (active === undefined) return { action: "continue" as const };
 			const result = await active.controller.prepareInput(event.text, {
 				streaming: event.streamingBehavior !== undefined,
 			});
@@ -250,6 +254,14 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 					}
 				}
 			}
+			if (result.action === "continue" && active.controller.captureFailed() && !captureFailureNotified) {
+				captureFailureNotified = true;
+				const reason = active.controller.captureFailureReason();
+				context.ui.notify(
+					`pi-undo: pre-input snapshot failed${reason === undefined || reason.length === 0 ? "" : ` (${reason})`}; this run will not be undoable`,
+					"warning",
+				);
+			}
 			return result;
 		});
 		pi.on("before_agent_start", async () => {
@@ -286,11 +298,16 @@ export function createPiUndoExtension(runtimeFactory: PiUndoRuntimeFactory): (pi
 			return result;
 		});
 		pi.on("session_tree", async (event: PiSessionTreeEvent) => {
-			if (runtime?.isInternalNavigation?.()) return;
-			await runtime?.controller.afterTree({
+			const active = runtime;
+			if (active?.isInternalNavigation?.()) return;
+			const treeGeneration = generation;
+			await active?.controller.afterTree({
 				newLeafId: event.newLeafId,
 				navigationTargetLeafId: event.summaryEntry?.parentId ?? event.newLeafId,
 			});
+			if (active !== undefined && runtime === active && generation === treeGeneration) {
+				resumeDeferredPrompts(active, treeGeneration, "session state ambiguous");
+			}
 		});
 		pi.on("session_shutdown", async () => {
 			generation += 1;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.10",
+	"version": "0.2.14",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [
@@ -45,14 +45,15 @@
 		"pack:dry-run": "npm pack --dry-run"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "^0.80.10",
+		"@earendil-works/pi-coding-agent": ">=0.80.10",
 		"@earendil-works/pi-tui": "*"
 	},
 	"dependencies": {
 		"proper-lockfile": "4.1.2"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@earendil-works/pi-coding-agent": "0.84.4",
+		"@earendil-works/pi-tui": "0.84.4",
 		"@types/node": "24.12.4",
 		"@types/proper-lockfile": "4.1.4",
 		"typescript": "5.9.3",

package/src/atomic-fs.ts

@@ -86,10 +86,28 @@ export async function fsyncFile(file: string): Promise<void> {
 	}
 }
 
+/** 不支持目录 fsync 的平台/文件系统（Windows/NTFS、网络盘、exFAT、FUSE 等）返回的 errno。 */
+const TOLERATED_DIR_FSYNC_CODES = new Set(["EPERM", "EINVAL", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
+
+/** 目录 fsync 失败是否因平台/文件系统不支持而可以安全降级跳过。 */
+export function isToleratedDirFsyncError(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error &&
+		typeof (error as { code?: unknown }).code === "string" &&
+		TOLERATED_DIR_FSYNC_CODES.has((error as { code: string }).code);
+}
+
 export async function fsyncDirectory(directory: string): Promise<void> {
+	if (process.platform === "win32") {
+		// Windows 对目录句柄调用 fsync 必然返回 EPERM；rename 的持久性由文件系统自身保证。
+		return;
+	}
 	const handle = await open(directory, "r");
 	try {
 		await handle.sync();
+	} catch (error) {
+		// 目录 fsync 只是崩溃持久性的 best-effort 强化，文件内容的 fsync 不受影响：
+		// 不支持目录 fsync 的文件系统降级跳过，其余错误照常传播。
+		if (!isToleratedDirFsyncError(error)) throw error;
 	} finally {
 		await handle.close();
 	}

package/src/controller.ts

@@ -145,6 +145,12 @@ export interface UndoController {
 	cancelTree?(): Promise<void>;
 	recover(): Promise<void>;
 	history(): HistoryState;
+	/** 后台预热快照缓存：立即返回，失败静默；后续 capture 会先等预热完成。 */
+	warmUp(): void;
+	/** 最近一次输入前快照是否失败（此时本次 run 不可 undo，但输入不受影响）。 */
+	captureFailed(): boolean;
+	/** 最近一次输入前快照失败的原因（截断后的错误消息）；成功时为 undefined。 */
+	captureFailureReason(): string | undefined;
 }
 
 interface StagedRun {
@@ -192,6 +198,9 @@ export class UndoControllerImpl implements UndoController {
 	private operationProfiler: OperationProfiler | undefined;
 	private promptDeferralInFlight = false;
 	private lastSafetyManifestId: ManifestId | null = null;
+	private lastCaptureFailed = false;
+	private lastCaptureFailureMessage: string | undefined;
+	private warmUpInFlight: Promise<void> | undefined;
 
 	constructor(dependencies: ControllerDependencies, initialState: ControllerInitialState = {}) {
 		this.dependencies = dependencies;
@@ -205,22 +214,46 @@ export class UndoControllerImpl implements UndoController {
 		return { undoCount: this.undoStack.length, redoCount: this.redoStack.length, locked: this.locked };
 	}
 
+	captureFailed(): boolean {
+		return this.lastCaptureFailed;
+	}
+
+	warmUp(): void {
+		if (this.locked || this.warmUpInFlight !== undefined) return;
+		this.warmUpInFlight = (async () => {
+			try {
+				await this.captureWithWorkspaceLock();
+			} catch {
+				// 预热是 best-effort：失败静默，正式 capture 会再次尝试并上报。
+			}
+		})();
+	}
+
+	captureFailureReason(): string | undefined {
+		return this.lastCaptureFailed ? this.lastCaptureFailureMessage : undefined;
+	}
+
 	listCheckpoints(): readonly CheckpointRecord[] {
 		return [...this.undoStack];
 	}
 
 	async prepareInput(text: string, context: InputContext): Promise<InputEventResult> {
 		if (this.promptDeferralInFlight) return { action: "defer" };
-		if (this.locked || this.operationInFlight) return { action: "handled" };
+		if (this.locked) return { action: "continue" };
+		if (this.operationInFlight) return { action: "defer" };
 		if (context.streaming || text.length === 0) return { action: "continue" };
 		try {
 			const before = await this.captureWithWorkspaceLock();
+			this.lastCaptureFailed = false;
+			this.lastCaptureFailureMessage = undefined;
 			this.historyPaused = false;
 			this.staged = { rawPrompt: text, before, sourceLogicalLeaf: this.dependencies.getLogicalLeafId() };
 			return { action: "continue" };
-		} catch {
-			// 无法证明输入前状态时保留编辑器输入；本轮尚未开始，可由用户直接重试。
-			return { action: "handled" };
+		} catch (error) {
+			// 无法证明输入前状态：放弃记录本次历史，但绝不吞掉用户输入。
+			this.lastCaptureFailed = true;
+			this.lastCaptureFailureMessage = truncateReason(error instanceof Error ? error.message : String(error));
+			return { action: "continue" };
 		}
 	}
 
@@ -658,6 +691,10 @@ export class UndoControllerImpl implements UndoController {
 	}
 
 	private async captureWithWorkspaceLock(): Promise<SnapshotManifest> {
+		// 预热可能仍持有 workspace lock：先等它完成再 acquire，避免排队超时；
+		// 此时进程内缓存已暖，本次 capture 只需指纹校验。
+		const warmUp = this.warmUpInFlight;
+		if (warmUp !== undefined) await warmUp;
 		const lease = await this.dependencies.acquireWorkspaceLock();
 		try {
 			return await this.dependencies.capture();
@@ -844,3 +881,7 @@ class OperationProfiler {
 function noop(): OperationResult {
 	return { code: "noop", changedFiles: 0 };
 }
+
+function truncateReason(reason: string): string {
+	return reason.replace(/[\u0000-\u001F\u007F]+/g, " ").trim().slice(0, 120);
+}

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/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/restore-engine.ts

@@ -1661,7 +1661,10 @@ function assertCompatibleManifests(
 		throw new Error("restore manifest 不属于同一 workspace");
 	}
 	if (current.roots.some((root) => root.state === "broken") || target.roots.some((root) => root.state === "broken")) {
-		throw new Error("broken root 不能用于 restore");
+		const brokenRoots = [...current.roots, ...target.roots]
+			.filter((root, index, all) => root.state === "broken" && all.findIndex((candidate) => candidate.relativeRoot === root.relativeRoot) === index)
+			.map((root) => root.relativeRoot);
+		throw new Error(`broken root 不能用于 restore: ${brokenRoots.join(", ")}`);
 	}
 	const scopedCoverage = scope === undefined
 		? undefined

package/src/root-discovery.ts

@@ -333,10 +333,35 @@ async function isSafeDirectory(directory: string, workspaceIdentity: string): Pr
 async function gitlinkState(absolutePath: string): Promise<DiscoveryRoot["state"]> {
 	try {
 		await lstat(absolutePath);
-		return "broken";
 	} catch {
 		return "uninitialized";
 	}
+	// git worktree / 部分 checkout 会为 gitlink 留下空目录骨架（可能含指向共享依赖的 symlink）；
+	// 内容寻址快照只跟踪文件，不含任何文件的目录与未初始化等价，避免整个 workspace 无法快照。
+	return (await directoryTreeContainsFile(absolutePath)) ? "broken" : "uninitialized";
+}
+
+const SKELETON_NOISE_FILES = new Set([".DS_Store", "desktop.ini", "Thumbs.db"]);
+
+async function directoryTreeContainsFile(directory: string): Promise<boolean> {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return true;
+	}
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			if (await directoryTreeContainsFile(join(directory, entry.name))) return true;
+		} else if (entry.isSymbolicLink() || SKELETON_NOISE_FILES.has(entry.name)) {
+			// symlink 不适随也不计内容：uninitialized 根下的内容不被捕获也不会被 restore 触碰，
+			// 原样保留不会丢失；OS 噪音文件不应让整个 workspace 无法快照。
+			continue;
+		} else {
+			return true;
+		}
+	}
+	return false;
 }
 
 function cleanGitEnvironment(): Readonly<Record<string, string | undefined>> {

package/src/snapshot-store.ts

@@ -38,7 +38,9 @@ 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;
@@ -250,38 +252,50 @@ export class SnapshotStore {
 			const coverage = captureCoverage(topology.workspaceIdentity, scope);
 			const artifactExclusions = captureExclusions(topology.workspaceIdentity, options.excludePaths);
 			await this.assertTopology(topology, "捕获前 topology 已变化");
-			if (topology.roots.some((root) => root.state === "broken")) {
-				throw new SnapshotStoreError("capture_failed", "broken root 不能静默进入快照");
+			const brokenRoots = brokenRootPaths(topology);
+			if (brokenRoots.length > 0) {
+				throw new SnapshotStoreError("capture_failed", `broken root 不能静默进入快照: ${brokenRoots.join(", ")}`);
 			}
 
 			const storeDirectory = this.storeDirectory(topology);
 			const transactionsRoot = join(storeDirectory, "transactions");
 			await mkdir(transactionsRoot, { recursive: true });
 			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);
-					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));
-				cacheUpdates.push(captured.cacheUpdate);
-			}
+			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 = {
@@ -334,8 +348,9 @@ export class SnapshotStore {
 			}
 			const artifactExclusions = captureExclusions(topology.workspaceIdentity, options.excludePaths);
 			await this.assertTopology(topology, "可见路径枚举前 topology 已变化");
-			if (topology.roots.some((root) => root.state === "broken")) {
-				throw new SnapshotStoreError("capture_failed", "broken root 不能静默进入可见路径枚举");
+			const brokenRoots = brokenRootPaths(topology);
+			if (brokenRoots.length > 0) {
+				throw new SnapshotStoreError("capture_failed", `broken root 不能静默进入可见路径枚举: ${brokenRoots.join(", ")}`);
 			}
 
 			const storeDirectory = this.storeDirectory(topology);
@@ -720,6 +735,7 @@ export class SnapshotStore {
 			inclusions,
 			exclusions,
 			exactExclusions,
+			transactionDirectory,
 		);
 		const treeId = (await this.runGit(["write-tree"], { cwd: absoluteRoot, env: environment })).trim();
 		if (!isObjectId(treeId)) {
@@ -743,6 +759,7 @@ export class SnapshotStore {
 		inclusions: readonly string[] | null,
 		exclusions: readonly string[],
 		exactExclusions: ReadonlySet<string>,
+		requestDirectory: string,
 	): Promise<string[]> {
 		if (inclusions === null) {
 			return [];
@@ -761,7 +778,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)) ||
@@ -769,23 +787,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;
+	}
+
+	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].sort(comparePaths);
+		return result;
 	}
 
 	private async stageWorktree(
@@ -1505,6 +1574,10 @@ function ignoredPresentProof(coverage: string, ignoredPresentPaths: readonly str
 	};
 }
 
+function brokenRootPaths(topology: Pick<RootTopology, "roots">): string[] {
+	return topology.roots.filter((root) => root.state === "broken").map((root) => root.relativeRoot);
+}
+
 function inactiveRootClosure(root: Pick<RootTopologyIdentity, "relativeRoot" | "state">): string {
 	return checksum(canonicalJson({
 		relativeRoot: root.relativeRoot,
@@ -1812,11 +1885,16 @@ function parseTreeEntries(output: Uint8Array): CapturedTreeEntry[] {
 }
 
 function parseNulPaths(output: Uint8Array): string[] {
-	return splitNulRecords(output).map((record) => {
+	const paths: string[] = [];
+	for (const record of splitNulRecords(output)) {
 		const path = decodeUtf8(record);
+		// git 在嵌套仓库边界会输出折叠的目录项（如 "dir/"）；该目录由 root discovery
+		// 作为独立 root 捕获，不属于本仓库的路径枚举，直接跳过。
+		if (path.endsWith("/")) continue;
 		relativeSafePath("/", path);
-		return path;
-	});
+		paths.push(path);
+	}
+	return paths;
 }
 
 function splitNulRecords(output: Uint8Array): Uint8Array[] {