unity-open-mcp 1.2.3 → 1.3.0

package/dist/tool-router.js

@@ -1,3 +1,17 @@
+import { testRunOperation, projectCommandOperation } from "./jobs/adapters.js";
+import { JobManager, JobManagerError } from "./jobs/job-manager.js";
+import { handleJobs } from "./jobs/handler.js";
+import { PROCESS_AGENT_ID, PROCESS_IDENTITY } from "./agent-identity.js";
+import { buildEditorSearch } from "./editor-search.js";
+import { withSchemaDefaults } from "./schema-defaults.js";
+import { validateSchema, wireArguments } from "./tool-contract.js";
+import { discoverTools, compactDiscoverySchema } from "./capabilities/discovery.js";
+import { PingCache } from "./ping-cache.js";
+import { resolveProjectPath, validateUnityProjectRoot } from "./project-path.js";
+import { resolvePort, resolveAuthToken } from "./instance-discovery.js";
+import { skipsReloadProbe } from "./local-tools.js";
+import { confirmBridgeReleaseTag, resolveLatestVersion } from "./release-lookup.js";
+import { LiveClient } from "./live-client.js";
 import { AssetModelCache, isCompressible, routeCompressible } from "./compressible-router.js";
 import { listAssetsOffline, findReferencesOffline, dependenciesOffline } from "./offline.js";
 import { resolveEditorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES, detectStaleLog, detectStaleAssembly, detectErrorsPredatingEdits, parseLogAuthorship, compareLogAuthorship } from "./unity-log.js";
@@ -53,7 +67,8 @@ const defaultHubBackend = {
     getInstallPath: () => getInstallPath(),
     setInstallPath: (path) => setInstallPath(path),
 };
-import { BATCH_TOOL_NAMES, ALWAYS_BATCH_TOOLS } from "./batch-spawn.js";
+import { BatchSpawn, BATCH_TOOL_NAMES, ALWAYS_BATCH_TOOLS, activeHeadlessRun } from "./batch-spawn.js";
+import { filterVisibleTools } from "./tool-session-state.js";
 import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, isOutputProfile, } from "./output-profile.js";
 /**
  * Single source of truth for the `_source` tag. Every route-tagging site goes
@@ -186,6 +201,17 @@ function transformLiveResult(result, source, meta, transform) {
 function localError(code, message) {
     return sourceResult({ error: { code, message } }, "local", true);
 }
+const defaultReleaseLookup = {
+    latest: () => resolveLatestVersion(globalThis.fetch.bind(globalThis)),
+    confirmBridgeTag: (version) => confirmBridgeReleaseTag(version, globalThis.fetch.bind(globalThis)),
+};
+let releaseLookup = defaultReleaseLookup;
+/** Test seam for the upgrade route's network lookups. Returns a restore function. */
+export function setReleaseLookupForTest(lookup) {
+    const previous = releaseLookup;
+    releaseLookup = lookup ?? defaultReleaseLookup;
+    return () => { releaseLookup = previous; };
+}
 // M26 Plan 2 — gate-consistent envelope shape for the mutating Hub control
 // tools (install_editor / install_modules / set_install_path). These are
 // system-level ops, not project-asset mutations, so paths_hint is N/A and the
@@ -341,7 +367,7 @@ function groupLiveRefsByKind(paths) {
     return counts;
 }
 // Operator-facing "what to do next" hint for each coarse status. Kept short
-// and action-oriented so the Validation Suite can render it inline.
+// and action-oriented so an operator UI can render it inline.
 function bridgeStatusNextStep(status, wedge) {
     if (status === "wedged") {
         return wedge?.reason === "main_thread_wedged"
@@ -392,6 +418,57 @@ function bridgeStatusNextStep(status, wedge) {
                 "Bridge) and confirm it is started.";
     }
 }
+// This server's own headless batch run holds the project. The Unity process
+// scan deliberately skips that child (it is not an Editor the user owns), so
+// Editor-ownership surfaces would otherwise report "no Unity running" and send
+// the agent to relaunch via the Hub, which would collide with the run.
+function describeHeadlessRun(run, now = Date.now()) {
+    return {
+        tool: run.tool,
+        operation: run.operation,
+        pid: run.pid,
+        startedAt: new Date(run.startedAt).toISOString(),
+        elapsedMs: Math.max(0, now - run.startedAt),
+        timeoutMs: run.timeoutMs,
+    };
+}
+function headlessRunSentence(run, now = Date.now()) {
+    const elapsedS = Math.round(Math.max(0, now - run.startedAt) / 1000);
+    const timeoutS = Math.round(run.timeoutMs / 1000);
+    return (`The only Unity process for this project is this MCP server's own headless ` +
+        `run for ${run.tool}` +
+        (run.pid !== null ? ` (pid ${run.pid})` : "") +
+        `, started ${elapsedS}s ago with a ${timeoutS}s timeout. It is not an ` +
+        `interactive Editor, and it exits on its own when the operation finishes ` +
+        `or the timeout elapses.`);
+}
+const HEADLESS_RUN_NEXT_STEPS = [
+    "Wait for the pending headless call to return; it releases the project " +
+        "when it finishes or when its timeout elapses.",
+    "Do not relaunch Unity for this project via the Hub meanwhile: Unity " +
+        "allows one Editor per project, so a second instance collides with the " +
+        "headless run's project lock.",
+];
+function headlessRunErrorResult(action, run, projectPath) {
+    const now = Date.now();
+    const tail = action === "restart_editor"
+        ? " restart_editor never targets the server's own headless run, so there is no Editor to restart."
+        : " resource_pressure watches the interactive Editor's descriptor leak, which a short-lived headless run does not accumulate.";
+    return sourceResult({
+        error: {
+            code: "headless_run_in_progress",
+            message: headlessRunSentence(run, now) + tail,
+            projectPath,
+            ...describeHeadlessRun(run, now),
+        },
+        agentNextSteps: [
+            ...HEADLESS_RUN_NEXT_STEPS,
+            action === "restart_editor"
+                ? "Call restart_editor again only if an interactive Editor for this project hangs after the run completes."
+                : "Once the run completes and an interactive Editor is open, call resource_pressure again; pass an explicit pid to sample the headless process anyway.",
+        ],
+    }, "local", true);
+}
 /**
  * specs/feedback.md 2026-08-24 — wire-contract staleness block.
  *
@@ -471,6 +548,60 @@ export class ToolRouter {
     onToolListChanged;
     hubBackend;
     globalLogPathOverride;
+    jobManager;
+    get jobs() { return this.jobManager ??= new JobManager(); }
+    closeJobs() { this.jobManager?.close(); }
+    async routeJobs(args, identity = PROCESS_IDENTITY) {
+        const definition = ALL_TOOLS.find(t => t.name === "unity_open_mcp_jobs");
+        const errors = validateSchema(args, definition.inputSchema);
+        if (errors.length)
+            return localError("invalid_arguments", errors.join("; "));
+        const owner = { project: this.projectPath || "default", agent: identity.agent,
+            ...(identity.port === undefined ? {} : { port: identity.port }) };
+        try {
+            // A port override names a bridge, not a project: bind the job client to
+            // the Editor whose lock claims that port (its bearer token and its lock
+            // diagnostics), exactly like a direct override call. resolveAuthToken
+            // yields no token for an explicit port, and the default project's lock
+            // would describe the wrong Editor.
+            const clientFor = (jobOwner) => jobOwner.port === undefined
+                ? jobOwner.agent === PROCESS_AGENT_ID ? this.live : this.live.forAgent(jobOwner.agent)
+                : LiveClient.forPortOverride(jobOwner.port, this.projectPath, jobOwner.agent);
+            if (args.action === "start" && typeof args.tool_or_command === "string") {
+                const name = args.tool_or_command, key = args.idempotency_key;
+                if (name === "unity_senses_run_tests") {
+                    if (!this.jobs.hasOperation(name))
+                        this.jobs.register(name, testRunOperation(clientFor));
+                }
+                else if (name.startsWith("project.") && !(typeof key === "string" && this.jobs.hasKey(owner, key))) {
+                    // A retry whose key already names a job gets that job (or
+                    // idempotency_conflict) from start() without the catalog, which may
+                    // be unreachable mid-reload or declare a contract changed since.
+                    // Re-read the catalog on every new start: a domain reload can change the
+                    // command's async/cancellable declaration, and an adapter frozen at
+                    // first registration would refuse the job for the rest of the session.
+                    const catalog = await clientFor(owner).projectCommands({ action: "describe", id: name });
+                    if (catalog.error) {
+                        // A transport/catalog failure (bridge down, reloading, too old) is
+                        // not "this command is unsupported": surface the catalog's own
+                        // code so the agent retries instead of abandoning the plan.
+                        const failure = catalog.error;
+                        throw new JobManagerError(failure.code ?? "catalog_unavailable", failure.message ?? "Project command catalog is unavailable.");
+                    }
+                    const command = catalog.command;
+                    if (!command?.available || !command.async)
+                        throw new JobManagerError("job_operation_unsupported", "Target must be an available async project command.");
+                    const cancellable = command.cancellable === true;
+                    if (this.jobs.operation(name)?.cancellable !== cancellable)
+                        this.jobs.register(name, projectCommandOperation(name, cancellable, clientFor), true);
+                }
+            }
+            return sourceResult(await handleJobs(this.jobs, owner, args), "local");
+        }
+        catch (error) {
+            return localError(error instanceof JobManagerError ? error.code : "invalid_arguments", error instanceof Error ? error.message : String(error));
+        }
+    }
     modelCache = new AssetModelCache();
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -487,15 +618,24 @@ export class ToolRouter {
         if (this.routeHandlers)
             return this.routeHandlers;
         const handlers = new Map([
-            // Offline-routed tools (resolved from disk; never hit the bridge).
+            // Disk reads and live compiler evidence with an offline log fallback.
             ["unity_open_mcp_list_assets", (_l, a) => this.routeListAssets(a)],
-            ["unity_open_mcp_read_compile_errors", (_l, a) => this.routeReadCompileErrors(a)],
+            ["unity_open_mcp_read_compile_errors", (l, a) => this.routeReadCompileErrors(a, l)],
             // Local-routed tools (server-only; no live/batch hop).
             ["unity_senses_pull_events", (l, a) => this.routePullEvents(a, l)],
             ["unity_open_mcp_capabilities", (l, a) => this.routeCapabilities(a, l)],
             ["unity_open_mcp_list_rules", (_l, a) => this.routeListRules(a)],
             ["unity_open_mcp_generate_skill", (_l, a) => this.routeGenerateSkill(a)],
-            ["unity_open_mcp_manage_tools", (l, a) => this.routeManageTools(a, l)],
+            ["unity_open_mcp_manage_tools", (l, a, id) => this.routeManageTools(a, l, id)],
+            ["unity_open_mcp_project_commands", (l, a) => this.routeProjectCommands(a, l)],
+            // Live tool whose release lookups (npm latest, GitHub tag) run HERE so
+            // the Editor main thread never blocks on the network.
+            ["unity_open_mcp_upgrade", (l, a) => this.routeUpgrade(a, l)],
+            // The owner is the request identity (agent id + per-request port
+            // override), never the live client's: the default client always sends
+            // the process agent id, whatever _meta.agentId the call carried. Direct,
+            // manage_tools(invoke) and port-override calls therefore share one owner.
+            ["unity_open_mcp_jobs", (_l, a, id) => this.routeJobs(a, id)],
             ["unity_open_mcp_bridge_status", (l, a) => this.routeBridgeStatus(a, l)],
             // M31 Plan 3 — Editor fd-exhaustion operator surfaces. restart_editor
             // is the reactive kill half (acts AFTER the Editor is hung);
@@ -545,28 +685,132 @@ export class ToolRouter {
         this.hubBackend = hubBackend;
         this.globalLogPathOverride = globalLogPathOverride;
     }
-    async route(toolName, args) {
-        return this.routeCore(this.live, toolName, args);
+    async route(toolName, args, identity = PROCESS_IDENTITY) {
+        return this.routeCore(this.live, toolName, args, identity);
+    }
+    /**
+     * `capabilities` / `bridge_status` with an explicit project_path, from any
+     * entry point (direct, manage_tools invoke, port override). The probe router
+     * gets the arguments without project_path, so it dispatches normally. A
+     * per-request port override is refused rather than dropped or mixed in:
+     * project_path brings its own port/auth discovery, and pinging the override
+     * port would present another bridge's answer as the probed project's.
+     */
+    async routeProjectProbe(toolName, args, identity) {
+        if (typeof args.project_path !== "string" || !args.project_path.trim())
+            return localError("invalid_project_path", "project_path must name a Unity project root.");
+        if (identity.port !== undefined)
+            return localError("invalid_arguments", "project_path discovers that project's own bridge port; drop the _meta.port (or port) override for this call.");
+        const selected = resolveProjectPath({ flagPath: args.project_path }).absolute;
+        if (!validateUnityProjectRoot(selected).valid)
+            return localError("invalid_project_path", "project_path must contain Assets, Packages, and ProjectSettings.");
+        const { project_path: _selected, ...rest } = args;
+        return this.projectProbeRouter(selected).route(toolName, rest, identity);
+    }
+    /**
+     * Router for a read-only probe of another project: its own port/auth
+     * discovery and a throwaway copy of this session. Discovery still reconciles
+     * auto-activation against the probed project's inventory, so the probe
+     * reports that project's view, but only the copy changes — this session's
+     * active groups and tools/list stay put, and no list_changed is wired. The
+     * probe tools are local-only and never spawn Unity; the probe's own batch
+     * router only answers headless availability for that project's editor.
+     */
+    projectProbeRouter(projectPath) {
+        const live = new LiveClient(resolvePort(projectPath), new PingCache(), resolveAuthToken(projectPath), projectPath);
+        return new ToolRouter(live, this.projectProbeBatch(projectPath), projectPath, this.eventStream, this.sessionState.clone());
+    }
+    // Batch routers of probed projects, keyed by project path and bounded to
+    // the most recently probed few. Constructing a BatchSpawn walks every Hub
+    // install root synchronously; a polled probe must not pay that on every
+    // call, and the router keeps its own editor-resolution cache (revalidated
+    // when the project version or the env inputs change).
+    static PROBE_BATCH_CACHE_SIZE = 8;
+    probeBatchByProject = new Map();
+    projectProbeBatch(projectPath) {
+        const cached = this.probeBatchByProject.get(projectPath);
+        if (cached) {
+            // Re-insert so the map keeps insertion order as recency order.
+            this.probeBatchByProject.delete(projectPath);
+            this.probeBatchByProject.set(projectPath, cached);
+            return cached;
+        }
+        const batch = new BatchSpawn({ projectPath });
+        this.probeBatchByProject.set(projectPath, batch);
+        while (this.probeBatchByProject.size > ToolRouter.PROBE_BATCH_CACHE_SIZE) {
+            const oldest = this.probeBatchByProject.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.probeBatchByProject.delete(oldest);
+        }
+        return batch;
     }
     /**
      * M23 Plan 3 — route with a per-call live-client override. Used when a
      * per-request `_meta.port` override targets a different bridge instance than
      * the default. The override client bypasses shared session state (it is a
      * fresh LiveClient aimed at the override port); all other routing logic is
-     * identical to {@link route}. When `overrideLive` is null the default client
-     * is used (identical to {@link route}).
+     * identical to {@link route}. `identity` carries the override port and the
+     * request's agent id.
      */
-    async routeOverride(toolName, args, overrideLive) {
-        return this.routeCore(overrideLive, toolName, args);
+    async routeOverride(toolName, args, overrideLive, identity) {
+        return this.routeCore(overrideLive, toolName, args, identity);
+    }
+    async routeCore(live, toolName, args, identity) {
+        // Every entry point funnels through here, so an explicit project_path is
+        // retargeted before validation and wiring wherever the call came from.
+        if ((toolName === "unity_open_mcp_capabilities" || toolName === "unity_open_mcp_bridge_status") && args.project_path !== undefined)
+            return this.routeProjectProbe(toolName, args, identity);
+        const definition = ALL_TOOLS.find(t => t.name === toolName);
+        if (definition) {
+            const errors = validateSchema(args, definition.inputSchema);
+            if (errors.length)
+                return sourceResult({ error: { code: "invalid_arguments", message: errors.join("; ") }, errors, _route: { route: "local" } }, "local", true);
+            const notes = [];
+            const wire = wireArguments(args, definition.inputSchema, notes);
+            if (toolName === "unity_open_mcp_batch_execute" && Array.isArray(wire.commands)) {
+                wire.commands = wire.commands.map(command => {
+                    const nested = ALL_TOOLS.find(t => t.name === command.tool);
+                    return nested
+                        ? { ...command, params: wireArguments(command.params ?? {}, nested.inputSchema, notes) }
+                        : command;
+                });
+            }
+            // Recursive dispatch only after validation; alias notes are attached to the normal result.
+            return this.routeValidated(live, toolName, wire, notes, identity);
+        }
+        return this.routeValidated(live, toolName, args, [], identity);
+    }
+    async routeValidated(live, toolName, args, notes, identity) {
+        const result = await this.routeUnchecked(live, toolName, args, identity);
+        if (notes.length)
+            result.content.push({ type: "text", text: JSON.stringify({ deprecations: [...new Set(notes)] }) });
+        return result;
     }
-    async routeCore(live, toolName, args) {
+    async routeUnchecked(live, toolName, args, identity) {
+        const localProbe = skipsReloadProbe(toolName);
+        const lock = !localProbe && this.projectPath ? readInstanceLock(this.projectPath) : null;
+        // The lock describes the default project's Editor. A per-request port
+        // override aimed elsewhere has no lock of its own (override clients never
+        // read locks) and its LiveClient handles that bridge's readiness, so the
+        // default Editor's reload must not refuse it. An override naming the
+        // default Editor's own port still targets the reloading Editor.
+        const targetsLockedEditor = identity.port === undefined || identity.port === lock?.port;
+        if (targetsLockedEditor && classifyInstance(lock) === "reloading") {
+            // One bounded re-probe. No headless fallback can acquire this Editor's project.
+            await new Promise(resolve => setTimeout(resolve, 250));
+            const available = await live.isLiveAvailable(750);
+            if (!available || classifyInstance(readInstanceLock(this.projectPath)) === "reloading") {
+                return sourceResult({ error: { code: "editor_reloading", message: "The live Editor is compiling or reloading. Retry after it settles." }, retryAfterMs: 1000 }, "local", true);
+            }
+        }
         // Named-tool dispatch (T3.2): the handler map covers every exact-name
         // route. The per-tool policy rationale (offline / local / hub / offline-
         // first / verify-fold / scene-paging) lives in each routeXxx method's
         // header comment.
         const handler = this.getRouteHandlers().get(toolName);
         if (handler) {
-            return handler(live, args);
+            return handler(live, args, identity);
         }
         // Compact drill-down reads: offline-first for text-serialized assets, fall
         // back to live bridge for binary formats. The compressible-router handles
@@ -713,7 +957,7 @@ export class ToolRouter {
             return meta;
         }
     }
-    async routeReadCompileErrors(args) {
+    async routeReadCompileErrors(args, live) {
         const tailBytes = typeof args.tail_bytes === "number" && args.tail_bytes >= 4096
             ? Math.min(Math.floor(args.tail_bytes), 1048576)
             : DEFAULT_LOG_TAIL_BYTES;
@@ -731,6 +975,40 @@ export class ToolRouter {
         const resolvedLog = resolveEditorLogPath(this.projectPath, undefined, livePid, this.globalLogPathOverride);
         const logPath = resolvedLog.path;
         const tail = readLogTail(logPath, tailBytes);
+        const compile = await live.readCompileState?.();
+        if (compile && compile.status !== "indeterminate") {
+            const historical = summarizeProjectHealth(tail.content);
+            const failed = compile.status === "compile_failed";
+            const pipelineErrors = failed && Array.isArray(compile.errors) ? compile.errors : [];
+            // Unity can report a failed compile the bridge never observed (it ran
+            // before the bridge domain loaded, e.g. the Editor-startup compile), so
+            // the pipeline holds no diagnostics for it. Editor.log does: promote its
+            // errors instead of answering "failed" with nothing to fix.
+            const fromLog = failed && pipelineErrors.length === 0;
+            const currentErrors = fromLog ? historical.compilerErrors : pipelineErrors;
+            return sourceResult({
+                ...compile, errorCount: currentErrors.length, errors: currentErrors,
+                errorSource: fromLog ? "Editor.log" : "CompilationPipeline",
+                unhealthy: failed,
+                staleAssembly: compile.status === "assembly_stale",
+                headline: compile.status === "no_errors_found" ? "Current compile is clean; source content matches the completed generation."
+                    : compile.status === "currently_compiling" ? "Compilation is active; wait for completion."
+                        : compile.status === "assembly_stale" ? "Source content changed after the last compile; recompile before trusting assemblies."
+                            : !fromLog ? "Current compilation failed. Fix the compiler diagnostics and recompile."
+                                : currentErrors.length > 0
+                                    ? "Current compilation failed in a compile the bridge did not observe (e.g. at Editor " +
+                                        `startup); errors are the ${currentErrors.length} compiler diagnostic(s) from Editor.log. ` +
+                                        "Fix them and recompile."
+                                    : "Current compilation failed in a compile the bridge did not observe (e.g. at Editor " +
+                                        "startup), and the Editor.log tail holds no compiler diagnostics. Raise tail_bytes or " +
+                                        `recompile (${toolHintReference("unity_open_mcp_recompile_scripts")}) to capture them.`,
+                compileSource: "CompilationPipeline", logPath, logSource: resolvedLog.reason,
+                logAuthorship: parseLogAuthorship(tail.content),
+                historicalLogErrors: fromLog ? [] : historical.compilerErrors,
+                historicalLogIssues: historical.issues,
+                logReadError: tail.error ?? null,
+            }, "live");
+        }
         if (tail.error) {
             return {
                 content: [
@@ -1122,6 +1400,13 @@ export class ToolRouter {
         };
     }
     async routeCapabilities(args, live) {
+        if (["tool_name", "query", "group", "tag", "available", "active", "route", "mutating"].some(k => args[k] !== undefined)) {
+            if (args.kind !== undefined && args.kind !== "tools")
+                return localError("invalid_arguments", "Tool discovery filters require kind: tools (or omit kind).");
+            const inventory = await this.fetchInventoryAndReconcile(live);
+            const found = discoverTools(ALL_TOOLS, BATCH_TOOL_NAMES, this.sessionState, inventory?.tools, args, this.batch.headlessAvailable());
+            return sourceResult(found, "local", !!found.error);
+        }
         const kind = args.kind === "tools" || args.kind === "rules" || args.kind === "fixes"
             ? args.kind
             : undefined;
@@ -1229,9 +1514,49 @@ export class ToolRouter {
     // when reachable; when the bridge is offline it reports `available: null`
     // (unknown) and the agent should fall back to `unity_open_mcp_capabilities`
     // for the authoritative compiled-state report.
-    async routeManageTools(args, live) {
+    async routeManageTools(args, live, identity) {
         const action = typeof args.action === "string" ? args.action : "";
         const group = typeof args.group === "string" ? args.group.trim() : "";
+        const actionKeys = {
+            list_groups: [], reset: [], activate: ["group"], deactivate: ["group"],
+            suggest: ["intent", "tags"], activate_for: ["intent", "tags"],
+            invoke: ["tool_name", "arguments"], editor_search: ["search_text", "asset_type", "open_ui"],
+        };
+        const ignored = Object.keys(args).filter(k => k !== "action" && actionKeys[action] && !actionKeys[action].includes(k));
+        if (ignored.length)
+            return this.manageToolsError("invalid_arguments", `Keys not used by ${action}: ${ignored.join(", ")}`);
+        if (action === "editor_search") {
+            const query = buildEditorSearch(String(args.search_text ?? ""), args.asset_type);
+            if (args.open_ui !== true)
+                return sourceResult({ query, opened: false, purpose: "Human collaboration; use search_assets/find_references for structured results." }, "local");
+            const result = await this.routeCore(live, "unity_open_mcp_execute_csharp", {
+                code: `UnityEditor.Search.SearchService.ShowWindow(UnityEditor.Search.SearchService.CreateContext(${JSON.stringify(query)})); return ${JSON.stringify(query)};`,
+                read_only: true,
+            }, identity);
+            // The Search window opens through a read_only snippet, which a running
+            // project job refuses (the bridge cannot verify a snippet writes
+            // nothing). The handoff is optional UI, so report the query instead of
+            // surfacing the refusal as a failed search.
+            const body = result.isError ? parseResultBody(result) : null;
+            const mutation = body?.mutation;
+            const refusal = mutation?.error ?? body?.error;
+            if (refusal?.code === "job_busy") {
+                return sourceResult({
+                    query, opened: false, reason: "job_busy",
+                    ...(refusal.job ? { job: refusal.job } : {}),
+                    message: "Unity Search cannot be opened while an asynchronous project command job runs. " +
+                        "Paste the query into Unity Search manually, or retry open_ui once the job reaches a terminal state.",
+                }, "local");
+            }
+            result.content.push({ type: "text", text: JSON.stringify({ query, opened: !result.isError }) });
+            return result;
+        }
+        if (action === "invoke") {
+            const name = typeof args.tool_name === "string" ? args.tool_name : "";
+            if (name === "unity_open_mcp_manage_tools" || !filterVisibleTools(ALL_TOOLS, this.sessionState).some(t => t.name === name))
+                return this.manageToolsError("tool_not_active", "Activate the target group first; recursive manage_tools invocation is forbidden.");
+            return this.routeCore(live, name, withSchemaDefaults(ALL_TOOLS.find(t => t.name === name), (args.arguments ?? {})), identity);
+        }
         if (action === "list_groups") {
             return this.manageToolsListGroups(live);
         }
@@ -1299,7 +1624,94 @@ export class ToolRouter {
             });
         }
         return this.manageToolsError("unknown_action", `Unknown action '${action}'. Valid actions: list_groups, activate, ` +
-            `deactivate, reset, suggest, activate_for.`);
+            `deactivate, reset, suggest, activate_for, invoke, editor_search.`);
+    }
+    /**
+     * `unity_open_mcp_upgrade` is a live tool, but its network lookups run HERE
+     * rather than inside the bridge: the bridge tool executes on the Editor main
+     * thread, where a 10 s registry timeout would freeze the Editor and every
+     * queued bridge request. The bridge only ever receives a resolved
+     * `target_version`, and an apply that will re-pin through UPM is forwarded
+     * only after the `bridge-v<version>` release tag was confirmed to exist —
+     * the same preview → confirm → apply order the bridge window follows.
+     */
+    async routeUpgrade(args, live) {
+        const forwarded = { ...args };
+        if (forwarded.target_version === undefined) {
+            try {
+                forwarded.target_version = (await releaseLookup.latest()).version;
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                return injectRouteMeta(localError("latest_version_failed", `Could not resolve the latest published version: ${detail}. Pass target_version explicitly.`), { route: "local" });
+            }
+        }
+        if (forwarded.dry_run === false && forwarded.update_upm !== false) {
+            // Preview first: only a plan that really re-pins through UPM needs the
+            // GitHub tag check (an embedded or file: bridge install skips UPM, so it
+            // must also work offline).
+            const preview = await live.route("unity_open_mcp_upgrade", { ...forwarded, dry_run: true });
+            const previewBody = parseResultBody(preview);
+            const mutation = previewBody?.mutation;
+            const output = (mutation && typeof mutation === "object" ? mutation.output : previewBody);
+            if (preview.isError || (output && typeof output === "object" && output.error !== undefined)) {
+                return injectRouteMeta(preview, { route: "live" });
+            }
+            if (output && typeof output === "object" && output.upmEnabled === true) {
+                const version = String(forwarded.target_version);
+                const tag = await releaseLookup.confirmBridgeTag(version);
+                if (!tag.confirmed) {
+                    return injectRouteMeta(localError("release_tag_unavailable", tag.error ?? `Release tag bridge-v${version} was not found.`), { route: "local" });
+                }
+            }
+        }
+        return injectRouteMeta(await live.route("unity_open_mcp_upgrade", forwarded), { route: "live" });
+    }
+    async routeProjectCommands(args, live) {
+        if (args.action === "invoke") {
+            const allowed = ["action", "command_id", "args", "schema_version", "paths_hint", "gate", "ignore_scene_dirty", "confirm_bypass", "timeout_ms"];
+            let identity = { id: args.command_id };
+            const fail = (code, message) => injectRouteMeta(sourceResult({ projectCommand: identity, error: { code, message } }, "local", true), { route: "local" });
+            if (!args.command_id || Object.keys(args).some(k => !allowed.includes(k)))
+                return fail("invalid_arguments", "invoke requires command_id and accepts command args plus transport safety options only.");
+            const catalog = await live.projectCommands({ action: "describe", id: args.command_id });
+            if (catalog.error)
+                return injectRouteMeta(sourceResult(catalog, "live", true), { route: "live" });
+            const command = catalog.command;
+            if (!command?.available || !command.invocationSupported || !command.inputSchema || !command.schemaVersion)
+                return fail("command_unavailable", "Command is unavailable or this bridge does not support invocation.");
+            identity = { id: command.id, schemaVersion: command.schemaVersion, declaringAssembly: command.declaringAssembly,
+                declaringType: command.declaringType, lifecycle: command.lifecycle };
+            if (args.schema_version !== undefined && args.schema_version !== command.schemaVersion)
+                return fail("command_schema_changed", "Describe the command again before invoking its changed contract.");
+            const errors = validateSchema(args.args ?? {}, command.inputSchema);
+            if (errors.length)
+                return fail("invalid_arguments", errors.join("; "));
+            // Deprecated parameter aliases are published like built-in aliases.
+            const notes = [];
+            const wire = wireArguments(args.args ?? {}, command.inputSchema, notes);
+            const result = await live.route("unity_open_mcp_project_commands", { ...args, args: wire, schema_version: command.schemaVersion }, command.lifecycle);
+            // Reload/transport failures have no bridge envelope; retain the exact catalog identity.
+            result.content = result.content.map(item => {
+                if (item.type !== "text")
+                    return item;
+                try {
+                    const body = JSON.parse(item.text);
+                    if (body && typeof body === "object" && !Array.isArray(body) && !body.projectCommand)
+                        return { ...item, text: JSON.stringify({ ...body, projectCommand: identity }) };
+                }
+                catch { /* Preserve non-JSON transport diagnostics. */ }
+                return item;
+            });
+            if (notes.length)
+                result.content.push({ type: "text", text: JSON.stringify({ deprecations: [...new Set(notes)] }) });
+            return injectRouteMeta(result, { route: "live" });
+        }
+        const allowed = args.action === "describe" ? ["action", "id"] : ["action", "query", "tags", "group", "package", "offset", "limit"];
+        if (Object.keys(args).some(k => !allowed.includes(k)) || (args.action === "describe" && !args.id))
+            return sourceResult({ error: { code: "invalid_arguments", message: "describe requires an exact id only; list accepts filters and paging only." } }, "local", true);
+        const body = await live.projectCommands(args);
+        return injectRouteMeta(sourceResult(body, "live", !!body.error), { route: "live" });
     }
     async manageToolsListGroups(live) {
         // M20 Plan 7 / T20.7.0 — fetch the compiled-state inventory once and
@@ -1388,6 +1800,7 @@ export class ToolRouter {
     // `availableReason`. Emits `notifications/tools/list_changed` exactly once
     // when the visible set changed (idempotent when already active).
     async manageToolsActivateFor(rec, live) {
+        const groupsBeforeInventory = new Set(this.sessionState.activeGroups());
         const inventory = await this.fetchInventoryAndReconcile(live);
         const compiledAvailability = this.computeCompiledAvailability(inventory, groupToTools());
         const before = this.sessionState.activeGroups();
@@ -1422,6 +1835,7 @@ export class ToolRouter {
             intent: rec,
             groups,
             activated,
+            tools: compactDiscoverySchema(discoverTools(ALL_TOOLS, BATCH_TOOL_NAMES, this.sessionState, inventory?.tools, { groups: this.sessionState.activeGroups().filter(g => !groupsBeforeInventory.has(g)), profile: "full", page_size: 1000 }, this.batch.headlessAvailable()).tools),
             skipped,
             unavailable,
             activeGroups: this.sessionState.activeGroups(),
@@ -1735,6 +2149,11 @@ export class ToolRouter {
         else {
             status = "stopped";
         }
+        // A "stopped" bridge while this server's own headless run holds the
+        // project: the process scan skips that child, so without this hint the
+        // generic nextStep would send the agent to launch Unity into the run's
+        // project lock.
+        const headlessRun = status === "stopped" ? activeHeadlessRun(this.projectPath) : null;
         const body = {
             status,
             // Coarse ready flag for clients that want a single boolean: true only
@@ -1784,7 +2203,12 @@ export class ToolRouter {
             // `stale: true` block is the signal to reinstall the Unity package
             // rather than file a regression.
             wireContract: wireContractBlock(pingReachable, pingBody?.wireContract),
-            nextStep: bridgeStatusNextStep(status, wedge),
+            ...(headlessRun !== null ? { headlessRun: describeHeadlessRun(headlessRun) } : {}),
+            nextStep: headlessRun !== null
+                ? headlessRunSentence(headlessRun) +
+                    " The bridge stays offline until then. Wait for the pending headless call to return; " +
+                    "do not launch Unity for this project meanwhile."
+                : bridgeStatusNextStep(status, wedge),
         };
         // bridge_status never reports an error — even a stopped bridge is a
         // successful status read. _source=local because the synthesis happens in
@@ -1916,6 +2340,16 @@ export class ToolRouter {
                 pid = null;
             }
         }
+        // No interactive Editor, but this server's own headless run holds the
+        // project: say so (both dry-run and confirmed) instead of the misleading
+        // "relaunch via the Hub" of unity_process_not_found. The scan never
+        // returns that child, so it is never a kill target.
+        if (pid === null) {
+            const headlessRun = activeHeadlessRun(this.projectPath);
+            if (headlessRun !== null) {
+                return headlessRunErrorResult("restart_editor", headlessRun, this.projectPath);
+            }
+        }
         // 3. Dry-run branch: confirm was false/absent. Return the diagnosis +
         //    the PID the tool WOULD kill, with no side effect. Lets an agent
         //    preview before committing. feedback #2: include the PID source and
@@ -2117,6 +2551,10 @@ export class ToolRouter {
             }
         }
         if (pid === null) {
+            const headlessRun = activeHeadlessRun(this.projectPath);
+            if (headlessRun !== null) {
+                return headlessRunErrorResult("resource_pressure", headlessRun, this.projectPath);
+            }
             return sourceResult({
                 error: {
                     code: "unity_process_not_found",