unity-open-mcp 0.7.0 → 0.8.3

package/dist/tool-router.js

@@ -1,17 +1,44 @@
 import { AssetModelCache, isCompressible, routeCompressible } from "./compressible-router.js";
 import { listAssetsOffline, findReferencesOffline, dependenciesOffline } from "./offline.js";
 import { resolveEditorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES, detectStaleLog } from "./unity-log.js";
-import { summarizeProjectHealth } from "./project-health.js";
+import { summarizeProjectHealth, extractProjectHealthIssues } 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, AUTO_ACTIVATE_GROUPS, groupToTools, } from "./capabilities/tool-groups.js";
+import { GROUP_IDS, TOOL_GROUPS, AUTO_ACTIVATE_GROUPS, groupToTools, getGroup, } from "./capabilities/tool-groups.js";
+import { recommendGroups, } from "./capabilities/intent-groups.js";
 import { listRules } from "./capabilities/list-rules.js";
 import { generateSkill } from "./skill/generate-skill.js";
-import { knownClientKeys } from "./skill/client-paths.js";
+import { getKnownClientKeys } from "./skill/client-paths.js";
 import { ALL_TOOLS } from "./tools/index.js";
 import { lockPath, readInstanceLock, classifyInstance, isPidAlive } from "./instance-discovery.js";
 import { PORT_ENV_VAR } from "./constants.js";
 import { findUnityForProject } from "./running-unity.js";
+// M31-optimizations Plan 1 / L14 — opt-in route-logging gate. Resolved once at
+// module load into a boolean; the per-dispatch log sites read the boolean
+// (not process.env on every call) so the hot path stays a single branch.
+// Default-off: silent in production; set UNITY_OPEN_MCP_DEBUG=1 (or pass
+// --verbose to the server) to re-enable the [unity-open-mcp] Route: trace.
+// Genuine error-path logging is unconditional and never gated by this flag.
+//
+// Exported (ROUTE_LOG_ENABLED + logRoute) so the test suite can pin both
+// halves of the L14 contract: the env-resolution semantics (via
+// resolveRouteLogEnabled, the pure helper) and the default-off posture (via
+// the captured boolean, which reflects whatever the env was at module load).
+export function resolveRouteLogEnabled(env = process.env) {
+    return env.UNITY_OPEN_MCP_DEBUG === "1" || env.UNITY_OPEN_MCP_VERBOSE === "1";
+}
+export const ROUTE_LOG_ENABLED = resolveRouteLogEnabled();
+/** Log a happy-path route trace iff the opt-in env flag is set. No-op by
+ *  default so high-throughput agents do not pay a console.error per dispatch. */
+export function logRoute(message) {
+    if (ROUTE_LOG_ENABLED)
+        console.error(message);
+}
+// M31 Plan 3 — Editor fd-exhaustion auto-recovery (restart_editor) + prediction
+// (resource_pressure). Both act on the OS process, not the bridge, so they
+// share the local route classification with bridge_status.
+import { killEditorProcess, DEFAULT_KILL_GRACE_MS, MAX_KILL_WAIT_MS, } from "./editor-process-control.js";
+import { countFileDescriptors, computeFdHeadroom, analyzeFdTrend, LAUNCH_CONTEXT_CAVEAT, FD_CEILING, } from "./process-diagnostics.js";
 import { listInstalledEditors, fetchAvailableReleases, openInstallDeepLink, getInstallPath, setInstallPath, } from "./hub-control.js";
 /** Default Hub-control backend — calls the real hub-control functions. */
 const defaultHubBackend = {
@@ -89,6 +116,65 @@ function injectRouteMeta(result, meta) {
         return result;
     }
 }
+// ===========================================================================
+// M31-optimizations Plan 1 / H2 — single parse+stringify for the live result
+// post-processors (fold + _source + _route).
+//
+// The live find_references / dependencies paths previously chained THREE
+// CallToolResult transforms — foldFindReferencesLive → tagSource →
+// injectRouteMeta — each doing its own JSON.parse + JSON.stringify on the
+// same payload (3 cycles per call). The helpers below collapse that to ONE
+// parse and ONE stringify by operating on the parsed body object directly.
+// `transformLiveResult` is the single entry point; it parses once, applies a
+// caller-supplied body transform (fold / paging / nothing), stamps `_source`
+// and `_route`, and stringifies exactly once.
+//
+// The legacy `tagSource` / `injectRouteMeta` helpers stay for the many call
+// sites that only need ONE of the two stamps (so they incur just one
+// parse+stringify each — not the triple-cycle chain the live routes had).
+// ===========================================================================
+/**
+ * Apply a body-level transform pipeline to a {@link CallToolResult} in ONE
+ * parse + ONE stringify cycle. Used by the live find_references /
+ * dependencies / verify routes that previously chained
+ * fold→tagSource→injectRouteMeta (three parse+stringify cycles each).
+ *
+ * Steps:
+ *   1. Parse the first text content block ONCE.
+ *   2. Hand the parsed body to `transform` (may return null to signal "leave
+ *      the body as-is" — the error case; the transform has nothing useful to
+ *      do on an error body).
+ *   3. Stamp `_source` and `_route` on the (possibly transformed) body — also
+ *      when the transform returned null, falling back to the original body.
+ *      This preserves the pre-change chain's contract (`tagSource` +
+ *      `injectRouteMeta` always stamped a parseable body, error or not), so
+ *      error responses still carry `_source` / `_route` for agent routing.
+ *   4. Stringify ONCE into the result's first text block; preserve isError
+ *      and any other content blocks (e.g. an MCP image block).
+ *
+ * `transform` defaults to identity. When the body fails to parse, the result
+ * is returned unchanged (no stamps — there is no JSON object to stamp).
+ */
+function transformLiveResult(result, source, meta, transform) {
+    const body = parseResultBody(result);
+    // parseResultBody returns null when there is no text block OR the block is
+    // not a JSON object. In either case there is nothing to stamp — return the
+    // result verbatim, matching tagSource/injectRouteMeta's no-op behavior on
+    // an unparsable body.
+    if (body === null)
+        return result;
+    // A null transform signals "leave the body as-is" (e.g. the fold has
+    // nothing to do on an error body). Fall through to identity so the stamps
+    // still land — matching the pre-change chain, where tagSource/injectRouteMeta
+    // stamped any parseable body regardless of an `error` field.
+    const transformed = transform ? transform(body) : body;
+    const stamped = {
+        ...(transformed ?? body),
+        _source: source,
+        _route: meta,
+    };
+    return withResultBody(result, stamped);
+}
 // 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.
@@ -174,16 +260,22 @@ function pageFindReferencesResult(result, pageSize, cursor) {
     return attachPagination({ ...result, referencedBy: page }, block);
 }
 /**
- * Fold + page the LIVE find_references result. The bridge returns a flat
+ * Fold + page the LIVE find_references result body. 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.
+ *
+ * M31-optimizations Plan 1 / H2 — operates on a parsed body object (not a
+ * re-stringified {@link CallToolResult}) so it can be chained with
+ * {@link tagSourceBody} / {@link injectRouteMetaBody} in a single
+ * parse+stringify cycle via {@link transformLiveResult}.
+ *
+ * Returns null when the body should NOT be folded (it is not a parseable
+ * object, or it carries a top-level `error`), signalling the caller to leave
+ * the result untouched.
  */
-function foldFindReferencesLive(result, profile, wantPaging, args) {
-    const body = parseResultBody(result);
-    if (body === null)
-        return result;
+function foldFindReferencesLiveBody(body, profile, wantPaging, args) {
     if (body.error)
-        return result;
+        return null;
     // 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;
@@ -193,20 +285,19 @@ function foldFindReferencesLive(result, profile, wantPaging, args) {
         const { referencedBy: _dropped, ...rest } = body;
         void _dropped;
         const byKind = groupLiveRefsByKind(rawList);
-        return withResultBody(result, {
+        return {
             ...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 attachPagination({ ...body, referencedBy: page, totalCount: rawList.length }, block);
     }
-    return withResultBody(result, { ...body, totalCount: rawList.length });
+    return { ...body, totalCount: rawList.length };
 }
 /** Derive a byKind grouping from flat referenced paths for the live compact view. */
 function groupLiveRefsByKind(paths) {
@@ -297,6 +388,13 @@ export class ToolRouter {
             ["unity_open_mcp_generate_skill", (_l, a) => this.routeGenerateSkill(a)],
             ["unity_open_mcp_manage_tools", (l, a) => this.routeManageTools(a, l)],
             ["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);
+            // resource_pressure is the proactive prediction half (samples fd usage
+            // BEFORE exhaustion). Both are local-routed: they act on the OS process,
+            // not the bridge, like bridge_status.
+            ["unity_open_mcp_restart_editor", (l, a) => this.routeRestartEditor(a, l)],
+            ["unity_open_mcp_resource_pressure", (_l, a) => this.routeResourcePressure(a)],
             // Hub control tools (local-routed; system-level ops).
             ["unity_open_mcp_hub_list_editors", () => this.routeHubListEditors()],
             ["unity_open_mcp_hub_available_releases", () => this.routeHubAvailableReleases()],
@@ -382,7 +480,7 @@ export class ToolRouter {
         // second pinned branch for a new always-batch tool — extend the map.
         const alwaysBatchReason = ALWAYS_BATCH_TOOLS.get(toolName);
         if (alwaysBatchReason !== undefined) {
-            console.error(`[unity-open-mcp] Route: ${toolName} -> batch (always-batch: ${alwaysBatchReason})`);
+            logRoute(`[unity-open-mcp] Route: ${toolName} -> batch (always-batch: ${alwaysBatchReason})`);
             const result = await this.batch.route(toolName, args);
             return injectRouteMeta(result, {
                 route: "batch",
@@ -395,11 +493,11 @@ export class ToolRouter {
         }
         const liveAvailable = await live.isLiveAvailable();
         if (liveAvailable) {
-            console.error(`[unity-open-mcp] Route: ${toolName} -> live`);
+            logRoute(`[unity-open-mcp] Route: ${toolName} -> live`);
             const result = await live.route(toolName, args);
             return injectRouteMeta(result, { route: "live" });
         }
-        console.error(`[unity-open-mcp] Route: ${toolName} -> batch (live bridge unavailable)`);
+        logRoute(`[unity-open-mcp] Route: ${toolName} -> batch (live bridge unavailable)`);
         if (isPing) {
             return this.batchPingResult();
         }
@@ -632,7 +730,11 @@ export class ToolRouter {
         const rawClients = Array.isArray(args.clients) ? args.clients : [];
         // Client allowlist comes from the single-source manifest at
         // `skills/client-paths.json`. Do not add a literal union here.
-        const allowedClients = new Set(knownClientKeys());
+        // M31-optimizations Plan 4 / T4.4 (L6) — reuse the module-level
+        // `KNOWN_CLIENT_KEYS` singleton instead of allocating a fresh Set per
+        // call. The Set is built once on first access and re-derived only when
+        // the manifest cache is reset (tests).
+        const allowedClients = getKnownClientKeys();
         const clients = rawClients.filter((c) => typeof c === "string" && allowedClients.has(c));
         const caps = buildCapabilities({
             tools: ALL_TOOLS,
@@ -685,6 +787,28 @@ export class ToolRouter {
         if (action === "list_groups") {
             return this.manageToolsListGroups(live);
         }
+        // M31 Plan 2 / T31.2 — intent-driven actions. `suggest` is the read-only
+        // path (returns recommendations without changing state); `activate_for`
+        // activates the recommended set in one call. Both share the recommend
+        // engine + the per-group compiled-state availability, so an agent sees
+        // the same honesty about unavailable groups as `list_groups` (the
+        // recommendation lists them as `unavailable` with `availableReason`
+        // instead of pretending activation succeeded).
+        if (action === "suggest" || action === "activate_for") {
+            const intent = typeof args.intent === "string" ? args.intent : "";
+            const tags = Array.isArray(args.tags)
+                ? args.tags.filter((t) => typeof t === "string")
+                : [];
+            // Recommend against an empty input is a structured empty result, not an
+            // error — the agent gets the `list_groups` hint and can retry. This
+            // matches the spec ("unmatched intent returns a structured empty
+            // recommendation + hint to list_groups (no hallucinated groups)").
+            const rec = recommendGroups({ intent, tags });
+            if (action === "suggest") {
+                return this.manageToolsSuggest(rec, live);
+            }
+            return this.manageToolsActivateFor(rec, live);
+        }
         if (action === "reset") {
             const before = this.sessionState.activeGroups();
             this.sessionState.reset();
@@ -692,8 +816,9 @@ export class ToolRouter {
             return this.manageToolsResult({
                 reset: true,
                 activeGroups: this.sessionState.activeGroups(),
-                message: "Tool-group visibility restored to the five default-on groups. " +
-                    "MCP clients that support listChanged will refresh ListTools automatically.",
+                message: "Tool-group visibility restored to the default-on groups (core + " +
+                    "gate-and-verify). MCP clients that support listChanged will refresh " +
+                    "ListTools automatically.",
             });
         }
         if (action === "activate" || action === "deactivate") {
@@ -725,7 +850,8 @@ export class ToolRouter {
                         : `Group '${group}' was already inactive.`,
             });
         }
-        return this.manageToolsError("unknown_action", `Unknown action '${action}'. Valid actions: list_groups, activate, deactivate, reset.`);
+        return this.manageToolsError("unknown_action", `Unknown action '${action}'. Valid actions: list_groups, activate, ` +
+            `deactivate, reset, suggest, activate_for.`);
     }
     async manageToolsListGroups(live) {
         // M20 Plan 7 / T20.7.0 — fetch the compiled-state inventory once and
@@ -774,13 +900,129 @@ export class ToolRouter {
             activeGroups: this.sessionState.activeGroups(),
             note: "Activate a group to add its tools to your ListTools surface; " +
                 "deactivate to hide them. State is per-session and ephemeral — " +
-                "it resets to the five default-on groups when the MCP server restarts. " +
-                "Compiled-state availability (the `available` field) reflects " +
-                "whether the Unity domain dependency is compiled in; use " +
-                "unity_open_mcp_capabilities for the authoritative compiled-state " +
-                "report.",
+                "it resets to the default-on groups (core + gate-and-verify) when " +
+                "the MCP server restarts. Compiled-state availability (the " +
+                "`available` field) reflects whether the Unity domain dependency is " +
+                "compiled in; use unity_open_mcp_capabilities for the authoritative " +
+                "compiled-state report.",
+        }, "local");
+    }
+    // M31 Plan 2 / T31.2 — `suggest` handler. Read-only: returns the
+    // recommendation with per-group compiled-state availability so the agent
+    // sees the same honesty as `list_groups` (a recommended group whose domain
+    // dependency is missing surfaces with `unavailable: true` +
+    // `availableReason`, never as a silent success). Reconciles auto-activation
+    // first so the `alreadyActive` flags reflect packages that came online.
+    async manageToolsSuggest(rec, live) {
+        const inventory = await this.fetchInventoryAndReconcile(live);
+        const compiledAvailability = this.computeCompiledAvailability(inventory, groupToTools());
+        const groups = rec.groups.map((g) => this.augmentRecommendation(g, compiledAvailability));
+        return sourceResult({
+            action: "suggest",
+            intent: rec,
+            groups,
+            activeGroups: this.sessionState.activeGroups(),
+            // `empty` surfaces at the top level too so agents branching on a
+            // miss don't have to dig into `intent.empty`.
+            empty: rec.empty,
+            ...(rec.empty ? { hint: rec.hint } : {}),
+            note: "Read-only recommendation. Pass the same intent/tags to " +
+                "action=\"activate_for\" to activate the recommended groups in one " +
+                "call, or activate individual ids with action=\"activate\".",
+        }, "local");
+    }
+    // M31 Plan 2 / T31.2 — `activate_for` handler. Activates the recommended
+    // set (union with the current active groups — never deactivates anything).
+    // `unavailable` recommended groups are reported honestly: today's session
+    // model lets an agent activate a group whose domain dependency is missing
+    // (the tools appear in ListTools but error at call time), so we DO activate
+    // them but the response calls out the gap via `unavailable` + the standard
+    // `availableReason`. Emits `notifications/tools/list_changed` exactly once
+    // when the visible set changed (idempotent when already active).
+    async manageToolsActivateFor(rec, live) {
+        const inventory = await this.fetchInventoryAndReconcile(live);
+        const compiledAvailability = this.computeCompiledAvailability(inventory, groupToTools());
+        const before = this.sessionState.activeGroups();
+        const activated = [];
+        const skipped = [];
+        const unavailable = [];
+        for (const g of rec.groups) {
+            const changed = this.sessionState.activate(g.id);
+            if (changed) {
+                activated.push(g.id);
+            }
+            else {
+                skipped.push(g.id);
+            }
+            const avail = compiledAvailability.get(g.id);
+            if (avail && (avail.available === false || avail.available === null)) {
+                unavailable.push({ id: g.id, reason: avail.reason });
+            }
+        }
+        await this.maybeNotifyToolListChanged(before);
+        const groups = rec.groups.map((g) => this.augmentRecommendation(g, compiledAvailability));
+        const anyChange = activated.length > 0;
+        const message = rec.empty
+            ? rec.hint
+            : anyChange
+                ? `Activated ${activated.length} group(s) for the intent: ` +
+                    `${activated.join(", ")}. MCP clients that support listChanged ` +
+                    `will refresh ListTools automatically.`
+                : `All recommended groups were already active.`;
+        return sourceResult({
+            action: "activate_for",
+            intent: rec,
+            groups,
+            activated,
+            skipped,
+            unavailable,
+            activeGroups: this.sessionState.activeGroups(),
+            changed: anyChange,
+            empty: rec.empty,
+            message,
+            ...(unavailable.length > 0
+                ? {
+                    unavailableNote: "One or more recommended groups have a missing Unity domain " +
+                        "dependency — their tools will appear in ListTools but error " +
+                        "at call time. Use unity_open_mcp_capabilities for the " +
+                        "authoritative compiled-state report, or install the cited " +
+                        "Unity package and reconcile via list_groups.",
+                }
+                : {}),
         }, "local");
     }
+    /**
+     * Fetch the live bridge inventory (or null when offline) and reconcile auto-
+     * activation against it. Shared by `suggest` / `activate_for` so both see the
+     * same compiled-state + auto-activated snapshot as `list_groups` without
+     * duplicating the GET /tools hop.
+     */
+    async fetchInventoryAndReconcile(live) {
+        const liveAvailable = await live.isLiveAvailable();
+        const inventory = liveAvailable ? await live.listBridgeTools() : null;
+        await this.reconcileAutoActivation(inventory ? { tools: inventory.tools } : null);
+        return inventory;
+    }
+    /**
+     * Augment a {@link RecommendedGroup} with the session + compiled-state
+     * fields the agent needs to act on it: whether it is already active, its
+     * availability, and its catalog description / Unity package dependency.
+     */
+    augmentRecommendation(g, compiledAvailability) {
+        const entry = getGroup(g.id);
+        const avail = compiledAvailability.get(g.id);
+        return {
+            id: g.id,
+            reason: g.reason,
+            matchedTags: g.matchedTags,
+            ...(g.fromMutationSignal ? { fromMutationSignal: true } : {}),
+            description: entry?.description ?? null,
+            alreadyActive: this.sessionState.isGroupActive(g.id),
+            available: avail?.available ?? null,
+            availableReason: avail?.reason ?? null,
+            unityPackage: entry?.unityPackage ?? null,
+        };
+    }
     /**
      * Notify MCP clients when the filtered ListTools surface changed. Skips the
      * callback when the active group set is unchanged (e.g. no-op reset).
@@ -1046,6 +1288,329 @@ export class ToolRouter {
         // the MCP server (no bridge tool endpoint, no batch Unity).
         return sourceResult(body, "local");
     }
+    // ── M31 Plan 3 — Editor fd-exhaustion operator surfaces (local-routed) ──
+    //
+    // restart_editor (T31.3, reactive kill) + resource_pressure (T31.4,
+    // proactive prediction). Both resolve entirely inside the MCP server: they
+    // act on the OS process (kill / lsof / /proc), never on the bridge. The
+    // bridge is the thing that dies on fd-exhaustion, so neither tool may
+    // depend on it for its primary path. restart_editor still consults the
+    // bridge opportunistically for the active-scene-dirty signal — the Editor
+    // is hung, but the HTTP listener might still be up long enough to answer
+    // a read-only status call before the kill.
+    /**
+     * T31.3 — terminate the hung Unity Editor after confirming the
+     * `editor_fd_exhaustion` signature is present in Editor.log. Requires
+     * explicit `confirm: true`. The relaunch half is intentionally deferred
+     * (the Hub owns the interactive-Editor launch recipe); the response tells
+     * the operator/agent to relaunch via the Hub.
+     *
+     * Safety contract (the plan's "explicit confirmation" requirement):
+     *   1. Refuses unless `confirm: true` is passed. A dry-run call (confirm
+     *      false or absent) returns the PID + diagnosis it would act on, no
+     *      side effect.
+     *   2. Refuses when the fd-exhaustion signature is ABSENT from Editor.log.
+     *      Never restart on a plain `dead_bridge` (usually a fixable compile
+     *      failure) or a merely offline bridge.
+     *   3. Surfaces unsaved-scene risk when the bridge is still reachable
+     *      enough to report dirty scenes. Does NOT block the kill — the Editor
+     *      is hung — but makes the risk visible in the response.
+     */
+    async routeRestartEditor(args, live) {
+        const confirm = args.confirm === true;
+        const graceMs = typeof args.kill_grace_ms === "number" &&
+            Number.isInteger(args.kill_grace_ms) &&
+            args.kill_grace_ms >= 0 &&
+            args.kill_grace_ms <= MAX_KILL_WAIT_MS
+            ? args.kill_grace_ms
+            : DEFAULT_KILL_GRACE_MS;
+        // 1. Resolve the fd-exhaustion signature from Editor.log FIRST. This is
+        //    the gate: the tool must NEVER restart on a plain dead_bridge / a
+        //    fixable compile failure. We reuse the same offline log read +
+        //    health-issue extractor as read_compile_errors so the diagnosis is
+        //    identical to what the agent already saw.
+        const logPath = resolveEditorLogPath(this.projectPath);
+        const tail = readLogTail(logPath, DEFAULT_LOG_TAIL_BYTES);
+        let signaturePresent = false;
+        let logWarning = null;
+        if (tail.error || !tail.exists) {
+            // Without the log we cannot confirm the signature — refuse for safety.
+            logWarning = tail.error
+                ? `Editor.log unreadable at ${logPath}: ${tail.error}`
+                : `No Editor.log found at ${logPath}.`;
+        }
+        else {
+            const issues = extractProjectHealthIssues(tail.content);
+            signaturePresent = issues.some((i) => i.kind === "editor_fd_exhaustion");
+            if (!signaturePresent) {
+                logWarning =
+                    "The editor_fd_exhaustion signature is NOT present in the recent " +
+                        "Editor.log tail. The Editor may be slow/stuck for a different " +
+                        "reason (a fixable compile failure, a modal, an unresponsive main " +
+                        "thread). Re-run unity_open_mcp_read_compile_errors to confirm " +
+                        "the diagnosis before killing the Editor.";
+            }
+        }
+        // 2. Resolve the live Unity PID via the process scan (same primitive
+        //    bridge_status uses for cold-Safe-Mode detection). The bridge may
+        //    already be down (it dies on fd-exhaustion), so we cannot rely on
+        //    the instance lock's pid alone.
+        let pid = null;
+        try {
+            const proc = findUnityForProject(this.projectPath);
+            pid = proc ? proc.pid : null;
+        }
+        catch {
+            pid = null;
+        }
+        // 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.
+        if (!confirm) {
+            return sourceResult({
+                action: "restart_editor",
+                confirm: false,
+                dryRun: true,
+                signaturePresent,
+                ...(pid !== null ? { wouldKillPid: pid } : {}),
+                ...(logWarning !== null ? { warning: logWarning } : {}),
+                projectPath: this.projectPath,
+                message: "Dry-run preview. Pass confirm: true to actually terminate the " +
+                    "hung Unity Editor. Only do so after read_compile_errors " +
+                    "confirms an editor_fd_exhaustion issue — killing the Editor " +
+                    "can destroy unsaved scene work and in-flight asset imports.",
+            }, "local");
+        }
+        // 4. Confirmed-path refusals. Each guard surfaces a structured code so
+        //    an agent can branch on why the kill did not happen.
+        if (logWarning !== null && !signaturePresent) {
+            return sourceResult({
+                error: {
+                    code: "restart_signature_absent",
+                    message: logWarning,
+                    logPath,
+                },
+            }, "local", true);
+        }
+        if (pid === null) {
+            return sourceResult({
+                error: {
+                    code: "unity_process_not_found",
+                    message: "No live Unity process matches this project's path. The " +
+                        "Editor may have already exited, or it was launched without " +
+                        "-projectPath (the scanner cannot match a bare editor " +
+                        "launch). Relaunch Unity for this project via the Hub.",
+                    projectPath: this.projectPath,
+                },
+            }, "local", true);
+        }
+        // 5. Opportunistic active-scene-dirty check. The Editor is hung, but the
+        //    bridge HTTP listener might still be up long enough to answer a
+        //    read-only status call. If so, surface dirtyScenes[] as a warning so
+        //    the operator knows what unsaved work the kill will lose. This does
+        //    NOT block the kill — the Editor is hung, saving is not an option.
+        let dirtyScenesWarning = null;
+        try {
+            const liveAvailable = await live.isLiveAvailable();
+            if (liveAvailable) {
+                const dirtyResult = await live.route("unity_open_mcp_scene_get_dirty_summary", {});
+                const dirtyBody = parseResultBody(dirtyResult);
+                if (dirtyBody && Array.isArray(dirtyBody.scenes)) {
+                    const dirty = dirtyBody.scenes
+                        .filter((s) => s.isDirty === true)
+                        .map((s) => ({
+                        name: typeof s.name === "string" ? s.name : "",
+                        path: typeof s.path === "string" ? s.path : "",
+                        isDirty: true,
+                    }));
+                    if (dirty.length > 0)
+                        dirtyScenesWarning = dirty;
+                }
+            }
+        }
+        catch {
+            // The bridge is unreachable (expected on fd-exhaustion). Swallow — the
+            // dirty-scene signal is opportunistic, not load-bearing.
+        }
+        // 6. Kill the Editor.
+        const kill = await killEditorProcess(pid, graceMs);
+        return this.restartEditorKillResponse(pid, graceMs, kill, dirtyScenesWarning);
+    }
+    /** Build the confirmed-kill response from a {@link KillResult}. */
+    restartEditorKillResponse(pid, graceMs, kill, dirtyScenesWarning) {
+        if (kill.terminated) {
+            return sourceResult({
+                action: "restart_editor",
+                confirm: true,
+                killed: true,
+                pid: kill.pid,
+                method: kill.method,
+                elapsedMs: kill.elapsedMs,
+                graceMs,
+                ...(dirtyScenesWarning !== null
+                    ? {
+                        dirtyScenesWarning,
+                        dirtyScenesNote: "These scenes had unsaved changes when the Editor was " +
+                            "killed — that work is lost. Saving is not an option when " +
+                            "the Editor is hung mid-build; surface this to the operator.",
+                    }
+                    : {}),
+                nextSteps: [
+                    "Editor terminated. Relaunch Unity for this project via the Hub " +
+                        "(the MCP server does not own the interactive-Editor launch " +
+                        "recipe — the flags the Hub used at original launch are not " +
+                        "knowable from here).",
+                    "After relaunch, poll unity_open_mcp_bridge_status until it " +
+                        "returns status: \"running\" to confirm the bridge reconnected " +
+                        "and wrote a fresh instance lock.",
+                    "Once running, call unity_open_mcp_resource_pressure to sample " +
+                        "the fresh Editor's fd baseline — the leak accumulates across " +
+                        "domain reloads, so a fresh process starts back near zero.",
+                ],
+            }, "local");
+        }
+        // Kill failed — the Editor is still alive (or its state is unknown).
+        return sourceResult({
+            action: "restart_editor",
+            confirm: true,
+            killed: false,
+            pid: kill.pid,
+            reason: kill.reason,
+            message: kill.message,
+            graceMs,
+            nextSteps: [
+                "The automated kill did not terminate the Editor. The operator " +
+                    "must force-quit Unity manually (Activity Monitor / Task " +
+                    "Manager / `kill -9 <pid>`).",
+                kill.reason === "not_found"
+                    ? "The PID vanished between the scan and the kill — the Editor " +
+                        "may have exited on its own. Re-run unity_open_mcp_bridge_status " +
+                        "to confirm state before retrying."
+                    : "After a manual force-quit, relaunch Unity via the Hub and " +
+                        "poll unity_open_mcp_bridge_status until running.",
+            ],
+        }, "local", true);
+    }
+    /**
+     * T31.4 — sample the live Unity process's file-descriptor usage and report
+     * headroom against Mono's ~1024 fd ceiling (the real trip point for the Bee
+     * build-driver hang). Proactive counterpart to restart_editor: lets an agent
+     * warn the operator to save + restart BEFORE the Editor hangs, while the
+     * bridge is still healthy. The probe runs server-side (lsof / /proc / Handle
+     * Count) and does NOT require the bridge to be reachable — the bridge is
+     * what dies on fd-exhaustion.
+     *
+     * Records the sample in the session-scoped in-memory ring so successive
+     * calls build a trend (monotonic climb = leak in progress). No disk cache.
+     */
+    async routeResourcePressure(args) {
+        // 1. Resolve the PID. An explicit pid arg wins; otherwise scan for the
+        //    live Unity process for this project (same primitive bridge_status
+        //    uses). The probe must NOT depend on the bridge.
+        let pid = null;
+        if (typeof args.pid === "number" && Number.isInteger(args.pid) && args.pid > 0) {
+            pid = args.pid;
+        }
+        else {
+            try {
+                const proc = findUnityForProject(this.projectPath);
+                pid = proc ? proc.pid : null;
+            }
+            catch {
+                pid = null;
+            }
+        }
+        if (pid === null) {
+            return sourceResult({
+                error: {
+                    code: "unity_process_not_found",
+                    message: "No live Unity process matches this project's path, and no " +
+                        "explicit pid was supplied. resource_pressure samples the OS " +
+                        "process directly (it does not depend on the bridge) — open " +
+                        "Unity for this project first, or pass an explicit pid.",
+                    projectPath: this.projectPath,
+                },
+            }, "local", true);
+        }
+        // 2. Probe + record the sample. A failed probe still records a sample
+        //    (count: null) so the trend detector sees the gap and does not
+        //    interpolate across it.
+        const probe = countFileDescriptors(pid);
+        const count = probe.count;
+        const headroom = computeFdHeadroom(count, "approximate" in probe ? probe.approximate : false);
+        const ts = Date.now();
+        this.sessionState.recordFdSample({ ts, pid, count });
+        const samples = this.sessionState.fdSamplesSnapshot();
+        const trend = analyzeFdTrend(samples);
+        // 3. Build the response. The launchContextCaveat is always present so an
+        //    agent (and the operator) understands the Mono-ceiling-vs-OS-soft-
+        //    limit nuance. warningState is non-null only when there is something
+        //    to surface (warn/critical/leaking); ok+stable stays silent.
+        const fdMethod = probe.method;
+        const approximate = "approximate" in probe ? probe.approximate : false;
+        const probeReason = "reason" in probe ? probe.reason : null;
+        const probeMessage = "message" in probe ? probe.message : null;
+        const warningState = headroom.state === "warn" || headroom.state === "critical" || trend.state === "leaking"
+            ? {
+                level: headroom.state === "critical"
+                    ? "critical"
+                    : trend.state === "leaking"
+                        ? "leaking"
+                        : "warn",
+                message: headroom.state === "critical"
+                    ? `Editor fd usage is at ${Math.round(headroom.pressureRatio * 100)}% of ` +
+                        `Mono's ${FD_CEILING}-descriptor ceiling — the next domain reload is ` +
+                        `likely to trip the Bee build-driver hang. Save scene work and restart ` +
+                        `Unity via the Hub now, before the Editor hangs.`
+                    : trend.state === "leaking"
+                        ? `Editor fd usage is climbing monotonically across samples (leak in ` +
+                            `progress): trend delta ${trend.delta} over ${trend.sampleCount} ` +
+                            `sample(s). Save scene work and plan a restart before the count ` +
+                            `crosses the ${FD_CEILING}-descriptor ceiling.`
+                        : `Editor fd usage is at ${Math.round(headroom.pressureRatio * 100)}% of ` +
+                            `Mono's ${FD_CEILING}-descriptor ceiling. Monitor the trend; if it ` +
+                            `keeps climbing across domain reloads, save scene work and restart ` +
+                            `Unity via the Hub before the Editor hangs.`,
+            }
+            : null;
+        return sourceResult({
+            pid,
+            fdCount: count,
+            fdMethod,
+            approximate,
+            ceiling: FD_CEILING,
+            headroom: headroom.headroom,
+            pressureRatio: headroom.pressureRatio,
+            state: headroom.state,
+            reliable: headroom.reliable,
+            trend,
+            samples: samples.map((s) => ({
+                ts: s.ts,
+                pid: s.pid,
+                count: s.count,
+            })),
+            sampleCount: samples.length,
+            launchContextCaveat: LAUNCH_CONTEXT_CAVEAT,
+            ...(probeReason !== null ? { probeReason } : {}),
+            ...(probeMessage !== null ? { probeMessage } : {}),
+            ...(warningState !== null
+                ? {
+                    warning: warningState,
+                    agentNextSteps: [
+                        "Surface this to the operator — the Editor is approaching " +
+                            "fd-exhaustion and the bridge (the thing that dies on " +
+                            "exhaustion) cannot recover on its own.",
+                        "If scene work is unsaved, recommend saving now while the " +
+                            "bridge is still healthy.",
+                        "When the operator is ready, restart Unity via the Hub. " +
+                            "After relaunch, call resource_pressure again to sample " +
+                            "the fresh Editor's fd baseline (a fresh process starts " +
+                            "back near zero).",
+                    ],
+                }
+                : {}),
+        }, "local");
+    }
     // ── M26 Plan 2 — Unity Hub control (local-routed) ────────────────
     //
     // Each of these resolves entirely inside the MCP server (no bridge tool
@@ -1153,7 +1718,7 @@ export class ToolRouter {
         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");
+            logRoute("[unity-open-mcp] Route: find_references -> 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. The 0 here is the server-internal
@@ -1164,13 +1729,13 @@ export class ToolRouter {
                 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);
-            // T6.1 — tag _source=live so the response matches the offline path's
-            // _source=offline tag (clients switching on _source get a defined value
-            // for the common live case instead of undefined).
-            return injectRouteMeta(tagSource(folded, "live"), { route: "live" });
+            // M31-optimizations Plan 1 / H2 — fold + tag _source=live + stamp _route
+            // in ONE parse + ONE stringify. Previously this was three cycles:
+            // foldFindReferencesLive → tagSource → injectRouteMeta. T6.1's _source
+            // contract is preserved (clients switching on _source still see "live").
+            return transformLiveResult(result, "live", { route: "live" }, (body) => foldFindReferencesLiveBody(body, profile, wantPaging, args));
         }
-        console.error("[unity-open-mcp] Route: find_references -> offline (live bridge unavailable)");
+        logRoute("[unity-open-mcp] Route: find_references -> offline (live bridge unavailable)");
         const assetPath = typeof args.asset_path === "string" ? args.asset_path : undefined;
         const guid = typeof args.guid === "string" ? args.guid : undefined;
         if (!assetPath && !guid) {
@@ -1256,7 +1821,7 @@ export class ToolRouter {
         // 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");
+            logRoute("[unity-open-mcp] Route: dependencies -> live");
             // The live tool honors asset_path/guid/detail/max_results only.
             const liveArgs = {
                 asset_path: assetPath,
@@ -1265,10 +1830,12 @@ export class ToolRouter {
                 max_results: typeof args.max_results === "number" ? args.max_results : 100,
             };
             const result = await live.route("unity_open_mcp_dependencies", liveArgs);
-            // T6.1 — tag _source=live for parity with the offline route's _source.
-            return injectRouteMeta(tagSource(result, "live"), { route: "live" });
+            // M31-optimizations Plan 1 / H2 — tag _source=live + stamp _route in ONE
+            // parse + ONE stringify. Previously this was two cycles:
+            // tagSource → injectRouteMeta. T6.1's _source=live contract preserved.
+            return transformLiveResult(result, "live", { route: "live" });
         }
-        console.error(includeImpact && liveAvailable
+        logRoute(includeImpact && liveAvailable
             ? "[unity-open-mcp] Route: dependencies -> offline (include_impact is offline-only)"
             : "[unity-open-mcp] Route: dependencies -> offline (live bridge unavailable)");
         try {
@@ -1311,28 +1878,42 @@ export class ToolRouter {
         // 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.
+        // M31-optimizations Plan 1 / H2 — defer the _route stamp to the single-
+        // parse fold below (saves one parse+stringify per call vs. the previous
+        // injectRouteMeta → parseResultBody → withResultBody chain).
         const canBatch = this.batch.isBatchTool(toolName);
         let raw;
+        let routeMeta;
         if (!canBatch) {
             raw = await live.route(toolName, args);
-            raw = injectRouteMeta(raw, { route: "live" });
+            routeMeta = { route: "live" };
         }
         else {
             const liveAvailable = await live.isLiveAvailable();
             if (liveAvailable) {
                 raw = await live.route(toolName, args);
-                raw = injectRouteMeta(raw, { route: "live" });
+                routeMeta = { route: "live" };
             }
             else {
                 raw = await this.batch.route(toolName, args);
-                raw = injectRouteMeta(raw, { route: "batch", fallbackReason: "live_unavailable" });
+                routeMeta = { route: "batch", fallbackReason: "live_unavailable" };
             }
         }
         const body = parseResultBody(raw);
-        if (body === null)
-            return raw;
-        if (body.error)
-            return raw;
+        if (body === null) {
+            // Body not parseable — fall back to the legacy injectRouteMeta path so
+            // _route is still stamped (matches pre-change behavior on this edge).
+            return injectRouteMeta(raw, routeMeta);
+        }
+        if (body.error) {
+            return injectRouteMeta(raw, routeMeta);
+        }
+        // Stamp _route on the parsed body BEFORE folding so the key order matches
+        // the pre-change chain (injectRouteMeta ran first, then foldVerifyResult
+        // spread its result on top). foldVerifyResult's spreads (`...rest` /
+        // `...result`) carry `_route` through unchanged, preserving byte-identical
+        // output. Single stringify via withResultBody below.
+        body._route = routeMeta;
         const folded = foldVerifyResult(body, toolName, profile, { page_size: pageSize, cursor });
         return withResultBody(raw, folded);
     }
@@ -1350,6 +1931,15 @@ export class ToolRouter {
         delete bridgeArgs.page_size;
         delete bridgeArgs.cursor;
         bridgeArgs.detail = detail;
+        // M3 — when paging, request the full hierarchy from the bridge. The bridge
+        // clamps max_nodes to >= 1 (ScenesTools.cs:387), so 0 is NOT an unlimited
+        // sentinel there; without this override the default 200 would cap the
+        // flattened stream and paging could never walk past node 200 even once the
+        // field path is fixed. Use a large explicit cap so paging can walk the
+        // whole tree; applyPaging enforces the per-page size.
+        if (wantPaging) {
+            bridgeArgs.max_nodes = SCENE_PAGING_MAX_NODES;
+        }
         const canBatch = this.batch.isBatchTool("unity_open_mcp_scene_get_data");
         let raw;
         if (!canBatch) {
@@ -1392,17 +1982,51 @@ function pageSceneNodes(body, pageSize, cursor) {
     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;
+    // M3 — the bridge nests the hierarchy under `body.scene` (ScenesTools.cs:
+    // 393-417 emits `{"status":"ok","scene":{...,"roots":[...],"truncated":N}}`),
+    // so the structural fields live on `body.scene`, not `body`. The previous
+    // destructure looked at the top level and silently dropped the bridge's
+    // `truncated` count; we now pull it from `body.scene` and re-attach it on
+    // the page so callers can tell paging-truncated (resumable via next_cursor)
+    // from bridge-truncated (the source cap was hit).
+    //
+    // B-N20 — the previous rewrite built a fresh `{status, scene: {...}}` object,
+    // silently discarding every OTHER top-level field. The most important of
+    // those is `_route` (stamped at :2409/2414/2417 to signal live vs batch
+    // fallback), which docs/api/routing-lifecycle.md documents as the agent's
+    // data-origin signal: a paging agent would lose the live-vs-batch-fallback
+    // indication whenever `page_size` is supplied, while the unpaged response
+    // still carries it. Spread the rest of `body` (everything except `scene`)
+    // so the page matches the unpaged response's top-level shape.
+    const scene = (body.scene && typeof body.scene === "object")
+        ? body.scene
+        : {};
+    const { roots, rootGameObjects, nodes, truncated, moreHidden, pagination: _existing, ...sceneMeta } = scene;
     void roots;
     void rootGameObjects;
     void nodes;
     void truncated;
+    void moreHidden;
     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);
+    // Pull the top-level meta (everything except `scene`, which we rebuild).
+    const { scene: _s, ...topMeta } = body;
+    void _s;
+    const result = {
+        ...topMeta,
+        status: body.status ?? "ok",
+        scene: {
+            ...sceneMeta,
+            nodes: page,
+            pagingNote: "page_size returns a flattened node stream; re-read without page_size for the structural root/hierarchy view",
+        },
+    };
+    // Carry the bridge's source-side truncation count through to the page so an
+    // agent can distinguish "more pages" (pagination.truncated) from "the bridge
+    // capped the hierarchy" (scene.truncated). Both can be non-zero at once.
+    if (typeof truncated === "number" && truncated > 0) {
+        result.scene.truncated = truncated;
+    }
+    return attachPagination(result, block);
 }
 /**
  * Flatten the scene body into a node stream for paging. Handles both the
@@ -1422,13 +2046,27 @@ function flattenSceneBody(body) {
                 walk(child);
         }
     };
+    // M3 — the bridge nests everything one level down under `body.scene`
+    // (`{"status":"ok","scene":{...,"roots":[...]}}`, ScenesTools.cs:393-417).
+    // The previous code read `body.roots` / `body.rootGameObjects` directly, so
+    // `rootField` was always undefined and paging returned an empty node list
+    // while claiming completeness. Read from `body.scene` first, then fall back
+    // to the top level for any caller that hands us a pre-unwrapped body.
+    const scene = (body.scene && typeof body.scene === "object")
+        ? body.scene
+        : body;
     // The bridge emits `roots` (summary) or `rootGameObjects` (normal/verbose);
     // accept either.
-    const rootField = Array.isArray(body.roots) ? body.roots : body.rootGameObjects;
+    const rootField = Array.isArray(scene.roots) ? scene.roots : scene.rootGameObjects;
     if (Array.isArray(rootField)) {
         for (const root of rootField)
             walk(root);
     }
     return out;
 }
+// M3 — large explicit cap forwarded to the bridge when paging so the
+// flattened stream is not truncated at the default 200 before paging even
+// starts. applyPaging enforces the per-page size; this only lifts the
+// source-side ceiling.
+const SCENE_PAGING_MAX_NODES = 100_000;
 //# sourceMappingURL=tool-router.js.map