@alpsckr/unitycli 0.4.3 → 0.4.5

package/dist/extensions/installer.d.ts

@@ -32,6 +32,7 @@ export interface ExtensionStatusCheck {
     extensionId: ExtensionId;
     name: string;
     status: ExtensionInstallStatus;
+    integrity: "shallow" | "target" | "full";
     dependencyInstalled: boolean;
     installed: boolean;
     outdated: boolean;
@@ -42,10 +43,25 @@ export interface ExtensionStatusCheck {
     missingPackageIds: string[];
     nextActions: string[];
 }
+/** 一次公开调用冻结的 package/install 输入，后续检查不得重新读取。 */
+export interface ExtensionStateSnapshot {
+    projectPath: string;
+    installedPackages: ReadonlyMap<string, string>;
+    installManifest: ExtensionInstallManifest;
+}
+export interface ExtensionCheckOptions {
+    snapshot?: ExtensionStateSnapshot;
+    absoluteDeadlineMs?: number;
+}
+export type ExtensionFilesystemOperation = "snapshot" | "target-proof" | "managed-file-hash" | "source-proof" | "source-file-hash" | "source-tree-entry" | "unknown-tree-entry";
 /** 仅测试使用：在 source projection 复制后强制制造交错。 */
 export declare function setAfterProjectionCopyForTest(hook: (() => Promise<void>) | undefined): void;
 /** 仅测试使用：把可变 source 夹具隔离到临时目录。 */
 export declare function setExtensionSourceRootForTest(resolver: ((extensionId: ExtensionId) => string) | undefined): void;
+/** 仅测试使用：计数 discovery 的语义文件系统操作，不暴露到公开结果。 */
+export declare function setExtensionFilesystemOperationObserverForTest(observer: ((operation: ExtensionFilesystemOperation, extensionId?: ExtensionId) => void) | undefined): void;
+/** 仅测试使用：以确定时钟证明大目录扫描在deadline内中止。 */
+export declare function setExtensionFilesystemClockForTest(clock: (() => number) | undefined): void;
 /** 返回 extension 源码目录。 */
 export declare function extensionSourceRoot(extensionId: ExtensionId): string;
 /** 返回 extension Unity 安装投影使用的默认相对路径。 */
@@ -65,13 +81,49 @@ export declare function resolveInstallAvailability(manifest: ExtensionManifest,
 export declare function installExtensionBundleUnchecked(projectPath: string, manifest: ExtensionManifest, installedStatus?: "installed" | "already_installed"): Promise<ExtensionInstallResult>;
 /** 按 manifest 删除一个 extension 目录复制过的文件。 */
 export declare function removeExtensionBundle(projectPath: string, extensionId: ExtensionId): Promise<ExtensionInstallResult>;
-/** 检查所有 extension 的物理安装状态。 */
-export declare function checkExtensionBundles(projectPath: string): Promise<ExtensionStatusCheck[]>;
+/** package lock 与安装 manifest 每次 invocation 只读取一次。 */
+export declare function readExtensionStateSnapshot(projectPath: string): Promise<ExtensionStateSnapshot>;
+/** list 使用 manifest/version/root 的浅状态，不做 source 或 managed-file hash。 */
+export declare function listExtensionBundles(projectPath: string, snapshot?: ExtensionStateSnapshot): Promise<ExtensionStatusCheck[]>;
+/** 普通 discovery/执行只证明一个 selected extension 的 target 投影，不读取 source tree。 */
+export declare function checkSelectedExtensionBundle(projectPath: string, extensionId: ExtensionId, options?: ExtensionCheckOptions): Promise<ExtensionStatusCheck | undefined>;
+/** extensions doctor 独占全 extension source/managed-file 深 hash。 */
+export declare function checkExtensionBundles(projectPath: string, options?: ExtensionCheckOptions): Promise<ExtensionStatusCheck[]>;
+export interface ExtensionProjectionRepairEntry {
+    extensionId: ExtensionId;
+    fileCount: number;
+    sourceHash?: string;
+}
+export interface ExtensionProjectionRepairFailure {
+    extensionId: ExtensionId;
+    code: string;
+    message: string;
+    nextActions: string[];
+}
+export interface ExtensionProjectionRepairResult {
+    repaired: ExtensionProjectionRepairEntry[];
+    upToDate: ExtensionId[];
+    failures: ExtensionProjectionRepairFailure[];
+}
+/**
+ * init 包发布后的扩展升级自愈：把已装扩展投影对齐到当前 CLI 内置 bundle。
+ * Unity 增量编译只看源文件变化，包升级后若不重铺投影，扩展程序集不会重编译，
+ * 新协议要求的精确 UnityCliExtensionAssembly 标记就不会出现，bridge 启动校验会失败。
+ * 逐项收集失败结果并原样透出，任何单项失败都不中断 init 包发布。
+ */
+export declare function refreshInstalledExtensionProjections(projectPath: string, absoluteDeadlineMs?: number): Promise<ExtensionProjectionRepairResult>;
+export interface CompiledExtensionMarkerCheck {
+    extensionId: ExtensionId;
+    assemblyName: string;
+    compiledAssemblyFound: boolean;
+    markerPresent?: boolean;
+}
 /**
- * 返回目标项目的唯一 extension physical install state 视图。
- * 控制面和 live capability gate 均必须使用此入口，不能用 package dependency 替代安装状态。
+ * 只读检查扩展编译产物是否包含当前协议要求的精确扩展标记。
+ * 投影重铺后 Unity 可能尚未重编译；此时 Library/ScriptAssemblies 的旧 dll 不含标记，
+ * bridge 启动校验仍会失败，doctor 必须把这种状态显式暴露为 warn 而不是 pass。
  */
-export declare function readExtensionPhysicalStates(projectPath: string): Promise<Map<ExtensionId, ExtensionStatusCheck>>;
+export declare function inspectCompiledExtensionMarkers(projectPath: string, extensionIds: readonly ExtensionId[], absoluteDeadlineMs?: number): Promise<CompiledExtensionMarkerCheck[]>;
 export declare class ExtensionInstallerError extends Error {
     readonly code: string;
     readonly nextActions: string[];

package/dist/extensions/installer.js

@@ -5,6 +5,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readInstalledUnityPackages } from "./project-resolver.js";
 import { ExtensionRegistry, resolveExtensionAvailability } from "./registry.js";
+import { EXTENSION_STATE_MAX_ENTRIES, ExtensionStateContractError, isValidExtensionId, readBoundedExtensionStateFile, } from "./state-contract.js";
 import { stripBom } from "../util.js";
 const packageName = "com.alpsckr.unitycli";
 const manifestFileName = "unitycli.extensions.manifest.json";
@@ -12,6 +13,8 @@ const manifestLockTimeoutMs = 15_000;
 const processStartIdentity = new Date(Date.now() - Math.floor(process.uptime() * 1_000)).toISOString();
 let afterProjectionCopyForTest;
 let sourceRootForTest;
+let filesystemOperationObserverForTest;
+let extensionFilesystemNow = Date.now;
 /** 仅测试使用：在 source projection 复制后强制制造交错。 */
 export function setAfterProjectionCopyForTest(hook) {
     afterProjectionCopyForTest = hook;
@@ -20,6 +23,14 @@ export function setAfterProjectionCopyForTest(hook) {
 export function setExtensionSourceRootForTest(resolver) {
     sourceRootForTest = resolver;
 }
+/** 仅测试使用：计数 discovery 的语义文件系统操作，不暴露到公开结果。 */
+export function setExtensionFilesystemOperationObserverForTest(observer) {
+    filesystemOperationObserverForTest = observer;
+}
+/** 仅测试使用：以确定时钟证明大目录扫描在deadline内中止。 */
+export function setExtensionFilesystemClockForTest(clock) {
+    extensionFilesystemNow = clock ?? Date.now;
+}
 /** 返回 extension 源码目录。 */
 export function extensionSourceRoot(extensionId) {
     return resolve(fileURLToPath(new URL(`../../extensions/${extensionId}`, import.meta.url)));
@@ -38,20 +49,23 @@ export function extensionInstallManifestPath(projectPath) {
 }
 /** 读取 extension 安装 manifest；仅缺失文件代表空状态，损坏状态必须阻断变更。 */
 export async function readExtensionInstallManifest(projectPath) {
-    const path = extensionInstallManifestPath(projectPath);
     let content;
     try {
-        content = await readFile(path, "utf8");
+        content = await readBoundedExtensionStateFile(extensionInstallManifestPath(projectPath));
     }
     catch (error) {
-        if (error.code === "ENOENT")
-            return emptyManifest();
+        if (error instanceof ExtensionStateContractError)
+            throw invalidInstallManifest(projectPath, error.message);
         throw error;
     }
+    if (content === undefined)
+        return emptyManifest();
     try {
         const parsed = JSON.parse(stripBom(content));
-        if (parsed.version !== 1 || !Array.isArray(parsed.extensions) || !parsed.extensions.every(isInstalledEntry)) {
-            throw invalidInstallManifest(projectPath, "Expected version 1 and valid extension entries.");
+        if (parsed.version !== 1 || !Array.isArray(parsed.extensions)
+            || parsed.extensions.length > EXTENSION_STATE_MAX_ENTRIES
+            || !parsed.extensions.every(isInstalledEntry)) {
+            throw invalidInstallManifest(projectPath, `Expected version 1 and at most ${EXTENSION_STATE_MAX_ENTRIES} valid extension entries.`);
         }
         if (new Set(parsed.extensions.map((entry) => entry.extensionId)).size !== parsed.extensions.length) {
             throw invalidInstallManifest(projectPath, "Extension entries must have unique extensionId values.");
@@ -66,6 +80,11 @@ export async function readExtensionInstallManifest(projectPath) {
 }
 /** 原子写入 extension 安装 manifest，读取方不会观察到半写文件。 */
 export async function writeExtensionInstallManifest(projectPath, manifest) {
+    if (manifest.extensions.length > EXTENSION_STATE_MAX_ENTRIES
+        || !manifest.extensions.every(isInstalledEntry)
+        || new Set(manifest.extensions.map((entry) => entry.extensionId)).size !== manifest.extensions.length) {
+        throw invalidInstallManifest(projectPath, `Expected at most ${EXTENSION_STATE_MAX_ENTRIES} unique valid extension entries.`);
+    }
     const manifestPath = extensionInstallManifestPath(projectPath);
     const temporaryPath = `${manifestPath}.${process.pid}.${randomUUID()}.tmp`;
     await mkdir(dirname(manifestPath), { recursive: true });
@@ -199,50 +218,217 @@ export async function removeExtensionBundle(projectPath, extensionId) {
         };
     });
 }
-/** 检查所有 extension 的物理安装状态。 */
-export async function checkExtensionBundles(projectPath) {
+/** package lock 与安装 manifest 每次 invocation 只读取一次。 */
+export async function readExtensionStateSnapshot(projectPath) {
+    filesystemOperationObserverForTest?.("snapshot");
+    const canonicalProjectPath = resolve(projectPath);
+    const [installedPackages, installManifest] = await Promise.all([
+        readInstalledUnityPackages(canonicalProjectPath),
+        readExtensionInstallManifest(canonicalProjectPath),
+    ]);
+    return { projectPath: canonicalProjectPath, installedPackages, installManifest };
+}
+/** list 使用 manifest/version/root 的浅状态，不做 source 或 managed-file hash。 */
+export async function listExtensionBundles(projectPath, snapshot) {
+    const frozen = snapshot ?? await readExtensionStateSnapshot(projectPath);
     const registry = new ExtensionRegistry();
-    const installedPackages = await readInstalledUnityPackages(projectPath);
-    const installManifest = await readExtensionInstallManifest(projectPath);
+    return registry.extensionIds().map((extensionId) => {
+        const extension = registry.getExtension(extensionId);
+        const availability = resolveInstallAvailability(extension.manifest, frozen.installedPackages);
+        const entry = frozen.installManifest.extensions.find((item) => item.extensionId === extensionId);
+        const targetPresent = existsSync(extensionInstallRoot(frozen.projectPath, extensionId));
+        const outdated = Boolean(entry && (entry.version !== extension.manifest.version || !targetPresent));
+        const status = resolvePhysicalStatus(availability, entry !== undefined, outdated, [], [], []);
+        return extensionStatus(extension.manifest, availability, status, "shallow", Boolean(entry && targetPresent && !outdated), outdated, {
+            missingFiles: [], changedFiles: [], unknownFiles: [],
+        });
+    });
+}
+/** 普通 discovery/执行只证明一个 selected extension 的 target 投影，不读取 source tree。 */
+export async function checkSelectedExtensionBundle(projectPath, extensionId, options = {}) {
+    const registry = new ExtensionRegistry();
+    const extension = registry.getExtension(extensionId);
+    if (!extension)
+        return undefined;
+    const snapshot = options.snapshot ?? await readExtensionStateSnapshot(projectPath);
+    const availability = resolveInstallAvailability(extension.manifest, snapshot.installedPackages);
+    const entry = snapshot.installManifest.extensions.find((item) => item.extensionId === extensionId);
+    const targetRoot = extensionInstallRoot(snapshot.projectPath, extensionId);
+    filesystemOperationObserverForTest?.("target-proof", extensionId);
+    const fileCheck = entry
+        ? await checkManagedFiles(targetRoot, entry.files, options.absoluteDeadlineMs, extensionId)
+        : { missingFiles: [], changedFiles: [], unknownFiles: [] };
+    const outdated = Boolean(entry && entry.version !== extension.manifest.version);
+    const installed = Boolean(entry && !outdated && fileCheck.missingFiles.length === 0 && fileCheck.changedFiles.length === 0 && fileCheck.unknownFiles.length === 0);
+    const status = resolvePhysicalStatus(availability, entry !== undefined, outdated, fileCheck.missingFiles, fileCheck.changedFiles, fileCheck.unknownFiles);
+    return extensionStatus(extension.manifest, availability, status, "target", installed, outdated, fileCheck);
+}
+/** extensions doctor 独占全 extension source/managed-file 深 hash。 */
+export async function checkExtensionBundles(projectPath, options = {}) {
+    const registry = new ExtensionRegistry();
+    const snapshot = options.snapshot ?? await readExtensionStateSnapshot(projectPath);
     const checks = [];
     for (const extensionId of registry.extensionIds()) {
+        requireExtensionScanDeadline(options.absoluteDeadlineMs);
         const extension = registry.getExtension(extensionId);
-        const bundleAvailability = resolveInstallAvailability(extension.manifest, installedPackages);
-        const entry = installManifest.extensions.find((item) => item.extensionId === extensionId);
-        const targetRoot = extensionInstallRoot(projectPath, extensionId);
+        const availability = resolveInstallAvailability(extension.manifest, snapshot.installedPackages);
+        const entry = snapshot.installManifest.extensions.find((item) => item.extensionId === extensionId);
+        const targetRoot = extensionInstallRoot(snapshot.projectPath, extensionId);
         const sourceRoot = extensionSourceRoot(extensionId);
         const includes = extensionUnityInstallIncludes(extension.manifest);
         const sourceProjectionComplete = existsSync(sourceRoot) && includes.every((include) => existsSync(safeSourcePath(sourceRoot, include)));
-        const sourceHash = sourceProjectionComplete ? await hashBundleProjection(sourceRoot, includes) : undefined;
-        const fileCheck = entry ? await checkManagedFiles(targetRoot, entry.files) : { missingFiles: [], changedFiles: [], unknownFiles: await listUnknownFiles(targetRoot, []) };
-        // version、投影源码 hash 和 include 文件均属于 physical install contract。
+        filesystemOperationObserverForTest?.("source-proof", extensionId);
+        const sourceHash = sourceProjectionComplete ? await hashBundleProjection(sourceRoot, includes, options.absoluteDeadlineMs, extensionId) : undefined;
+        filesystemOperationObserverForTest?.("target-proof", extensionId);
+        const fileCheck = entry
+            ? await checkManagedFiles(targetRoot, entry.files, options.absoluteDeadlineMs, extensionId)
+            : { missingFiles: [], changedFiles: [], unknownFiles: await listUnknownFiles(targetRoot, [], options.absoluteDeadlineMs, extensionId) };
         const outdated = Boolean(entry && (!sourceProjectionComplete || !sourceHash || entry.sourceHash !== sourceHash || entry.version !== extension.manifest.version));
-        const hasUnknownFiles = fileCheck.unknownFiles.length > 0;
-        const installed = Boolean(entry && fileCheck.missingFiles.length === 0 && fileCheck.changedFiles.length === 0 && !outdated && !hasUnknownFiles);
-        const status = resolvePhysicalStatus(bundleAvailability, entry !== undefined, outdated, fileCheck.missingFiles, fileCheck.changedFiles, fileCheck.unknownFiles);
-        checks.push({
-            extensionId,
-            name: extension.manifest.name,
-            status,
-            dependencyInstalled: bundleAvailability.status === "available",
-            installed,
-            outdated,
-            unknownFiles: fileCheck.unknownFiles,
-            missingFiles: fileCheck.missingFiles,
-            changedFiles: fileCheck.changedFiles,
-            providedTools: extension.manifest.contributions.tools?.map((tool) => tool.name) ?? [],
-            missingPackageIds: bundleAvailability.missingPackageIds,
-            nextActions: nextActionsForStatus(extension.manifest, bundleAvailability, status)
-        });
+        const installed = Boolean(entry && fileCheck.missingFiles.length === 0 && fileCheck.changedFiles.length === 0 && !outdated && fileCheck.unknownFiles.length === 0);
+        const status = resolvePhysicalStatus(availability, entry !== undefined, outdated, fileCheck.missingFiles, fileCheck.changedFiles, fileCheck.unknownFiles);
+        checks.push(extensionStatus(extension.manifest, availability, status, "full", installed, outdated, fileCheck));
     }
     return checks;
 }
 /**
- * 返回目标项目的唯一 extension physical install state 视图。
- * 控制面和 live capability gate 均必须使用此入口，不能用 package dependency 替代安装状态。
+ * init 包发布后的扩展升级自愈：把已装扩展投影对齐到当前 CLI 内置 bundle。
+ * Unity 增量编译只看源文件变化，包升级后若不重铺投影，扩展程序集不会重编译，
+ * 新协议要求的精确 UnityCliExtensionAssembly 标记就不会出现，bridge 启动校验会失败。
+ * 逐项收集失败结果并原样透出，任何单项失败都不中断 init 包发布。
+ */
+export async function refreshInstalledExtensionProjections(projectPath, absoluteDeadlineMs) {
+    const result = { repaired: [], upToDate: [], failures: [] };
+    const registry = new ExtensionRegistry();
+    let installed;
+    try {
+        installed = (await readExtensionInstallManifest(projectPath)).extensions;
+    }
+    catch (error) {
+        result.failures.push({
+            extensionId: "unknown",
+            code: "E_EXTENSION_REPAIR_FAILED",
+            message: `Installed extension manifest could not be read, so installed extension projections were not refreshed: ${error instanceof Error ? error.message : String(error)}`,
+            nextActions: [`Run \`unitycli extensions status --project "${projectPath}"\` to inspect the broken extension install manifest.`],
+        });
+        return result;
+    }
+    for (const entry of installed) {
+        if (absoluteDeadlineMs !== undefined && Date.now() >= absoluteDeadlineMs) {
+            result.failures.push({
+                extensionId: entry.extensionId,
+                code: "E_EXTENSION_REPAIR_DEADLINE",
+                message: `The immutable init deadline elapsed before the ${entry.extensionId} extension projection could be refreshed.`,
+                nextActions: ["Rerun `unitycli init package --project <UnityProject>` to finish refreshing extension projections."],
+            });
+            continue;
+        }
+        const extension = registry.getExtension(entry.extensionId);
+        if (!extension) {
+            result.failures.push({
+                extensionId: entry.extensionId,
+                code: "E_EXTENSION_UNKNOWN_INSTALLED",
+                message: `Installed extension ${entry.extensionId} is not provided by this CLI build, so its projection cannot be refreshed automatically.`,
+                nextActions: [`Run \`unitycli extensions remove ${entry.extensionId} --project "${projectPath}"\` if the extension is no longer needed.`],
+            });
+            continue;
+        }
+        const sourceRoot = extensionSourceRoot(entry.extensionId);
+        const includes = extensionUnityInstallIncludes(extension.manifest);
+        if (!existsSync(sourceRoot) || !includes.every((include) => existsSync(safeSourcePath(sourceRoot, include)))) {
+            result.failures.push({
+                extensionId: entry.extensionId,
+                code: "E_EXTENSION_BUNDLE_MISSING",
+                message: `The ${entry.extensionId} extension bundle shipped with this CLI build is incomplete, so its installed projection was left unchanged.`,
+                nextActions: ["Reinstall the @alpsckr/unitycli package, then run `unitycli init package` again."],
+            });
+            continue;
+        }
+        const currentHash = await hashBundleProjection(sourceRoot, includes);
+        if (entry.sourceHash === currentHash && entry.version === extension.manifest.version) {
+            result.upToDate.push(entry.extensionId);
+            continue;
+        }
+        try {
+            const repair = await installExtensionBundleUnchecked(projectPath, extension.manifest, "installed");
+            result.repaired.push({ extensionId: entry.extensionId, fileCount: repair.fileCount, sourceHash: repair.sourceHash });
+        }
+        catch (error) {
+            result.failures.push({
+                extensionId: entry.extensionId,
+                code: error instanceof ExtensionInstallerError ? error.code : "E_EXTENSION_REPAIR_FAILED",
+                message: `Extension projection refresh failed for ${entry.extensionId}: ${error instanceof Error ? error.message : String(error)}`,
+                nextActions: error instanceof ExtensionInstallerError && error.nextActions.length > 0
+                    ? error.nextActions
+                    : [`Reinstall manually: \`unitycli extensions remove ${entry.extensionId}\` followed by \`unitycli extensions install ${entry.extensionId} --project "${projectPath}"\`.`],
+            });
+        }
+    }
+    return result;
+}
+const compiledMarkerNeedle = Buffer.from("UnityCliExtensionAssembly", "utf8");
+const maxCompiledAssemblyReadBytes = 32 * 1024 * 1024;
+/**
+ * 只读检查扩展编译产物是否包含当前协议要求的精确扩展标记。
+ * 投影重铺后 Unity 可能尚未重编译；此时 Library/ScriptAssemblies 的旧 dll 不含标记，
+ * bridge 启动校验仍会失败，doctor 必须把这种状态显式暴露为 warn 而不是 pass。
  */
-export async function readExtensionPhysicalStates(projectPath) {
-    return new Map((await checkExtensionBundles(projectPath)).map((check) => [check.extensionId, check]));
+export async function inspectCompiledExtensionMarkers(projectPath, extensionIds, absoluteDeadlineMs) {
+    const checks = [];
+    for (const extensionId of extensionIds) {
+        if (absoluteDeadlineMs !== undefined && Date.now() >= absoluteDeadlineMs)
+            break;
+        // 投影根目录即 Unity 包根，asmdef 与 Editor/ 都在 Extensions/<id>/ 顶层。
+        const unityPackageRoot = extensionInstallRoot(projectPath, extensionId);
+        let assemblyName;
+        try {
+            const entries = await readdir(unityPackageRoot);
+            const asmdefFile = entries.find((name) => name.endsWith(".asmdef"));
+            if (!asmdefFile)
+                continue;
+            const parsed = JSON.parse(stripBom(await readFile(join(unityPackageRoot, asmdefFile), "utf8")));
+            if (typeof parsed.name !== "string" || parsed.name.length === 0)
+                continue;
+            assemblyName = parsed.name;
+        }
+        catch {
+            continue; // 投影缺失或不可读时无从检查编译产物
+        }
+        const assemblyPath = join(projectPath, "Library", "ScriptAssemblies", `${assemblyName}.dll`);
+        try {
+            const info = await stat(assemblyPath);
+            if (!info.isFile() || info.size > maxCompiledAssemblyReadBytes) {
+                checks.push({ extensionId, assemblyName, compiledAssemblyFound: false });
+                continue;
+            }
+            const bytes = await readFile(assemblyPath);
+            checks.push({ extensionId, assemblyName, compiledAssemblyFound: true, markerPresent: bytes.includes(compiledMarkerNeedle) });
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                checks.push({ extensionId, assemblyName, compiledAssemblyFound: false });
+                continue;
+            }
+            throw error;
+        }
+    }
+    return checks;
+}
+function extensionStatus(manifest, availability, status, integrity, installed, outdated, files) {
+    return {
+        extensionId: manifest.id,
+        name: manifest.name,
+        status,
+        integrity,
+        dependencyInstalled: availability.status === "available",
+        installed,
+        outdated,
+        unknownFiles: files.unknownFiles,
+        missingFiles: files.missingFiles,
+        changedFiles: files.changedFiles,
+        providedTools: manifest.contributions.tools?.map((tool) => tool.name) ?? [],
+        missingPackageIds: availability.missingPackageIds,
+        nextActions: nextActionsForStatus(manifest, availability, status),
+    };
 }
 /** 跨进程序列化同一项目的 extension 文件与 manifest 变更；活 owner 与损坏锁一律不按时间抢占。 */
 async function withExtensionManifestLock(projectPath, action) {
@@ -386,46 +572,48 @@ async function removeManagedFiles(targetRoot, files) {
         await rm(safeManagedPath(targetRoot, file.path), { force: true });
     }
 }
-async function checkManagedFiles(targetRoot, files) {
+async function checkManagedFiles(targetRoot, files, absoluteDeadlineMs, extensionId) {
     const missingFiles = [];
     const changedFiles = [];
     const managed = new Set(files.map((file) => file.path));
     for (const file of files) {
+        requireExtensionScanDeadline(absoluteDeadlineMs);
         const fullPath = safeManagedPath(targetRoot, file.path);
         if (!existsSync(fullPath)) {
             missingFiles.push(file.path);
             continue;
         }
-        const actualHash = await hashFile(fullPath);
-        if (actualHash !== file.sha256) {
+        filesystemOperationObserverForTest?.("managed-file-hash", extensionId);
+        const actualHash = await hashFile(fullPath, absoluteDeadlineMs);
+        if (actualHash !== file.sha256)
             changedFiles.push(file.path);
-        }
     }
-    const unknownFiles = await listUnknownFiles(targetRoot, managed);
+    const unknownFiles = await listUnknownFiles(targetRoot, managed, absoluteDeadlineMs, extensionId);
     return { missingFiles, changedFiles, unknownFiles };
 }
-async function listUnknownFiles(targetRoot, managed) {
-    if (!existsSync(targetRoot)) {
+async function listUnknownFiles(targetRoot, managed, absoluteDeadlineMs, extensionId) {
+    requireExtensionScanDeadline(absoluteDeadlineMs);
+    if (!existsSync(targetRoot))
         return [];
-    }
     const managedSet = new Set(managed);
-    const allFiles = await listFiles(targetRoot);
+    const allFiles = await listFiles(targetRoot, targetRoot, absoluteDeadlineMs, extensionId);
     return allFiles.filter((file) => !managedSet.has(file) && !isUnityGeneratedMetaFile(file)).sort();
 }
 function isUnityGeneratedMetaFile(path) {
     return path.endsWith(".meta");
 }
-async function listFiles(root, current = root) {
+async function listFiles(root, current = root, absoluteDeadlineMs, extensionId) {
+    requireExtensionScanDeadline(absoluteDeadlineMs);
     const entries = await readdir(current, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
+        requireExtensionScanDeadline(absoluteDeadlineMs);
+        filesystemOperationObserverForTest?.("unknown-tree-entry", extensionId);
         const fullPath = join(current, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...await listFiles(root, fullPath));
-        }
-        else if (entry.isFile()) {
+        if (entry.isDirectory())
+            files.push(...await listFiles(root, fullPath, absoluteDeadlineMs, extensionId));
+        else if (entry.isFile())
             files.push(normalizePath(relative(root, fullPath)));
-        }
     }
     return files;
 }
@@ -452,43 +640,54 @@ async function hashManagedProjection(root, files) {
     }
     return hash.digest("hex");
 }
-async function hashBundleProjection(sourceRoot, includes) {
+async function hashBundleProjection(sourceRoot, includes, absoluteDeadlineMs, extensionId) {
     const files = [];
     for (const includePath of includes.map(normalizePath).sort()) {
+        requireExtensionScanDeadline(absoluteDeadlineMs);
         const sourcePath = safeSourcePath(sourceRoot, includePath);
         if (!existsSync(sourcePath))
             continue;
         const targetRelativeRoot = projectionTargetRoot(includePath);
-        if ((await stat(sourcePath)).isDirectory()) {
-            await collectProjectionFiles(sourcePath, sourcePath, targetRelativeRoot, files);
-        }
-        else {
+        if ((await stat(sourcePath)).isDirectory())
+            await collectProjectionFiles(sourcePath, sourcePath, targetRelativeRoot, files, absoluteDeadlineMs, extensionId);
+        else
             files.push({ path: targetRelativeRoot, sourcePath });
-        }
     }
     const hash = createHash("sha256");
     for (const file of files.sort((left, right) => left.path.localeCompare(right.path))) {
+        requireExtensionScanDeadline(absoluteDeadlineMs);
         hash.update(`file:${file.path}\n`);
+        filesystemOperationObserverForTest?.("source-file-hash", extensionId);
         hash.update(await readFile(file.sourcePath));
         hash.update("\n");
     }
     return hash.digest("hex");
 }
-async function collectProjectionFiles(dir, root, targetPrefix, files) {
+async function collectProjectionFiles(dir, root, targetPrefix, files, absoluteDeadlineMs, extensionId) {
+    requireExtensionScanDeadline(absoluteDeadlineMs);
     for (const entry of (await readdir(dir, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+        requireExtensionScanDeadline(absoluteDeadlineMs);
+        filesystemOperationObserverForTest?.("source-tree-entry", extensionId);
         const sourcePath = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            await collectProjectionFiles(sourcePath, root, targetPrefix, files);
-        }
+        if (entry.isDirectory())
+            await collectProjectionFiles(sourcePath, root, targetPrefix, files, absoluteDeadlineMs, extensionId);
         else if (entry.isFile()) {
             const relativePath = normalizePath(relative(root, sourcePath));
             files.push({ path: normalizePath(targetPrefix ? `${targetPrefix}/${relativePath}` : relativePath), sourcePath });
         }
     }
 }
-async function hashFile(path) {
+async function hashFile(path, absoluteDeadlineMs) {
+    requireExtensionScanDeadline(absoluteDeadlineMs);
     return createHash("sha256").update(await readFile(path)).digest("hex");
 }
+function requireExtensionScanDeadline(absoluteDeadlineMs) {
+    if (absoluteDeadlineMs !== undefined && extensionFilesystemNow() >= absoluteDeadlineMs) {
+        throw new ExtensionInstallerError("E_EXTENSION_SCAN_TIMEOUT", "Extension filesystem inspection exceeded the immutable command deadline.", [
+            "Remove unexpected files or retry extensions doctor with a larger --timeout-ms after filesystem activity settles."
+        ]);
+    }
+}
 function resolvePhysicalStatus(availability, hasEntry, outdated, missingFiles, changedFiles, unknownFiles) {
     if (availability.status !== "available")
         return "missing_dependency";
@@ -564,7 +763,7 @@ function invalidInstallManifest(projectPath, reason) {
 }
 function isInstalledEntry(value) {
     const entry = value;
-    return typeof entry?.extensionId === "string" && entry.extensionId.length > 0
+    return isValidExtensionId(entry?.extensionId)
         && typeof entry.version === "string" && entry.version.length > 0
         && typeof entry.installedAt === "string" && !Number.isNaN(Date.parse(entry.installedAt))
         && typeof entry.sourceHash === "string" && /^[a-f0-9]{64}$/i.test(entry.sourceHash)