unity-open-mcp 0.1.0 → 0.3.0

package/dist/tool-router.js

@@ -1,16 +1,26 @@
 import { AssetModelCache, isCompressible, routeCompressible } from "./compressible-router.js";
-import { listAssetsOffline, findReferencesOffline } from "./offline.js";
+import { listAssetsOffline, findReferencesOffline, dependenciesOffline } from "./offline.js";
 import { editorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES } from "./unity-log.js";
 import { summarizeProjectHealth } from "./project-health.js";
 import { buildCapabilities } from "./capabilities/build-capabilities.js";
 import { RULE_CATALOG, FIX_CATALOG } from "./capabilities/rule-catalog.js";
-import { GROUP_IDS, TOOL_GROUPS, groupToTools, } from "./capabilities/tool-groups.js";
+import { GROUP_IDS, TOOL_GROUPS, AUTO_ACTIVATE_GROUPS, groupToTools, } from "./capabilities/tool-groups.js";
 import { listRules } from "./capabilities/list-rules.js";
 import { generateSkill } from "./skill/generate-skill.js";
 import { knownClientKeys } from "./skill/client-paths.js";
 import { ALL_TOOLS } from "./tools/index.js";
-import { lockPath, readInstanceLock, classifyInstance } from "./instance-discovery.js";
+import { lockPath, readInstanceLock, classifyInstance, isPidAlive } from "./instance-discovery.js";
+import { listInstalledEditors, fetchAvailableReleases, openInstallDeepLink, getInstallPath, setInstallPath, } from "./hub-control.js";
+/** Default Hub-control backend — calls the real hub-control functions. */
+const defaultHubBackend = {
+    listInstalledEditors: () => listInstalledEditors(),
+    fetchAvailableReleases: () => fetchAvailableReleases(),
+    openInstallDeepLink: (version, changeset) => openInstallDeepLink(version, changeset),
+    getInstallPath: () => getInstallPath(),
+    setInstallPath: (path) => setInstallPath(path),
+};
 import { BATCH_TOOL_NAMES } from "./batch-spawn.js";
+import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, } from "./output-profile.js";
 function injectRouteMeta(result, meta) {
     if (result.content.length === 0)
         return result;
@@ -35,6 +45,43 @@ function injectRouteMeta(result, meta) {
         return result;
     }
 }
+// M26 Plan 2 — local-routed error result (used by the Hub control tools for
+// missing-parameter refusals before any side effect runs). Tagged _source=local
+// because it is resolved entirely in the MCP server.
+function localError(code, message) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify({ error: { code, message }, _source: "local" }) },
+        ],
+        isError: true,
+    };
+}
+// 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
+// gate is skipped (gate.skipped=true). The shape matches MutationEnvelope so
+// agents parse it uniformly alongside bridge-routed mutating tools.
+function hubMutationEnvelope(opts) {
+    const body = {
+        mutation: {
+            success: opts.success,
+            output: opts.output,
+            error: opts.error,
+        },
+        gate: {
+            mode: "off",
+            skipped: true,
+            validation: null,
+            delta: null,
+        },
+        agentNextSteps: opts.nextSteps,
+        _source: "local",
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(body) }],
+        isError: opts.isError,
+    };
+}
 function activeGroupsEqual(a, b) {
     if (a.length !== b.length)
         return false;
@@ -77,6 +124,66 @@ function summarizeBridgeStatusLock(lock) {
         unityVersion: lock.unityVersion,
     };
 }
+// ===========================================================================
+// M22 — heavy-tool result post-processors (find_references + verify tools).
+//
+// These run after the live/batch/offline hop returns. The bridge emits the full
+// result regardless of profile; we fold + page server-side so the wire shape
+// matches the profile/paging contract without a bridge change. Each returns a
+// new CallToolResult (never mutates the input); injectRouteMeta runs after to
+// append `_route`.
+// ===========================================================================
+/** Page the offline find_references `referencedBy` list and attach pagination. */
+function pageFindReferencesResult(result, pageSize, cursor) {
+    const referencedBy = Array.isArray(result.referencedBy) ? result.referencedBy : [];
+    const { page, block } = applyPaging(referencedBy, "find_references", { page_size: pageSize, cursor });
+    return attachPagination({ ...result, referencedBy: page }, block);
+}
+/**
+ * Fold + page the LIVE find_references result. The bridge returns a flat
+ * `referencedBy` path list (no byKind/byFolder groupings, no locations); we
+ * derive the compact grouping server-side and page when requested.
+ */
+function foldFindReferencesLive(result, profile, wantPaging, args) {
+    const body = parseResultBody(result);
+    if (body === null)
+        return result;
+    if (body.error)
+        return result;
+    // Bridge shape: { referencedBy: string[], totalCount, ... } (flat paths).
+    const rawList = Array.isArray(body.referencedBy) ? body.referencedBy : [];
+    const pageSize = typeof args.page_size === "number" && args.page_size > 0 ? args.page_size : 0;
+    const cursor = typeof args.cursor === "string" ? args.cursor : undefined;
+    if (profile === "compact") {
+        // compact: counts + byKind grouping only — drop the per-asset list.
+        const { referencedBy: _dropped, ...rest } = body;
+        void _dropped;
+        const byKind = groupLiveRefsByKind(rawList);
+        return withResultBody(result, {
+            ...rest,
+            totalCount: rawList.length,
+            byKind,
+            referencedBy: [],
+        });
+    }
+    // balanced / full: keep the path list (paged when requested).
+    if (pageSize > 0) {
+        const { page, block } = applyPaging(rawList, "find_references", { page_size: pageSize, cursor });
+        const withPage = attachPagination({ ...body, referencedBy: page, totalCount: rawList.length }, block);
+        return withResultBody(result, withPage);
+    }
+    return withResultBody(result, { ...body, totalCount: rawList.length });
+}
+/** Derive a byKind grouping from flat referenced paths for the live compact view. */
+function groupLiveRefsByKind(paths) {
+    const counts = {};
+    for (const path of paths) {
+        const dot = path.lastIndexOf(".");
+        const kind = dot > 0 ? path.slice(dot + 1).toLowerCase() : "other";
+        counts[kind] = (counts[kind] ?? 0) + 1;
+    }
+    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.
 function bridgeStatusNextStep(status) {
@@ -87,10 +194,41 @@ function bridgeStatusNextStep(status) {
             return "Unity is compiling. Wait for the bridge to return to idle, or poll unity_open_mcp_bridge_status again.";
         case "stopped":
             return "Bridge listener is not reachable. Open the bridge window (Unity menu: Tools/Unity Open MCP Bridge) and ensure it is started, or launch Unity if it is not running, then call unity_open_mcp_bridge_status again to confirm.";
+        case "unreachable":
+            // M20 Plan 4-5 / T-fix-3 — distinct from "stopped": the Unity process is
+            // alive (lock PID live) but the listener did not respond. Usually a
+            // transient domain-reload window (the bridge tears down its HTTP socket
+            // for the reload duration) — retry shortly rather than treating it as a
+            // clean stop. This makes the reload-window flakiness visible instead of
+            // being masked by a clean-looking "stopped".
+            return "Bridge listener is not responding but Unity is running — likely a transient domain-reload window (the bridge tears down its HTTP socket during compiles). Wait a moment and call unity_open_mcp_bridge_status again; if it persists, call unity_open_mcp_read_compile_errors to check for a failed recompile.";
         case "dead_bridge":
-            return "The bridge assembly failed to recompile and Unity is in a bad state. Call unity_open_mcp_read_compile_errors to retrieve the compiler errors from Editor.log, fix the cited file/line, then trigger a recompile.";
+            // M23 Plan 2 — safe-mode surfacing (feedback 2026-06-29). A dead_bridge
+            // signature (live PID + stale heartbeat) almost always means Unity is
+            // sitting in Safe Mode / showing compile errors; the generic "open the
+            // bridge window" hint was misleading. Name safe mode explicitly and
+            // point at the one channel that works in that state.
+            return "Unity is likely in Safe Mode or showing compile errors — the bridge " +
+                "assembly failed to recompile, so the HTTP listener will not return on its " +
+                "own. Call unity_open_mcp_read_compile_errors to retrieve the compiler " +
+                "errors from Editor.log, fix the cited file/line, then trigger a recompile " +
+                "(e.g. a no-op edit + focus Unity, or unity_open_mcp_compile_check once the " +
+                "source compiles). If Unity is NOT in safe mode, the bridge toolbar toggle " +
+                "may be off — open the bridge window (Unity menu: Tools/Unity Open MCP " +
+                "Bridge) and confirm it is started.";
     }
 }
+function bridgeStatusRecoveryHint(status) {
+    if (status === "dead_bridge") {
+        return {
+            tool: "unity_open_mcp_read_compile_errors",
+            reason: "Unity is likely in Safe Mode / compile failure — read_compile_errors " +
+                "reads Editor.log offline (the only channel that works with the bridge " +
+                "assembly dead).",
+        };
+    }
+    return null;
+}
 export class ToolRouter {
     live;
     batch;
@@ -98,16 +236,36 @@ export class ToolRouter {
     eventStream;
     sessionState;
     onToolListChanged;
+    hubBackend;
     modelCache = new AssetModelCache();
-    constructor(live, batch, projectPath, eventStream, sessionState, onToolListChanged) {
+    constructor(live, batch, projectPath, eventStream, sessionState, onToolListChanged, 
+    // M26 Plan 2 — injectable Hub-control backend. Omit in production (the
+    // default calls the real hub-control functions); tests pass a fake to
+    // avoid real subprocess + network side effects.
+    hubBackend = defaultHubBackend) {
         this.live = live;
         this.batch = batch;
         this.projectPath = projectPath;
         this.eventStream = eventStream;
         this.sessionState = sessionState;
         this.onToolListChanged = onToolListChanged;
+        this.hubBackend = hubBackend;
     }
     async route(toolName, args) {
+        return this.routeCore(this.live, toolName, args);
+    }
+    /**
+     * 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}).
+     */
+    async routeOverride(toolName, args, overrideLive) {
+        return this.routeCore(overrideLive, toolName, args);
+    }
+    async routeCore(live, toolName, args) {
         // list_assets — always offline (no live equivalent needed).
         if (toolName === "unity_open_mcp_list_assets") {
             return this.routeListAssets(args);
@@ -125,11 +283,11 @@ export class ToolRouter {
         // bridge is reachable; an unreachable bridge returns a clear error instead
         // of hanging on connect.
         if (toolName === "unity_senses_pull_events") {
-            return this.routePullEvents(args);
+            return this.routePullEvents(args, live);
         }
         // capabilities — local capability-discovery surface (no live/batch hop).
         if (toolName === "unity_open_mcp_capabilities") {
-            return this.routeCapabilities(args);
+            return this.routeCapabilities(args, live);
         }
         // list_rules — local rule catalog (no live/batch hop). Lets an agent
         // discover which rules apply to which asset kinds before calling
@@ -148,7 +306,7 @@ export class ToolRouter {
         // server applies the activate / deactivate filter to ListTools. Always
         // visible regardless of the current active set (meta-tool).
         if (toolName === "unity_open_mcp_manage_tools") {
-            return this.routeManageTools(args);
+            return this.routeManageTools(args, live);
         }
         // testsuite-tauri phase-3 — bridge_status. Operator-only health snapshot.
         // Server-resolved (classifyInstance + one /ping via the LiveClient); never
@@ -156,18 +314,59 @@ export class ToolRouter {
         // `status` token (running/compiling/stopped/dead_bridge) the Validation
         // Suite app drives its offline-scenario gate off. Read-only, gate-free.
         if (toolName === "unity_open_mcp_bridge_status") {
-            return this.routeBridgeStatus(args);
+            return this.routeBridgeStatus(args, live);
+        }
+        // M26 Plan 2 — Unity Hub control tools. Local-routed: resolved inside the
+        // MCP server (filesystem discovery + Unity archive feed + unityhub:// deep
+        // link + Hub CLI). Never hit the bridge tool endpoint, never spawn Unity.
+        // Mutating members are system-level ops (paths_hint N/A, gate-free).
+        if (toolName === "unity_open_mcp_hub_list_editors") {
+            return this.routeHubListEditors();
+        }
+        if (toolName === "unity_open_mcp_hub_available_releases") {
+            return this.routeHubAvailableReleases();
+        }
+        if (toolName === "unity_open_mcp_hub_install_editor") {
+            return this.routeHubInstallEditor(args);
+        }
+        if (toolName === "unity_open_mcp_hub_install_modules") {
+            return this.routeHubInstallModules(args);
+        }
+        if (toolName === "unity_open_mcp_hub_get_install_path") {
+            return this.routeHubGetInstallPath();
+        }
+        if (toolName === "unity_open_mcp_hub_set_install_path") {
+            return this.routeHubSetInstallPath(args);
         }
         // find_references — offline-first when no bridge is connected; live
         // ReferenceGraph remains available when the bridge is up.
         if (toolName === "unity_open_mcp_find_references") {
-            return this.routeFindReferences(args);
+            return this.routeFindReferences(args, live);
+        }
+        // dependencies — offline-first (M24 Plan 2 / T24.2). Forward + reverse
+        // edges + impact analysis all compute from YAML on disk when no bridge is
+        // connected; the live DependenciesTool remains available when the bridge
+        // is up. The offline path is the only one that exposes include_impact
+        // (transitive reverse closure) today.
+        if (toolName === "unity_open_mcp_dependencies") {
+            return this.routeDependencies(args, live);
+        }
+        // M22 — verify tools. The bridge returns the full issues[] list; we fold +
+        // page server-side per the output profile (compact = counts only).
+        if (toolName === "unity_open_mcp_validate_edit" || toolName === "unity_open_mcp_scan_paths") {
+            return this.routeVerifyResult(toolName, args, live);
+        }
+        // M22 — scene_get_data. Resolves the output profile (onto detail) and pages
+        // the node stream server-side; the bridge detail/max_nodes params keep
+        // working as back-compat aliases.
+        if (toolName === "unity_open_mcp_scene_get_data") {
+            return this.routeSceneGetData(args, live);
         }
         // Compact drill-down reads: offline-first for text-serialized assets, fall
         // back to live bridge for binary formats. The compressible-router handles
         // the source selection internally.
         if (isCompressible(toolName)) {
-            const result = await routeCompressible(toolName, args, this.live, this.modelCache, this.projectPath);
+            const result = await routeCompressible(toolName, args, live, this.modelCache, this.projectPath);
             return injectRouteMeta(result, { route: "live" });
         }
         const canBatch = this.batch.isBatchTool(toolName);
@@ -186,13 +385,13 @@ export class ToolRouter {
             });
         }
         if (!canBatch && !isPing) {
-            const result = await this.live.route(toolName, args);
+            const result = await live.route(toolName, args);
             return injectRouteMeta(result, { route: "live" });
         }
-        const liveAvailable = await this.live.isLiveAvailable();
+        const liveAvailable = await live.isLiveAvailable();
         if (liveAvailable) {
             console.error(`[unity-open-mcp] Route: ${toolName} -> live`);
-            const result = await this.live.route(toolName, args);
+            const result = await live.route(toolName, args);
             return injectRouteMeta(result, { route: "live" });
         }
         console.error(`[unity-open-mcp] Route: ${toolName} -> batch (live bridge unavailable)`);
@@ -334,8 +533,8 @@ export class ToolRouter {
     // (a fresh subscriber id is minted per process), so a restarted MCP server
     // begins "now" — agents that care about historical logs should still call
     // unity_senses_read_console.
-    async routePullEvents(args) {
-        const liveAvailable = await this.live.isLiveAvailable();
+    async routePullEvents(args, live) {
+        const liveAvailable = await live.isLiveAvailable();
         if (!liveAvailable) {
             return {
                 content: [
@@ -365,7 +564,7 @@ export class ToolRouter {
             isError: false,
         };
     }
-    async routeCapabilities(args) {
+    async routeCapabilities(args, live) {
         const kind = args.kind === "tools" || args.kind === "rules" || args.kind === "fixes"
             ? args.kind
             : undefined;
@@ -376,12 +575,18 @@ export class ToolRouter {
         // Capabilities stays local-route; the bridge probe is a read-only fetch
         // that does not change the route classification.
         let availableBridgeTools;
-        const liveAvailable = await this.live.isLiveAvailable();
+        const liveAvailable = await live.isLiveAvailable();
         if (liveAvailable) {
-            const inventory = await this.live.listBridgeTools();
+            const inventory = await live.listBridgeTools();
             if (inventory)
                 availableBridgeTools = inventory.tools;
         }
+        // M20 Plan 7 / T20.7.0 — reconcile auto-activation before reporting the
+        // group catalog so the capability output reflects packages that came
+        // online since the last call. Auto-activated groups surface with
+        // `autoActivated: true` + `packageDependency` (see build-capabilities).
+        // Reuse the inventory already fetched above (no second GET /tools hop).
+        await this.reconcileAutoActivation(availableBridgeTools ? { tools: availableBridgeTools } : null);
         const result = buildCapabilities({
             tools: ALL_TOOLS,
             batchToolNames: BATCH_TOOL_NAMES,
@@ -459,8 +664,8 @@ export class ToolRouter {
     // M18 Plan 2 / T18.2.2 — manage_tools routes local. Mutates the per-
     // session tool-group visibility state (ToolSessionState) that ListTools
     // consults to filter tools. The bridge does not see these calls — it is
-    // session-state the MCP server owns (matches the Coplay model and the
-    // resolved decision in M18 execution-plan.md).
+    // session-state the MCP server owns (the resolved decision in M18
+    // execution-plan.md).
     //
     // Compiled-state availability (whether the bridge compiled the domain in)
     // is reported in the `available` + `availableReason` fields per group. The
@@ -468,11 +673,11 @@ 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) {
+    async routeManageTools(args, live) {
         const action = typeof args.action === "string" ? args.action : "";
         const group = typeof args.group === "string" ? args.group.trim() : "";
         if (action === "list_groups") {
-            return this.manageToolsListGroups();
+            return this.manageToolsListGroups(live);
         }
         if (action === "reset") {
             const before = this.sessionState.activeGroups();
@@ -516,9 +721,20 @@ export class ToolRouter {
         }
         return this.manageToolsError("unknown_action", `Unknown action '${action}'. Valid actions: list_groups, activate, deactivate, reset.`);
     }
-    async manageToolsListGroups() {
+    async manageToolsListGroups(live) {
+        // M20 Plan 7 / T20.7.0 — fetch the compiled-state inventory once and
+        // reuse it for both auto-activation reconciliation and compiled-state
+        // availability (two GET /tools hops → one). When the bridge is offline
+        // both paths degrade gracefully (no auto-activation; availability=null).
+        const liveAvailable = await live.isLiveAvailable();
+        const inventory = liveAvailable
+            ? await live.listBridgeTools()
+            : null;
+        // Reconcile auto-activation first so the listed active set reflects
+        // packages that came online since the last call.
+        await this.reconcileAutoActivation(inventory ? { tools: inventory.tools } : null);
         const groupsList = groupToTools();
-        const compiledAvailability = await this.resolveCompiledAvailability();
+        const compiledAvailability = this.computeCompiledAvailability(inventory, groupsList);
         const groups = TOOL_GROUPS.map((g) => {
             const tools = groupsList[g.id] ?? [];
             const availability = compiledAvailability.get(g.id);
@@ -526,6 +742,12 @@ export class ToolRouter {
                 id: g.id,
                 description: g.description,
                 active: this.sessionState.isGroupActive(g.id),
+                // M20 Plan 7 / T20.7.0 — why the group is active (default / manual /
+                // auto). `null` when the group is not active. Lets an agent learn
+                // that a group is visible because its package is installed, not
+                // because the operator opted in.
+                activationSource: this.sessionState.activationSource(g.id),
+                autoActivated: this.sessionState.activationSource(g.id) === "auto",
                 defaultEnabled: g.defaultEnabled,
                 // Compiled-state availability of the domain dependency. `true` for
                 // groups without a domainDefine (always compiled in); `false` /
@@ -536,6 +758,7 @@ export class ToolRouter {
                 available: availability?.available ?? null,
                 availableReason: availability?.reason ?? null,
                 unityPackage: g.unityPackage ?? null,
+                packageDependency: g.unityPackage ?? null,
                 toolCount: tools.length,
                 tools,
             };
@@ -573,16 +796,69 @@ export class ToolRouter {
             return;
         await this.onToolListChanged();
     }
+    // M20 Plan 7 / T20.7.0 — reconcile the auto-activated set against the
+    // currently-compiled-in bridge inventory. A group with `autoActivate: true`
+    // is considered package-present when any of its compiled-in tool names
+    // appears in the bridge's `GET /tools` inventory — the same signal
+    // `resolveCompiledAvailability` uses, so no extra package_list round-trip.
+    // The session store records the outcome; we fire the listChanged
+    // notification exactly once when the active set changed. Returns true when
+    // the active set changed (so callers like capabilities / list_groups can
+    // report a fresh snapshot).
+    //
+    // Callers that have ALREADY fetched the bridge inventory (capabilities,
+    // list_groups) pass it via `prefetchedInventory` to avoid a second
+    // `GET /tools` round-trip on the same call.
+    async reconcileAutoActivation(prefetchedInventory) {
+        if (AUTO_ACTIVATE_GROUPS.length === 0)
+            return false;
+        let inventory = prefetchedInventory ?? null;
+        if (!inventory) {
+            const liveAvailable = await this.live.isLiveAvailable();
+            if (!liveAvailable)
+                return false;
+            inventory = await this.live.listBridgeTools();
+            if (!inventory)
+                return false;
+        }
+        const groupsList = groupToTools();
+        const satisfied = new Set();
+        for (const entry of AUTO_ACTIVATE_GROUPS) {
+            const groupTools = groupsList[entry.groupId] ?? [];
+            const anyCompiledIn = groupTools.length > 0 &&
+                groupTools.some((t) => inventory.tools.has(t));
+            if (anyCompiledIn)
+                satisfied.add(entry.groupId);
+        }
+        const before = this.sessionState.activeGroups();
+        const changed = this.sessionState.reconcileAutoActivation(satisfied);
+        if (changed.length > 0) {
+            await this.maybeNotifyToolListChanged(before);
+            return true;
+        }
+        return false;
+    }
     // Resolve compiled-state availability per group from the live bridge. The
     // bridge reports which tools it compiled in via `GET /tools`; a domain-
     // gated group is `available: true` when any of its compiled-in tool names
     // appears in that set, `false` when none do (Unity domain package not
     // installed), and `null` (unknown) when the bridge is offline.
+    //
+    // Thin async wrapper over {@link computeCompiledAvailability}: fetches the
+    // inventory (or null when the bridge is offline) and delegates. Kept for
+    // the few call sites that don't already have an inventory in hand.
     async resolveCompiledAvailability() {
-        const out = new Map();
         const liveAvailable = await this.live.isLiveAvailable();
-        const inventory = liveAvailable ? await this.live.listBridgeTools() : null;
-        const groupsList = groupToTools();
+        const inventory = liveAvailable
+            ? await this.live.listBridgeTools()
+            : null;
+        return this.computeCompiledAvailability(inventory, groupToTools());
+    }
+    // Pure per-group availability computation given a (possibly null) bridge
+    // tool inventory. Extracted so callers that already fetched the inventory
+    // (capabilities, list_groups) can avoid a second GET /tools hop.
+    computeCompiledAvailability(inventory, groupsList) {
+        const out = new Map();
         for (const g of TOOL_GROUPS) {
             if (!g.domainDefine) {
                 out.set(g.id, { available: true, reason: null });
@@ -640,6 +916,7 @@ export class ToolRouter {
     //   lock="dead_bridge"                       → "dead_bridge"
     //   /ping reachable, compiling=true          → "compiling"
     //   /ping reachable, connected=true          → "running"
+    //   /ping UNreachable + Unity running        → "unreachable" (T-fix-3)
     //   otherwise (offline / toolbar off / gone) → "stopped"
     //
     // "stopped" intentionally folds two indistinguishable cases from the
@@ -648,7 +925,15 @@ export class ToolRouter {
     // lock summary in the response disambiguates them (`lock === null` → no
     // Unity; `lock.pid` alive but no listener → toolbar off). The tool never
     // errors on an offline bridge — `stopped` IS the answer in that case.
-    async routeBridgeStatus(_args) {
+    //
+    // M20 Plan 4-5 / T-fix-3 — "unreachable" splits out the case where Unity IS
+    // running (lock PID alive, often mid-reload) but the listener did not
+    // respond. Pre-fix this collapsed to "stopped", hiding transient reload-
+    // window flakiness behind a clean-looking status. "unreachable" makes it
+    // visible so agents retry instead of treating it as a clean stop. The
+    // `isError:false` contract is preserved — this is richer status, not an
+    // error path.
+    async routeBridgeStatus(_args, live) {
         const lockOnDisk = lockPath(this.projectPath);
         let lock = null;
         try {
@@ -664,11 +949,17 @@ export class ToolRouter {
         // — both shapes are valid inputs here. A compile-in-progress bridge
         // returns HTTP 503 from /ping which isLiveAvailable() treats as reachable;
         // the ping body's `compiling` field is the authoritative signal.
-        const pingResult = await this.live.route("unity_open_mcp_ping", {});
+        const pingResult = await live.route("unity_open_mcp_ping", {});
         const pingBody = parsePingBody(pingResult);
         const pingReachable = !pingResult.isError && pingBody !== null;
         const compiling = pingReachable === true && pingBody?.compiling === true;
         const connected = pingReachable === true && pingBody?.connected === true;
+        // T-fix-3 — when the ping is unreachable, distinguish "Unity is running but
+        // the listener is momentarily down" (lock PID alive / reload window) from a
+        // genuine "nothing there" stop. classification "reloading" covers the
+        // domain-reload window; a live-PID "healthy"/"gone"-with-alive-pid lock
+        // also indicates Unity is up.
+        const lockPidAlive = lock !== null && isPidAlive(lock.pid);
         let status;
         if (classification === "dead_bridge") {
             status = "dead_bridge";
@@ -679,6 +970,12 @@ export class ToolRouter {
         else if (connected) {
             status = "running";
         }
+        else if (!pingReachable && (classification === "reloading" || lockPidAlive)) {
+            // Unity is running but the listener didn't respond — transient (reload
+            // window) or toolbar-off. Surface as unreachable so it isn't masked by
+            // a clean "stopped".
+            status = "unreachable";
+        }
         else {
             status = "stopped";
         }
@@ -689,6 +986,17 @@ export class ToolRouter {
             // uses for poll termination).
             ready: status === "running",
             projectPath: this.projectPath,
+            // M23 Plan 2 — top-level mirror of the instance-lock classification
+            // (healthy | reloading | dead_bridge | gone) + a structured recovery
+            // hint. Mirrors `instance.classification` at the top level so agents
+            // can branch on a single field without digging into the instance
+            // sub-object; `recoveryHint` is null unless the status has a specific
+            // recovery tool to call (today: dead_bridge → read_compile_errors).
+            // Feedback 2026-06-29: a dead_bridge must read as "Unity likely in
+            // Safe Mode / compile failure", not the generic "stopped" the bare
+            // status used to suggest.
+            classification,
+            recoveryHint: bridgeStatusRecoveryHint(status),
             instance: {
                 lockPath: lockOnDisk,
                 classification,
@@ -716,12 +1024,146 @@ export class ToolRouter {
             isError: false,
         };
     }
-    async routeFindReferences(args) {
-        const liveAvailable = await this.live.isLiveAvailable();
+    // ── M26 Plan 2 — Unity Hub control (local-routed) ────────────────
+    //
+    // Each of these resolves entirely inside the MCP server (no bridge tool
+    // endpoint, no batch Unity) → every response is tagged `_source: "local"`.
+    // Read-only members are plain JSON bodies; mutating members return the
+    // gate-consistent mutation/gate/agentNextSteps envelope shape so agents
+    // parse them uniformly, with gate.skipped=true because these are system-
+    // level ops where the project-asset gate does not apply (paths_hint N/A).
+    async routeHubListEditors() {
+        const editors = this.hubBackend.listInstalledEditors();
+        const body = {
+            editors,
+            count: editors.length,
+            _source: "local",
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(body) }],
+            isError: false,
+        };
+    }
+    async routeHubAvailableReleases() {
+        const result = await this.hubBackend.fetchAvailableReleases();
+        const body = {
+            entries: result.entries,
+            count: result.entries.length,
+            stale: result.stale,
+            fetchedAt: result.fetchedAt,
+            _source: "local",
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(body) }],
+            isError: false,
+        };
+    }
+    async routeHubInstallEditor(args) {
+        const version = typeof args.version === "string" ? args.version : "";
+        const changeset = typeof args.changeset === "string" ? args.changeset : undefined;
+        if (!version.trim()) {
+            return localError("missing_parameter", "version is required.");
+        }
+        const res = this.hubBackend.openInstallDeepLink(version, changeset);
+        return hubMutationEnvelope({
+            success: res.opened,
+            output: { deepLink: res.deepLink, version, changeset: changeset ?? null },
+            error: res.error,
+            nextSteps: res.opened
+                ? [
+                    "Unity Hub opened at the install dialog for " +
+                        version +
+                        ". The download runs inside the Hub (watch its progress UI).",
+                    "There is no in-call completion detection — poll " +
+                        "unity_open_mcp_hub_list_editors after the Hub finishes to confirm the new editor.",
+                ]
+                : [
+                    "Ensure Unity Hub is installed and registered as the unityhub:// handler, then retry.",
+                    "Fallback: open the release-notes URL from hub_available_releases in a browser and install manually.",
+                ],
+            isError: !res.opened,
+        });
+    }
+    async routeHubInstallModules(args) {
+        const version = typeof args.version === "string" ? args.version : "";
+        const changeset = typeof args.changeset === "string" ? args.changeset : undefined;
+        const modules = Array.isArray(args.modules)
+            ? args.modules.filter((m) => typeof m === "string")
+            : [];
+        if (!version.trim()) {
+            return localError("missing_parameter", "version is required.");
+        }
+        const res = this.hubBackend.openInstallDeepLink(version, changeset);
+        return hubMutationEnvelope({
+            success: res.opened,
+            output: {
+                deepLink: res.deepLink,
+                version,
+                changeset: changeset ?? null,
+                modulesRequested: modules,
+                note: "The unityhub:// scheme does not expose a module-specific deep link; the Hub opens at the version's install dialog where the operator selects the modules.",
+            },
+            error: res.error,
+            nextSteps: res.opened
+                ? [
+                    `Unity Hub opened at the install dialog for ${version}. Select the requested modules (${modules.join(", ") || "none specified"}) in the Hub UI.`,
+                    "Poll unity_open_mcp_hub_list_editors (which scans Data/PlaybackEngines) afterwards to confirm the new modules.",
+                ]
+                : [
+                    "Ensure Unity Hub is installed and registered as the unityhub:// handler, then retry.",
+                ],
+            isError: !res.opened,
+        });
+    }
+    async routeHubGetInstallPath() {
+        const res = this.hubBackend.getInstallPath();
+        const body = {
+            path: res.path,
+            source: res.source,
+            error: res.error,
+            _source: "local",
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(body) }],
+            isError: res.error !== null,
+        };
+    }
+    async routeHubSetInstallPath(args) {
+        const path = typeof args.path === "string" ? args.path : "";
+        if (!path.trim()) {
+            return localError("missing_parameter", "path is required.");
+        }
+        const res = this.hubBackend.setInstallPath(path);
+        return hubMutationEnvelope({
+            success: res.success,
+            output: { path, hubCliOutput: res.output },
+            error: res.error,
+            nextSteps: res.success
+                ? [`Default Unity Editor install path set to ${path}.`]
+                : [
+                    "Set the UNITY_HUB_PATH env var to the Unity Hub binary if the CLI was not found, then retry.",
+                ],
+            isError: !res.success,
+        });
+    }
+    async routeFindReferences(args, live) {
+        // M22 — resolve profile -> detail. compact (default) maps to summary
+        // (counts/byKind/byFolder only); balanced -> normal; full -> verbose.
+        const { detail, profile } = readProfileAndDetail(args, "summary");
+        const wantPaging = typeof args.page_size === "number" && args.page_size > 0;
+        const liveAvailable = await live.isLiveAvailable();
         if (liveAvailable) {
             console.error("[unity-open-mcp] Route: find_references -> live");
-            const result = await this.live.route("unity_open_mcp_find_references", args);
-            return injectRouteMeta(result, { route: "live" });
+            // The live bridge only honors max_results (no detail/per-file/threshold).
+            // Ask for the full set when paging so the cursor can walk it; otherwise
+            // honor the legacy max_results cap.
+            const liveArgs = {
+                ...args,
+                max_results: wantPaging ? 0 : (typeof args.max_results === "number" ? args.max_results : 100),
+            };
+            const result = await live.route("unity_open_mcp_find_references", liveArgs);
+            const folded = foldFindReferencesLive(result, profile, wantPaging, args);
+            return injectRouteMeta(folded, { route: "live" });
         }
         console.error("[unity-open-mcp] Route: find_references -> offline (live bridge unavailable)");
         const assetPath = typeof args.asset_path === "string" ? args.asset_path : undefined;
@@ -746,16 +1188,98 @@ export class ToolRouter {
             const result = await findReferencesOffline({
                 assetPath,
                 guid,
-                detail: typeof args.detail === "string" ? args.detail : "normal",
-                maxResults: typeof args.max_results === "number" ? args.max_results : 100,
+                detail,
+                // When paging, fetch the full set; otherwise honor the legacy cap.
+                maxResults: wantPaging ? 0 : (typeof args.max_results === "number" ? args.max_results : 100),
                 maxPerFile: typeof args.max_per_file === "number" ? args.max_per_file : 5,
                 patternThreshold: typeof args.pattern_threshold === "number" ? args.pattern_threshold : 0,
                 projectRoot: this.projectPath,
             });
+            // M22 — page the referencedBy list when requested (balanced/full only;
+            // compact returns an empty list by design).
+            const withPaging = wantPaging
+                ? pageFindReferencesResult(result, args.page_size, typeof args.cursor === "string" ? args.cursor : undefined)
+                : result;
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...withPaging, _source: "offline" }) },
+                ],
+                isError: false,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: { code: "offline_error", message },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    // M24 Plan 2 / T24.2 — dependencies (forward + reverse edges + impact
+    // analysis). Offline-first when no bridge is connected; the live
+    // DependenciesTool is the fallback when the bridge is up. The live tool does
+    // not yet honor include_impact / max_impact_depth — those are offline-only
+    // today, so when the bridge is up and impact is requested we route offline
+    // regardless (the offline path is the only one with the transitive closure).
+    async routeDependencies(args, live) {
+        const { detail } = readProfileAndDetail(args, "normal");
+        const assetPath = typeof args.asset_path === "string" ? args.asset_path : undefined;
+        const guid = typeof args.guid === "string" ? args.guid : undefined;
+        const includeImpact = args.include_impact === true;
+        if (!assetPath && !guid) {
             return {
                 content: [
-                    { type: "text", text: JSON.stringify({ ...result, _source: "offline" }) },
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: {
+                                code: "missing_parameter",
+                                message: "Either 'asset_path' or 'guid' is required.",
+                            },
+                        }),
+                    },
                 ],
+                isError: true,
+            };
+        }
+        const liveAvailable = await live.isLiveAvailable();
+        // Impact analysis is offline-only. When requested, go straight to the
+        // offline path even if the bridge is up — the live DependenciesTool has no
+        // transitive-closure surface yet.
+        if (!includeImpact && liveAvailable) {
+            console.error("[unity-open-mcp] Route: dependencies -> live");
+            // The live tool honors asset_path/guid/detail/max_results only.
+            const liveArgs = {
+                asset_path: assetPath,
+                guid,
+                detail,
+                max_results: typeof args.max_results === "number" ? args.max_results : 100,
+            };
+            const result = await live.route("unity_open_mcp_dependencies", liveArgs);
+            return injectRouteMeta(result, { route: "live" });
+        }
+        console.error(includeImpact && liveAvailable
+            ? "[unity-open-mcp] Route: dependencies -> offline (include_impact is offline-only)"
+            : "[unity-open-mcp] Route: dependencies -> offline (live bridge unavailable)");
+        try {
+            const result = await dependenciesOffline({
+                assetPath,
+                guid,
+                detail,
+                maxResults: typeof args.max_results === "number" ? args.max_results : 100,
+                includeImpact,
+                maxImpactDepth: typeof args.max_impact_depth === "number" ? args.max_impact_depth : 5,
+                projectRoot: this.projectPath,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
                 isError: false,
             };
         }
@@ -774,5 +1298,134 @@ export class ToolRouter {
             };
         }
     }
+    // M22 — verify tools (validate_edit / scan_paths). The bridge always returns
+    // the full issues[] list; we fold + page server-side per the output profile
+    // (compact = counts only, balanced/full keep + page issues).
+    async routeVerifyResult(toolName, args, live) {
+        const { profile } = readProfileAndDetail(args, "summary");
+        const pageSize = typeof args.page_size === "number" && args.page_size > 0 ? args.page_size : 0;
+        const cursor = typeof args.cursor === "string" ? args.cursor : undefined;
+        // Forward to live/batch exactly as the generic path would. The bridge
+        // ignores the unknown profile/page_size/cursor keys (JsonBody substring-
+        // searches only for keys it asks for), so they pass through harmlessly.
+        const canBatch = this.batch.isBatchTool(toolName);
+        let raw;
+        if (!canBatch) {
+            raw = await live.route(toolName, args);
+            raw = injectRouteMeta(raw, { route: "live" });
+        }
+        else {
+            const liveAvailable = await live.isLiveAvailable();
+            if (liveAvailable) {
+                raw = await live.route(toolName, args);
+                raw = injectRouteMeta(raw, { route: "live" });
+            }
+            else {
+                raw = await this.batch.route(toolName, args);
+                raw = injectRouteMeta(raw, { route: "batch", fallbackReason: "live_unavailable" });
+            }
+        }
+        const body = parseResultBody(raw);
+        if (body === null)
+            return raw;
+        if (body.error)
+            return raw;
+        const folded = foldVerifyResult(body, toolName, profile, { page_size: pageSize, cursor });
+        return withResultBody(raw, folded);
+    }
+    // M22 — scene_get_data. Resolves the output profile (onto detail) and pages
+    // the node stream server-side. The bridge detail/max_nodes params keep
+    // working as back-compat aliases; profile wins when both are present.
+    async routeSceneGetData(args, live) {
+        const { detail } = readProfileAndDetail(args, "summary");
+        const wantPaging = typeof args.page_size === "number" && args.page_size > 0;
+        // Build the args the bridge sees: profile resolved to detail (the bridge's
+        // real knob), legacy max_nodes honored, paging keys stripped (the bridge
+        // would ignore them anyway, but keep the call clean).
+        const bridgeArgs = { ...args };
+        delete bridgeArgs.profile;
+        delete bridgeArgs.page_size;
+        delete bridgeArgs.cursor;
+        bridgeArgs.detail = detail;
+        const canBatch = this.batch.isBatchTool("unity_open_mcp_scene_get_data");
+        let raw;
+        if (!canBatch) {
+            raw = await live.route("unity_open_mcp_scene_get_data", bridgeArgs);
+            raw = injectRouteMeta(raw, { route: "live" });
+        }
+        else {
+            const liveAvailable = await live.isLiveAvailable();
+            if (liveAvailable) {
+                raw = await live.route("unity_open_mcp_scene_get_data", bridgeArgs);
+                raw = injectRouteMeta(raw, { route: "live" });
+            }
+            else {
+                raw = await this.batch.route("unity_open_mcp_scene_get_data", bridgeArgs);
+                raw = injectRouteMeta(raw, { route: "batch", fallbackReason: "live_unavailable" });
+            }
+        }
+        if (!wantPaging)
+            return raw;
+        const body = parseResultBody(raw);
+        if (body === null)
+            return raw;
+        if (body.error)
+            return raw;
+        const pageSize = args.page_size;
+        const cursor = typeof args.cursor === "string" ? args.cursor : undefined;
+        const paged = pageSceneNodes(body, pageSize, cursor);
+        return withResultBody(raw, paged);
+    }
+}
+/**
+ * Page the scene_get_data node stream. The bridge emits a per-root `roots`
+ * array (summary: root roster) or a nested hierarchy (normal/verbose). We page
+ * the FLATTENED node stream so the cursor is a stable position regardless of
+ * the detail mode, then re-hang the page as a flat `nodes` array with the
+ * original scene metadata preserved.
+ */
+function pageSceneNodes(body, pageSize, cursor) {
+    const flat = flattenSceneBody(body);
+    const { page, block } = applyPaging(flat, "scene_get_data", { page_size: pageSize, cursor });
+    // Preserve scene-level metadata; replace the structural root/hierarchy fields
+    // with the flat paged node list + a note explaining the page shape.
+    const { roots, rootGameObjects, nodes, truncated, pagination: _existing, ...meta } = body;
+    void roots;
+    void rootGameObjects;
+    void nodes;
+    void truncated;
+    void _existing;
+    return attachPagination({
+        ...meta,
+        nodes: page,
+        pagingNote: "page_size returns a flattened node stream; re-read without page_size for the structural root/hierarchy view",
+    }, block);
+}
+/**
+ * Flatten the scene body into a node stream for paging. Handles both the
+ * summary root roster (array of root objects) and the nested normal/verbose
+ * hierarchy (objects with `children`).
+ */
+function flattenSceneBody(body) {
+    const out = [];
+    const walk = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        const obj = node;
+        out.push(obj);
+        const children = obj.children;
+        if (Array.isArray(children)) {
+            for (const child of children)
+                walk(child);
+        }
+    };
+    // The bridge emits `roots` (summary) or `rootGameObjects` (normal/verbose);
+    // accept either.
+    const rootField = Array.isArray(body.roots) ? body.roots : body.rootGameObjects;
+    if (Array.isArray(rootField)) {
+        for (const root of rootField)
+            walk(root);
+    }
+    return out;
 }
 //# sourceMappingURL=tool-router.js.map