@alpsckr/unitycli 0.4.2 → 0.4.4

package/dist/tools/dispatcher.js

@@ -7,103 +7,187 @@ import { PackageManagerError } from "../package-manager.js";
 import { instanceSelectionFailure, selectInstanceForFlags, selectObservationInstanceForFlags } from "../instances.js";
 import { EditorBlockerObserver, sanitizeEditorBlockers } from "../editor-blocker-observer.js";
 import { defaultDataDir } from "../platform.js";
+import { trackCliProcessOwner } from "../cli-process-owners.js";
 import { validateSchema } from "../schema/validator.js";
-import { checkToolExtensionAvailability, extensionAvailabilityFlags } from "../extension-availability.js";
-import { resolveCatalogIndependentInvocationTool, resolveCatalogTool } from "./catalog.js";
+import { checkToolExtensionAvailability, extensionIdForToolName, freezeExtensionAvailability } from "../extension-availability.js";
+import { ExtensionInstallerError } from "../extensions/installer.js";
+import { resolveCatalogIndependentInvocationTool, resolveCatalogIndependentOperabilityTool, resolveCatalogTool } from "./catalog.js";
 import { generatedToolCompletionContract } from "./.generated-completion-registry.js";
 import { findDefineTool } from "./define.js";
 import { StructuredToolError } from "./errors.js";
 import { EXTENSION_GROUPS, findToolByName, toolIsMutation } from "./metadata/index.js";
-const MULTI_TARGET_CATALOG_TOOLS = new Set(["tools.group", "tools.group-list", "tools.search", "tools.describe", "diagnose.capabilities"]);
+/** 生产使用唯一supervisor实现；隔离测试只能替换构造边界。 */
+function createSessionSupervisor(flags, runtime) {
+    return runtime.createSessionSupervisor?.(flags, runtime) ?? new SessionSupervisor(flags, runtime);
+}
+const MULTI_TARGET_CATALOG_TOOLS = new Set();
+/** command 与 tools run 在第一次 live discovery 前只创建一次顶层 admission deadline。 */
+export function beginToolInvocation(flags, requestId, timeoutMetadata, startedAtMs = Date.now()) {
+    const timeoutFailure = validateExecutionTimeoutFlags(flags, requestId);
+    if (timeoutFailure)
+        return { ok: false, result: timeoutFailure };
+    const timeoutMs = Math.max(1, executionFromFlags(flags).timeoutMs ?? timeoutMetadata?.timeoutMs ?? 30_000);
+    return { ok: true, context: { timeoutMs, admissionAbsoluteDeadlineMs: startedAtMs + timeoutMs } };
+}
 /**
  * Tool 分发顺序固定为输入解析、catalog 解析、schema 校验、目标选择、执行与 envelope。
  * 调用即授权，只保留 schema、目标与 descriptor 的正确性验证。
  */
-export async function dispatchTool(name, positionalTarget, flags, runtime, requestId, seed = {}, resolvedTool) {
+export async function dispatchTool(name, positionalTarget, flags, runtime, requestId, seed = {}, resolvedTool, invocationContext) {
     const dispatchStartedAtMs = Date.now();
     if (!name)
         return failure(requestId, "E_TOOL_NOT_FOUND_FOR_TARGET", "Tool name is required for tools run.", ["Run unitycli tools group to see tool groups.", "Run unitycli tools search <k1|k2|...> to find related tools."]);
-    const executionFlagError = validateExecutionTimeoutFlags(flags, requestId);
-    if (executionFlagError)
-        return executionFlagError;
-    const codeInputDeadlineMs = name === "code.exec"
-        ? dispatchStartedAtMs + (typeof flags["timeout-ms"] === "string" ? Number(flags["timeout-ms"]) : 60_000)
-        : undefined;
-    const parsed = await parseTypedInput(flags, requestId, name === "code.exec" ? 1024 * 1024 : undefined, codeInputDeadlineMs);
+    if (resolvedTool && resolvedTool.name !== name)
+        return failure(requestId, "E_TOOL_SCHEMA_CONFLICT", `Resolved Tool name ${resolvedTool.name} does not match requested name ${name}.`, [
+            "Refresh the selected Unity instance catalog and retry the same command."
+        ], { requestedName: name, resolvedName: resolvedTool.name });
+    const localMetadata = findToolByName(name);
+    const timeoutMetadata = resolvedTool ?? localMetadata;
+    const defaultTimeoutMs = name === "code.exec" ? 60_000 : 30_000;
+    const started = invocationContext
+        ? { ok: true, context: invocationContext }
+        : beginToolInvocation(flags, requestId, { timeoutMs: timeoutMetadata?.timeoutMs ?? defaultTimeoutMs }, dispatchStartedAtMs);
+    if (!started.ok)
+        return started.result;
+    const admissionTimeoutMs = started.context.timeoutMs;
+    const admissionAbsoluteDeadlineMs = started.context.admissionAbsoluteDeadlineMs;
+    const parsed = await parseTypedInput(flags, requestId, name === "code.exec" ? 1024 * 1024 : undefined, admissionAbsoluteDeadlineMs);
     if (!parsed.ok)
         return parsed.error;
     const dispatchFlags = withStructuredInput(flags, parsed.input);
+    const dispatchResolved = (tool, input) => dispatchResolvedTool(tool, input, dispatchFlags, runtime, requestId, admissionTimeoutMs, admissionAbsoluteDeadlineMs, started.context.discoveryProvenances);
     // command入口已从同一次live catalog读取schema；直接使用该descriptor，避免二次发现改变绑定。
     if (resolvedTool) {
-        if (resolvedTool.name !== name)
-            return failure(requestId, "E_TOOL_SCHEMA_CONFLICT", `Resolved Tool name ${resolvedTool.name} does not match requested name ${name}.`, [
-                "Refresh the selected Unity instance catalog and retry the same command."
-            ], { requestedName: name, resolvedName: resolvedTool.name });
         const input = requestFromInput(resolvedTool, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
-        return dispatchResolvedTool(resolvedTool, input, dispatchFlags, runtime, requestId, dispatchStartedAtMs);
+        return dispatchResolved(resolvedTool, input);
+    }
+    if (localMetadata?.handler === "offline") {
+        const input = requestFromInput(localMetadata, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
+        return dispatchResolved(localMetadata, input);
+    }
+    // 内置 hybrid Tool 的 dry-run 不需要 live descriptor，但仍保留统一 admission 与输出校验。
+    if (localMetadata?.handler === "hybrid" && getBoolean(dispatchFlags, "dry-run") && localMetadata.supportsDryRun) {
+        const input = requestFromInput(localMetadata, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
+        return dispatchResolved(localMetadata, input);
     }
-    const localMetadata = findToolByName(name);
     const localProperties = localMetadata?.inputSchema.properties;
     // TS-local schema 的 project 仅约束已选实例；不得把其他业务字段写入 selector/execution flags。
     const catalogFlags = localMetadata && localProperties && "project" in localProperties
         && typeof parsed.input.project === "string" && dispatchFlags.project === undefined
         ? { ...dispatchFlags, project: parsed.input.project }
         : dispatchFlags;
-    // exact 弹窗恢复及其 describe 学习入口不依赖被同一 modal 阻断的 Live catalog。
-    const catalogIndependentTool = resolveCatalogIndependentInvocationTool(name, typeof seed.name === "string" ? seed.name : undefined);
+    // exact 弹窗观察与恢复不依赖被同一 modal 阻断的 Live catalog。
+    const catalogIndependentTool = resolveCatalogIndependentInvocationTool(name);
     if (catalogIndependentTool) {
         const input = requestFromInput(catalogIndependentTool, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
-        return dispatchResolvedTool(catalogIndependentTool, input, dispatchFlags, runtime, requestId, dispatchStartedAtMs);
+        return dispatchResolved(catalogIndependentTool, input);
     }
     const coreSpec = bridgeCommandRegistry.specs().find((spec) => (spec.toolName === name || spec.bridgeCommand === name) && !EXTENSION_GROUPS.has(spec.group) && spec.internal !== true);
     // Runtime descriptor 的唯一 owner 在 TS catalog；执行直接进入共享 runtime wrapper，目标缺失时返回 runtime selector 错误。
     if (localMetadata?.handler === "bridge-runtime") {
         const input = requestFromInput(localMetadata, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
-        return dispatchResolvedTool(localMetadata, input, dispatchFlags, runtime, requestId, dispatchStartedAtMs);
+        return dispatchResolved(localMetadata, input);
     }
     // 无 catalog fixture 的注入式 bridgeExecute 仅用于隔离测试；其余路径必须 catalog-first。
-    if (runtime.bridgeExecute && runtime.projectTools === undefined && localMetadata) {
+    if (runtime.bridgeExecute && runtime.projectTools === undefined && !runtime.createSessionSupervisor && localMetadata) {
         const input = requestFromInput(localMetadata, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
-        return dispatchResolvedTool(localMetadata, input, dispatchFlags, runtime, requestId, dispatchStartedAtMs);
+        return dispatchResolved(localMetadata, input);
     }
-    if (coreSpec && runtime.bridgeExecute && runtime.projectTools === undefined) {
-        return executeCoreBridgeSpec(name, coreSpec, parsed.input, dispatchFlags, runtime, requestId, positionalTarget);
+    if (coreSpec && runtime.bridgeExecute && runtime.projectTools === undefined && !runtime.createSessionSupervisor) {
+        return executeCoreBridgeSpec(name, coreSpec, parsed.input, dispatchFlags, runtime, requestId, admissionAbsoluteDeadlineMs, positionalTarget);
     }
-    const resolved = await resolveCatalogTool(name, catalogFlags, runtime, requestId);
+    const resolved = await resolveCatalogToolForInvocation(name, catalogFlags, runtime, requestId, started.context);
     if (resolved.ok === false)
-        return enrichTargetFailureWithDialogBlocker(resolved, catalogFlags, runtime);
+        return enrichTargetFailureWithDialogBlocker(resolved, catalogFlags, runtime, admissionAbsoluteDeadlineMs);
     const tool = resolved.tool;
     if (!tool)
         return failure(requestId, "E_TOOL_NOT_FOUND_FOR_TARGET", `Tool not found: ${name}.`, ["Run unitycli tools group to see tool groups.", "Run unitycli tools search <k1|k2|...> to find related tools."]);
     const input = requestFromInput(tool, { ...parsed.input, ...seed }, dispatchFlags, positionalTarget);
-    return dispatchResolvedTool(tool, input, dispatchFlags, runtime, requestId, dispatchStartedAtMs);
+    return dispatchResolvedTool(tool, input, dispatchFlags, runtime, requestId, admissionTimeoutMs, admissionAbsoluteDeadlineMs, resolved.context.discoveryProvenances);
+}
+/**
+ * live exact descriptor 在真实 catalog admission 上读取，并把 exact listener provenance 带回同一顶层调用。
+ * fixture 仍走相同 resolver，但没有伪造 registry identity。
+ */
+export async function resolveCatalogToolForInvocation(name, flags, runtime, requestId, context, fallbackName) {
+    if (runtime.projectTools) {
+        const resolved = await resolveCatalogTool(name, flags, runtime, requestId, context.admissionAbsoluteDeadlineMs, fallbackName);
+        return resolved.ok ? { ...resolved, context } : resolved;
+    }
+    const acquired = await acquireCatalogAdmissions(`catalog.resolve:${name}`, { name, ...(fallbackName ? { fallbackName } : {}) }, flags, runtime, requestId, context.timeoutMs, context.admissionAbsoluteDeadlineMs, "catalog-resolution-v1");
+    if ("result" in acquired)
+        return acquired.result;
+    const provenances = discoveryProvenances(acquired.admissions);
+    const primary = acquired.admissions.editor ?? acquired.admissions.runtime;
+    // descriptor discovery consumes only the original top-level admission budget.
+    for (const admission of Object.values(acquired.admissions)) {
+        if (admission)
+            admission.executionAbsoluteDeadlineMs = context.admissionAbsoluteDeadlineMs;
+    }
+    try {
+        const resolved = await resolveCatalogTool(name, flags, {
+            ...runtime, rootAdmission: primary, rootAdmissions: acquired.admissions,
+        }, requestId, context.admissionAbsoluteDeadlineMs, fallbackName);
+        return resolved.ok
+            ? { ...resolved, context: { ...context, discoveryProvenances: provenances } }
+            : resolved;
+    }
+    finally {
+        await releaseUnconsumedCatalogAdmissions(acquired);
+    }
+}
+function discoveryProvenances(admissions) {
+    const result = {};
+    for (const target of ["editor", "runtime"]) {
+        const admission = admissions[target];
+        if (!admission)
+            continue;
+        result[target] = {
+            target,
+            instanceId: admission.instanceId,
+            sessionId: admission.sessionId,
+            ...(target === "editor" ? { editorSessionId: admission.sessionId } : {}),
+            listenerId: admission.listenerId,
+            listenerGeneration: admission.listenerGeneration,
+        };
+    }
+    return result;
 }
 /** 公开统一catalog对每个在线target session分别占一个slot，禁止跨池旁路输出。 */
 export async function dispatchCatalogProjection(command, input, flags, runtime, requestId, execute) {
+    if (runtime.projectTools)
+        return execute(runtime);
     const startedAtMs = Date.now();
     const timeoutMs = Math.max(1, executionFromFlags(flags).timeoutMs ?? 30_000);
     const acquired = await acquireCatalogAdmissions(command, input, flags, runtime, requestId, timeoutMs, startedAtMs + timeoutMs, "catalog-projection-v1");
     if ("result" in acquired)
         return acquired.result;
     const primary = acquired.admissions.editor ?? acquired.admissions.runtime;
-    const result = await execute({ ...runtime, rootAdmission: primary, rootAdmissions: acquired.admissions });
-    await releaseUnconsumedCatalogAdmissions(acquired);
-    return result;
+    try {
+        return await execute({ ...runtime, rootAdmission: primary, rootAdmissions: acquired.admissions });
+    }
+    finally {
+        await releaseUnconsumedCatalogAdmissions(acquired);
+    }
 }
-async function acquireCatalogAdmissions(command, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs, completionContractIdentity) {
+async function acquireCatalogAdmissions(command, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs, completionContractIdentity, expectedDiscoveryProvenances) {
     const context = { admissions: {}, supervisors: {}, executionAbsoluteDeadlineMs: 0 };
-    let lastOffline;
+    let firstOffline;
     for (const target of ["editor", "runtime"]) {
-        const supervisor = new SessionSupervisor(flags, runtime);
+        const supervisor = createSessionSupervisor(flags, runtime);
         try {
-            const admission = await supervisor.acquireRootAdmission({ requestId, command, input, dryRun: false, target, completionContractIdentity, timeoutMs, admissionAbsoluteDeadlineMs });
+            const admission = await supervisor.acquireRootAdmission({
+                requestId, command, input, dryRun: false, target, completionContractIdentity,
+                captureDiscoveryProvenance: true,
+                expectedDiscoveryProvenance: expectedDiscoveryProvenances?.[target], timeoutMs, admissionAbsoluteDeadlineMs,
+            });
             context.admissions[target] = admission;
             context.supervisors[target] = supervisor;
         }
         catch (error) {
             const projected = catalogAdmissionFailure(requestId, error);
             if (projected.error.code === "E_INSTANCE_NOT_RUNNING" || projected.error.code === "E_RUNTIME_NOT_RUNNING") {
-                lastOffline = projected;
+                firstOffline ??= projected;
                 continue;
             }
             await releaseUnconsumedCatalogAdmissions(context);
@@ -112,7 +196,7 @@ async function acquireCatalogAdmissions(command, input, flags, runtime, requestI
     }
     const leases = Object.values(context.admissions).filter((value) => !!value);
     if (leases.length === 0)
-        return { result: lastOffline ?? failure(requestId, "E_INSTANCE_NOT_RUNNING", "No live Unity target is available for catalog projection.", ["Open the target Unity project or development Player."]) };
+        return { result: firstOffline ?? failure(requestId, "E_INSTANCE_NOT_RUNNING", "No live Unity target is available for catalog projection.", ["Open the target Unity project or development Player."]) };
     const now = Date.now();
     if (leases.some((lease) => lease.grantExpiresAtMs <= now)) {
         await releaseUnconsumedCatalogAdmissions(context);
@@ -128,9 +212,15 @@ async function releaseUnconsumedCatalogAdmissions(context) {
         const admission = context.admissions[target];
         const supervisor = context.supervisors[target];
         if (admission && supervisor)
-            await supervisor.completeRootAdmission(admission);
+            await completeUnconsumedRootAdmission(admission, supervisor);
     }
 }
+/** 迟到cleanup只接管仍由CLI持有的未消费lease。 */
+export async function completeUnconsumedRootAdmission(admission, supervisor) {
+    if (admission.consumed)
+        return;
+    await supervisor.completeRootAdmission(admission);
+}
 function catalogAdmissionFailure(requestId, error) {
     const selectionFailure = instanceSelectionFailure(requestId, error);
     if (selectionFailure)
@@ -139,7 +229,8 @@ function catalogAdmissionFailure(requestId, error) {
         return failure(requestId, error.code, error.message, error.nextActions, error.details, { transient: error.transient, retryAfterMs: error.retryAfterMs });
     return failure(requestId, "BRIDGE_CONNECTION_FAILED", error instanceof Error ? error.message : String(error), ["Inspect the selected Unity session."], undefined, { transient: true, retryAfterMs: 100 });
 }
-async function dispatchResolvedTool(tool, input, flags, runtime, requestId, dispatchStartedAtMs) {
+async function dispatchResolvedTool(tool, input, flags, runtime, requestId, admissionTimeoutMs, admissionAbsoluteDeadlineMs, discoveryProvenance) {
+    const invocationRuntime = discoveryProvenance ? { ...runtime, discoveryProvenances: discoveryProvenance } : runtime;
     const definition = findDefineTool(tool.name);
     const executionTool = tool;
     const completion = generatedToolCompletionContract(executionTool.name) ?? executionTool.completionContract;
@@ -152,10 +243,19 @@ async function dispatchResolvedTool(tool, input, flags, runtime, requestId, disp
         return failure(requestId, "E_TOOL_COMPLETION_CONTRACT_MISMATCH", `Tool ${executionTool.name} completion contract disagrees with its descriptor mutation signals.`, [
             `Run unitycli tools describe ${executionTool.name} and fix the descriptor or completion contract before execution.`
         ], { toolName: executionTool.name, contractMutation: completion.mutation, descriptorMutation });
-    const availabilityFlags = await extensionAvailabilityFlags(flags, runtime);
-    const availability = await checkToolExtensionAvailability(executionTool, availabilityFlags);
-    if (!availability.available)
-        return failure(requestId, availability.errorCode, availability.message, availability.nextActions, { extensionId: availability.extensionId, missingPackageIds: availability.availabilityResult?.missingPackageIds ?? executionTool.requiresPackages ?? [] });
+    if (executionTool.source === "extension" || extensionIdForToolName(executionTool.name)) {
+        try {
+            const extensionSnapshot = await freezeExtensionAvailability(flags, invocationRuntime);
+            const availability = await checkToolExtensionAvailability(executionTool, extensionSnapshot, admissionAbsoluteDeadlineMs);
+            if (!availability.available)
+                return failure(requestId, availability.errorCode, availability.message, availability.nextActions, { extensionId: availability.extensionId, missingPackageIds: availability.availabilityResult?.missingPackageIds ?? executionTool.requiresPackages ?? [] });
+        }
+        catch (error) {
+            if (error instanceof ExtensionInstallerError)
+                return failure(requestId, error.code, error.message, error.nextActions);
+            throw error;
+        }
+    }
     if (getBoolean(flags, "dry-run") && !executionTool.supportsDryRun)
         return failure(requestId, "E_DRY_RUN_UNSUPPORTED", `Tool ${executionTool.name} does not support dry-run.`, [
             "Remove --dry-run and invoke the Tool only when its declared side effects are acceptable.",
@@ -169,24 +269,28 @@ async function dispatchResolvedTool(tool, input, flags, runtime, requestId, disp
             errors: schemaErrors
         });
     return definition && executionTool.handler !== "bridge-runtime"
-        ? executeDefinition(executionTool, completion, definition, input, flags, runtime, requestId, dispatchStartedAtMs)
-        : executeLiveTool(executionTool, completion, input, flags, runtime, requestId, dispatchStartedAtMs);
+        ? executeDefinition(executionTool, completion, definition, input, flags, invocationRuntime, requestId, admissionTimeoutMs, admissionAbsoluteDeadlineMs)
+        : executeLiveTool(executionTool, completion, input, flags, invocationRuntime, requestId, admissionTimeoutMs, admissionAbsoluteDeadlineMs);
 }
 /** 已有 core bridge spec 使用统一参数构造，不进入 live custom wrapper。 */
-async function executeCoreBridgeSpec(name, spec, input, flags, runtime, requestId, positionalTarget) {
+async function executeCoreBridgeSpec(name, spec, input, flags, runtime, requestId, absoluteDeadlineMs, positionalTarget) {
     let args = await spec.buildArgs({ command: name, flags: bridgeWrapperFlags(flags, input), positionalTarget });
     if (spec.toolName)
         args = { name: spec.toolName, input: args };
-    return enrichTargetFailureWithDialogBlocker(await executeBridgePayload(requestId, spec.bridgeCommand, args, flags, runtime, undefined, {
+    return enrichTargetFailureWithDialogBlocker(await executeBridgePayload(requestId, spec.bridgeCommand, args, flags, runtime, {
         mode: "execute",
         mutation: true,
-    }), flags, runtime);
+        absoluteDeadlineMs,
+    }), flags, runtime, absoluteDeadlineMs);
 }
-async function executeDefinition(tool, completion, definition, input, flags, runtime, requestId, dispatchStartedAtMs) {
+async function executeDefinition(tool, completion, definition, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs) {
     let projectPath = typeof input.project === "string" ? input.project : process.cwd();
     const execution = executionFromFlags(flags);
-    const timeoutMs = Math.max(1, execution.timeoutMs ?? tool.timeoutMs ?? 30_000);
-    const admissionAbsoluteDeadlineMs = dispatchStartedAtMs + timeoutMs;
+    // 仅精确观察定义及 catalog fixture 不进入业务准入；生产中的普通本地 Tool 仍是 live target root。
+    if (isAdmissionIndependentLocalDefinition(tool, input)
+        || tool.handler === "offline" && runtime.projectTools !== undefined && !runtime.createSessionSupervisor) {
+        return executeLocalDefinition(tool, completion, definition, input, flags, runtime, requestId, projectPath, execution, admissionAbsoluteDeadlineMs);
+    }
     let selected;
     // package本地Tool也是live target的一等root；先固定实例，再由同一实例原子发放准入。
     try {
@@ -216,8 +320,19 @@ async function executeDefinition(tool, completion, definition, input, flags, run
     if ("result" in admissionContext)
         return admissionContext.result;
     const { admission, admissions, supervisors, executionAbsoluteDeadlineMs } = admissionContext;
-    const absoluteDeadlineMs = executionAbsoluteDeadlineMs;
     const rootRuntime = { ...runtime, rootAdmission: admission, rootAdmissions: admissions };
+    const cleanup = async () => {
+        await releaseUnconsumedCatalogAdmissions({ admissions, supervisors, executionAbsoluteDeadlineMs });
+    };
+    return executeLocalDefinition(tool, completion, definition, input, flags, rootRuntime, requestId, projectPath, execution, executionAbsoluteDeadlineMs, cleanup);
+}
+/** exact owner判定只接受固定公开观察与durable status Tool。 */
+function isAdmissionIndependentLocalDefinition(tool, _input) {
+    return resolveCatalogIndependentOperabilityTool(tool.name)?.handler === "offline";
+}
+/** 本地定义统一执行输出校验、effect barrier和deadline terminal。 */
+async function executeLocalDefinition(tool, completion, definition, input, flags, runtime, requestId, projectPath, execution, absoluteDeadlineMs, cleanupAfterLateSettlement) {
+    const barrier = new LocalEffectBarrier(tool.name, absoluteDeadlineMs);
     const run = async () => {
         try {
             const data = await definition.execute(input, {
@@ -225,16 +340,16 @@ async function executeDefinition(tool, completion, definition, input, flags, run
                 projectPath,
                 absoluteDeadlineMs,
                 execution,
-                dataDir: rootRuntime.dataDir,
-                artifactDir: getString(flags, "artifact-dir") ?? rootRuntime.dataDir ?? projectPath,
+                dataDir: runtime.dataDir,
+                artifactDir: getString(flags, "artifact-dir") ?? runtime.dataDir ?? projectPath,
                 logPath: typeof input.logPath === "string" ? input.logPath : undefined,
                 flags,
-                projectTools: rootRuntime.projectTools,
-                rootAdmission: admission,
-                rootAdmissions: admissions,
-                bridgeExecute: rootRuntime.bridgeExecute,
-                fetch: rootRuntime.fetch,
-                commitEffect: async () => undefined,
+                projectTools: runtime.projectTools,
+                rootAdmission: runtime.rootAdmission,
+                rootAdmissions: runtime.rootAdmissions,
+                bridgeExecute: runtime.bridgeExecute,
+                fetch: runtime.fetch,
+                commitEffect: barrier.commitEffect,
             });
             if (!tool.outputSchema)
                 throw new StructuredToolError("E_TOOL_COMPLETION_PROOF_INVALID", `Tool ${tool.name} has no output schema for terminal proof.`, [
@@ -265,42 +380,94 @@ async function executeDefinition(tool, completion, definition, input, flags, run
             return failure(requestId, "COMMAND_FAILED", error instanceof Error ? error.message : String(error), [`Run unitycli tools describe ${tool.name} for input requirements and examples.`]);
         }
     };
-    let result;
     try {
-        result = await settleToolExecutionAtDeadline(tool.name, requestId, completion.mutation, absoluteDeadlineMs, run);
+        return await settleToolExecutionAtDeadline(tool.name, requestId, completion.mutation, absoluteDeadlineMs, run, {
+            closeEffectBarrier: barrier.close,
+            cleanupAfterLateSettlement,
+        });
     }
     catch (error) {
         if (error instanceof PackageManagerError)
-            result = failure(requestId, error.code, error.message, error.nextActions);
-        else if (error instanceof StructuredToolError)
-            result = failure(requestId, error.code, error.message, error.nextActions, error.details);
-        else
-            result = failure(requestId, "COMMAND_FAILED", error instanceof Error ? error.message : String(error), [
-                `Run unitycli tools describe ${tool.name} for input requirements and examples.`
-            ]);
+            return failure(requestId, error.code, error.message, error.nextActions);
+        if (error instanceof StructuredToolError)
+            return failure(requestId, error.code, error.message, error.nextActions, error.details);
+        return failure(requestId, "COMMAND_FAILED", error instanceof Error ? error.message : String(error), [
+            `Run unitycli tools describe ${tool.name} for input requirements and examples.`
+        ]);
     }
-    if (rootResultHasTrustedTerminal(result))
-        await releaseUnconsumedCatalogAdmissions({ admissions, supervisors, executionAbsoluteDeadlineMs });
-    return result;
 }
-/** Tool自己的wait未按时settle时由框架结束CLI等待；已开始的Unity effect不因此停止。 */
-export async function settleToolExecutionAtDeadline(toolName, requestId, mutation, absoluteDeadlineMs, run) {
-    const remainingMs = absoluteDeadlineMs - Date.now();
-    if (remainingMs <= 0)
-        return toolDeadlineFailure(toolName, requestId, mutation);
-    let timer;
-    try {
-        return await Promise.race([
-            run(),
-            new Promise((resolveTimeout) => {
-                timer = setTimeout(() => resolveTimeout(toolDeadlineFailure(toolName, requestId, mutation)), remainingMs);
-            }),
-        ]);
+/** 首个effect barrier在公开timeout后永久关闭；此前已跨过时保持原owner。 */
+export class LocalEffectBarrier {
+    toolName;
+    absoluteDeadlineMs;
+    now;
+    closed = false;
+    committed = false;
+    constructor(toolName, absoluteDeadlineMs, now = Date.now) {
+        this.toolName = toolName;
+        this.absoluteDeadlineMs = absoluteDeadlineMs;
+        this.now = now;
     }
-    finally {
-        if (timer)
-            clearTimeout(timer);
+    commitEffect = async () => {
+        if (this.committed)
+            return;
+        if (this.closed || this.now() >= this.absoluteDeadlineMs)
+            throw new StructuredToolError("E_EXECUTION_TIMEOUT", `Tool ${this.toolName} cannot start its first effect after the public deadline.`, [
+                "Inspect editor.state and the affected business state before deciding whether to submit a new request."
+            ], { reason: "post-deadline-effect-barrier" });
+        this.committed = true;
+    };
+    close = () => { this.closed = true; };
+}
+/** Tool自己的wait未按时settle时只关闭公开terminal；每次settlement只执行一次精确cleanup。 */
+export async function settleToolExecutionAtDeadline(toolName, requestId, mutation, absoluteDeadlineMs, run, hooks = {}) {
+    const now = hooks.now ?? Date.now;
+    let cleanupStarted = false;
+    const cleanup = async () => {
+        if (cleanupStarted || !hooks.cleanupAfterLateSettlement)
+            return;
+        cleanupStarted = true;
+        try {
+            await hooks.cleanupAfterLateSettlement();
+        }
+        catch { /* cleanup不能重写已返回的terminal。 */ }
+    };
+    const remainingMs = absoluteDeadlineMs - now();
+    if (remainingMs <= 0) {
+        hooks.closeEffectBarrier?.();
+        trackCliProcessOwner(cleanup());
+        return toolDeadlineFailure(toolName, requestId, mutation);
     }
+    let timer;
+    let resolveTimer;
+    const markDeadline = () => {
+        hooks.closeEffectBarrier?.();
+        return { kind: "deadline" };
+    };
+    const runPromise = Promise.resolve().then(run);
+    const settlement = runPromise.then((value) => now() >= absoluteDeadlineMs ? markDeadline() : { kind: "result", value }, (reason) => now() >= absoluteDeadlineMs ? markDeadline() : { kind: "rejected", reason });
+    const owner = settlement.then(() => cleanup());
+    trackCliProcessOwner(owner);
+    const scheduleDeadline = () => {
+        const remaining = absoluteDeadlineMs - now();
+        if (remaining > 0) {
+            timer = setTimeout(scheduleDeadline, Math.max(1, remaining));
+            return;
+        }
+        resolveTimer?.(markDeadline());
+    };
+    const timerPromise = new Promise((resolveTimeout) => {
+        resolveTimer = resolveTimeout;
+        timer = setTimeout(scheduleDeadline, Math.max(1, remainingMs));
+    });
+    const winner = await Promise.race([settlement, timerPromise]);
+    if (timer)
+        clearTimeout(timer);
+    if (winner.kind === "deadline")
+        return toolDeadlineFailure(toolName, requestId, mutation);
+    if (winner.kind === "result")
+        return winner.value;
+    throw winner.reason;
 }
 /** mutation超时只能读取业务状态，不能建议直接重试或声称底层执行已取消。 */
 function toolDeadlineFailure(toolName, requestId, mutation) {
@@ -539,11 +706,12 @@ function validateKnownLocalTerminal(toolName, completion, result, input) {
     }
     if (toolName === "editor.refresh") {
         const editorState = objectRecord(record.editorState);
-        if (typeof record.changed !== "boolean" || typeof record.compilationTriggered !== "boolean"
-            || typeof record.sourceFileCount !== "number" || !Number.isSafeInteger(record.sourceFileCount) || record.sourceFileCount < 0
-            || !sha256(record.sourceFingerprint) || !sha256(record.dependencyVersion)
+        const generation = objectRecord(record.generation);
+        if (typeof record.changed !== "boolean" || typeof record.importObserved !== "boolean" || typeof record.compilationTriggered !== "boolean"
+            || !generation || !nonnegativeInteger(generation.dependencyBefore) || !nonnegativeInteger(generation.dependencyAfter)
+            || !nonnegativeInteger(generation.processedBefore) || !nonnegativeInteger(generation.processedAfter)
             || !editorState || editorState.status !== "ready" || editorState.compile !== false || editorState.import !== false) {
-            throw invalidCompletionProof(toolName, completion, "did not prove a stable source and dependency refresh readback");
+            throw invalidCompletionProof(toolName, completion, "did not prove stable Unity-owned import generations and ready state");
         }
         return true;
     }
@@ -648,7 +816,7 @@ function findFailedCompletionStatus(value) {
 }
 async function acquireToolAdmission(tool, completion, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs, selected) {
     if (MULTI_TARGET_CATALOG_TOOLS.has(tool.name)) {
-        const acquired = await acquireCatalogAdmissions(tool.name, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs, JSON.stringify(completion));
+        const acquired = await acquireCatalogAdmissions(tool.name, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs, JSON.stringify(completion), runtime.discoveryProvenances);
         if ("result" in acquired)
             return acquired;
         const admission = acquired.admissions.editor ?? acquired.admissions.runtime;
@@ -657,7 +825,7 @@ async function acquireToolAdmission(tool, completion, input, flags, runtime, req
     }
     const target = selected?.instance.activeSession?.target ?? selected?.instance.target ?? toolTarget(tool, flags);
     const admissionFlags = selected ? { ...flags, instance: selected.instance.instanceId } : flags;
-    const supervisor = new SessionSupervisor(admissionFlags, runtime);
+    const supervisor = createSessionSupervisor(admissionFlags, runtime);
     try {
         const admission = await supervisor.acquireRootAdmission({
             requestId,
@@ -666,6 +834,7 @@ async function acquireToolAdmission(tool, completion, input, flags, runtime, req
             dryRun: getBoolean(flags, "dry-run") || getBoolean(flags, "preflight"),
             target,
             completionContractIdentity: JSON.stringify(completion),
+            expectedDiscoveryProvenance: runtime.discoveryProvenances?.[target],
             timeoutMs,
             admissionAbsoluteDeadlineMs,
         });
@@ -705,37 +874,37 @@ const UNKNOWN_ROOT_OUTCOME_CODES = new Set([
 function rootResultHasTrustedTerminal(result) {
     return result.ok || !UNKNOWN_ROOT_OUTCOME_CODES.has(result.error.code);
 }
-async function executeLiveTool(tool, completion, input, flags, runtime, requestId, dispatchStartedAtMs) {
-    const timeoutMs = Math.max(1, executionFromFlags(flags).timeoutMs ?? tool.timeoutMs ?? 30_000);
-    const admissionContext = await acquireToolAdmission(tool, completion, input, flags, runtime, requestId, timeoutMs, dispatchStartedAtMs + timeoutMs);
+async function executeLiveTool(tool, completion, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs) {
+    const admissionContext = await acquireToolAdmission(tool, completion, input, flags, runtime, requestId, timeoutMs, admissionAbsoluteDeadlineMs);
     if ("result" in admissionContext)
         return admissionContext.result;
     const { admission, supervisor } = admissionContext;
     const runtimeTarget = admission.target === "runtime";
     const wrapper = runtimeTarget ? "runtime-tool.run" : "project-tool.run";
-    const descriptorBinding = {
-        ...(tool.liveDescriptorFingerprint ? { liveDescriptorFingerprint: tool.liveDescriptorFingerprint } : {})
-    };
     const rootRuntime = { ...runtime, rootAdmission: admission };
     // live descriptor已完成schema校验，wrapper直接承载typed input并复用同一root admission。
     const mutation = toolIsMutation(tool);
-    const result = await enrichTargetFailureWithDialogBlocker(await executeBridgeCommand(requestId, wrapper, bridgeWrapperFlags(flags, input), tool.name, rootRuntime, descriptorBinding, {
+    const result = await enrichTargetFailureWithDialogBlocker(await executeBridgeCommand(requestId, wrapper, bridgeWrapperFlags(flags, input), tool.name, rootRuntime, {
         mode: "execute",
         mutation,
         defaultTimeoutMs: timeoutMs,
         absoluteDeadlineMs: admission.executionAbsoluteDeadlineMs,
-    }), flags, rootRuntime);
+    }), flags, rootRuntime, admission.executionAbsoluteDeadlineMs);
     if (rootResultHasTrustedTerminal(result))
         await supervisor.completeRootAdmission(admission);
     return result;
 }
-/** Bridge wrappers may discard supervisor details; append one independent read-only modal diagnosis to target failures. */
-export async function enrichTargetFailureWithDialogBlocker(result, flags, runtime, observer = new EditorBlockerObserver()) {
+/** Bridge wrapper失败只在原absolute deadline内追加一次有界modal诊断。 */
+export async function enrichTargetFailureWithDialogBlocker(result, flags, runtime, absoluteDeadlineMs, observer = new EditorBlockerObserver(), selectObservation = selectObservationInstanceForFlags, now = Date.now) {
     if (result.ok || (result.error.details && typeof result.error.details === "object" && Array.isArray(result.error.details.blockers)))
         return result;
+    const deadlineMs = Math.min(absoluteDeadlineMs, now() + 10_000);
+    if (deadlineMs - now() <= 0)
+        return result;
     try {
-        const deadlineMs = Date.now() + 10_000;
-        const selection = await selectObservationInstanceForFlags(flags, runtime.dataDir ?? defaultDataDir(), Math.max(0, deadlineMs - Date.now()));
+        const selection = await selectObservation(flags, runtime.dataDir ?? defaultDataDir(), Math.max(0, deadlineMs - now()));
+        if (deadlineMs - now() <= 0)
+            return result;
         const instance = selection.instance;
         const observation = await observer.observe({ instanceId: instance.instanceId, canonicalProjectPath: instance.canonicalProjectPath, displayProjectPath: instance.displayProjectPath }, deadlineMs, instance.activeSession);
         const blockers = observation.outcome === "observed-blocked" ? sanitizeEditorBlockers(observation.blockers) : [];
@@ -749,7 +918,7 @@ export async function enrichTargetFailureWithDialogBlocker(result, flags, runtim
                 ] } };
     }
     catch {
-        // An unproven probe must not be represented as an empty blocker list or replace the original failure.
+        // 未证明的诊断不能替换主错误。
         return result;
     }
 }
@@ -900,7 +1069,7 @@ function inputTooLarge(requestId, source, maxBytes) {
     return { ok: false, error: failure(requestId, "E_CODE_INPUT_TOO_LARGE", `${source} exceeds the ${maxBytes}-byte code.exec typed-input limit.`, ["Use a smaller JSON input and keep Runtime Code source below its documented local budget."]) };
 }
 function inputDeadlineExceeded(requestId) {
-    return { ok: false, error: failure(requestId, "E_EXECUTION_TIMEOUT", "code.exec typed input did not finish reading before the immutable deadline.", ["Provide bounded input from a responsive local source or submit a new request with a sufficient timeout."]) };
+    return { ok: false, error: failure(requestId, "E_EXECUTION_TIMEOUT", "Tool typed input did not finish reading before the immutable admission deadline.", ["Provide bounded input from a responsive local source or submit a new request with a sufficient timeout."]) };
 }
 const TOOL_CONTROL_FLAGS = new Set([
     "input", "input-file", "stdin", "pretty", "format",