unity-open-mcp 0.9.0 → 1.1.0

package/dist/tool-router.js

@@ -1,18 +1,22 @@
 import { AssetModelCache, isCompressible, routeCompressible } from "./compressible-router.js";
 import { listAssetsOffline, findReferencesOffline, dependenciesOffline } from "./offline.js";
-import { resolveEditorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES, detectStaleLog, detectStaleAssembly } from "./unity-log.js";
+import { resolveEditorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES, detectStaleLog, detectStaleAssembly, detectErrorsPredatingEdits, parseLogAuthorship, compareLogAuthorship } from "./unity-log.js";
+import { toolHintReference } from "./tool-hint.js";
+import { scanForFdExhaustion } from "./editor-wedge.js";
 import { summarizeProjectHealth, extractProjectHealthIssues } from "./project-health.js";
+import { countProjectAsmdefs, countAssembliesWithErrors } from "./asmdef-discovery.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, getGroup, } from "./capabilities/tool-groups.js";
 import { recommendGroups, } from "./capabilities/intent-groups.js";
 import { listRules } from "./capabilities/list-rules.js";
+import { viewCapabilities } from "./capabilities/capabilities-view.js";
 import { generateSkill } from "./skill/generate-skill.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";
+import { PORT_ENV_VAR, EXPECTED_BRIDGE_WIRE_CONTRACT } from "./constants.js";
+import { findUnityForProject, readProcessCommandLine } 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.
@@ -38,7 +42,8 @@ export function logRoute(message) {
 // (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 { countFileDescriptors, computeFdHeadroom, analyzeFdTrend, LAUNCH_CONTEXT_CAVEAT, } from "./process-diagnostics.js";
+import { readFdCeiling } from "./project-settings.js";
 import { listInstalledEditors, fetchAvailableReleases, openInstallDeepLink, getInstallPath, setInstallPath, } from "./hub-control.js";
 /** Default Hub-control backend — calls the real hub-control functions. */
 const defaultHubBackend = {
@@ -49,7 +54,7 @@ const defaultHubBackend = {
     setInstallPath: (path) => setInstallPath(path),
 };
 import { BATCH_TOOL_NAMES, ALWAYS_BATCH_TOOLS } from "./batch-spawn.js";
-import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, } from "./output-profile.js";
+import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, isOutputProfile, } from "./output-profile.js";
 /**
  * Single source of truth for the `_source` tag. Every route-tagging site goes
  * through one of the two helpers below so live / offline / local stay
@@ -337,7 +342,25 @@ function groupLiveRefsByKind(paths) {
 }
 // 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) {
+function bridgeStatusNextStep(status, wedge) {
+    if (status === "wedged") {
+        return wedge?.reason === "main_thread_wedged"
+            ? "Unity's main thread is wedged — the HTTP listener still answers /ping, but the " +
+                "editor heartbeat has stopped, which is the signature of a MODAL DIALOG blocking " +
+                "the message pump (material/scene converters and several ExecuteMenuItem paths " +
+                "open one). This is NOT a compile failure and NOT a dead bridge assembly — a dead " +
+                "assembly has no listener at all. It cannot self-heal and no tool can dismiss the " +
+                "dialog: an operator must dismiss it in the Unity UI, after which queued calls " +
+                "resume. Prefer non-interactive APIs over unity_open_mcp_execute_menu for " +
+                "converter-style menus."
+            : "The Unity Editor hit the Bee build driver's file-descriptor exhaustion — the " +
+                "process is alive and the listener answers, but it can no longer BUILD: " +
+                "Library/ScriptAssemblies stops updating, so C# edits never take effect and " +
+                "unity_open_mcp_execute_csharp silently runs the previous assembly. Do not trust " +
+                "any result computed since. Call unity_open_mcp_read_compile_errors to confirm " +
+                "the editor_fd_exhaustion issue, save scene work, then restart the Editor " +
+                "(unity_open_mcp_restart_editor with confirm: true, or manually).";
+    }
     switch (status) {
         case "running":
             return "Bridge is ready. Proceed with live-only MCP tools.";
@@ -369,7 +392,66 @@ function bridgeStatusNextStep(status) {
                 "Bridge) and confirm it is started.";
     }
 }
-function bridgeStatusRecoveryHint(status) {
+/**
+ * specs/feedback.md 2026-08-24 — wire-contract staleness block.
+ *
+ * The field report: a blocker fixed and shipped on 2026-08-17 (registry tools
+ * rejecting the transport envelope keys, which made `editor_status` uncallable
+ * with default args) recurred against an installed bridge that still reported
+ * `bridgeVersion "1.0.0"` — the same string the FIXED source reports, because
+ * the package semver does not move for a wire-contract fix. "Your install is
+ * stale" and "this regressed" were therefore indistinguishable at the call
+ * site, and the agent had no way to pick between reinstalling and filing a bug.
+ *
+ * `BridgeSession.WireContract` is bumped for every observable change to the
+ * request/response contract, so comparing it against
+ * {@link EXPECTED_BRIDGE_WIRE_CONTRACT} answers that question directly. A
+ * bridge that predates the field reports no `wireContract` at all — `bridge`
+ * is then null and `stale` is true, which is the correct reading (it is older
+ * than revision 1 by definition).
+ *
+ * Returns null when /ping was unreachable: there is no bridge to compare, and a
+ * bogus "stale" on an offline bridge would be worse than silence.
+ */
+function wireContractBlock(reachable, reported) {
+    if (!reachable)
+        return null;
+    const bridge = typeof reported === "number" ? reported : null;
+    const stale = bridge === null || bridge < EXPECTED_BRIDGE_WIRE_CONTRACT;
+    return {
+        bridge,
+        expected: EXPECTED_BRIDGE_WIRE_CONTRACT,
+        stale,
+        note: stale
+            ? "The installed Unity bridge package is OLDER than this MCP server's wire " +
+                "contract" +
+                (bridge === null
+                    ? " (it does not report `wireContract` at all, so it predates revision 1)"
+                    : ` (revision ${bridge} vs ${EXPECTED_BRIDGE_WIRE_CONTRACT})`) +
+                ". A tool failing in a way the docs say is fixed is almost certainly " +
+                "this staleness, not a regression: reinstall/update the bridge package " +
+                "in Unity (Package Manager > the unity-open-mcp-bridge git URL) and " +
+                "retry before filing anything. bridgeVersion alone cannot tell you " +
+                "this — it does not move for a wire-contract fix."
+            : null,
+    };
+}
+function bridgeStatusRecoveryHint(status, wedge) {
+    if (status === "wedged") {
+        return wedge?.reason === "main_thread_wedged"
+            ? {
+                tool: "unity_open_mcp_editor_status",
+                reason: "Main thread wedged (likely a modal dialog): /ping answers but the " +
+                    "editor heartbeat stopped. No tool can dismiss a modal — an operator " +
+                    "must close it in the Unity UI, then editor_status confirms recovery.",
+            }
+            : {
+                tool: "unity_open_mcp_read_compile_errors",
+                reason: "editor_fd_exhaustion in the freshest Editor.log — the Editor answers " +
+                    "HTTP but can no longer build, so C# edits never take effect. Confirm " +
+                    "with read_compile_errors, then restart the Editor.",
+            };
+    }
     if (status === "dead_bridge") {
         return {
             tool: "unity_open_mcp_read_compile_errors",
@@ -388,6 +470,7 @@ export class ToolRouter {
     sessionState;
     onToolListChanged;
     hubBackend;
+    globalLogPathOverride;
     modelCache = new AssetModelCache();
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -444,7 +527,15 @@ export class ToolRouter {
     // 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) {
+    hubBackend = defaultHubBackend, 
+    // feedback-fable-04-08 §2b — injectable global Editor.log path for tests.
+    // Production leaves this undefined so resolveEditorLogPath computes the
+    // real platform global path; tests pass a path under their tmp sandbox so
+    // the freshness comparison does not consult the host machine's real
+    // ~/Library/Logs/Unity/Editor.log (which is newer than the artificial
+    // 1970-era mtimes the tests plant and would win the comparison, reading
+    // the wrong file).
+    globalLogPathOverride) {
         this.live = live;
         this.batch = batch;
         this.projectPath = projectPath;
@@ -452,6 +543,7 @@ export class ToolRouter {
         this.sessionState = sessionState;
         this.onToolListChanged = onToolListChanged;
         this.hubBackend = hubBackend;
+        this.globalLogPathOverride = globalLogPathOverride;
     }
     async route(toolName, args) {
         return this.routeCore(this.live, toolName, args);
@@ -478,10 +570,21 @@ export class ToolRouter {
         }
         // 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.
+        // the source selection internally and tags the payload `_source`
+        // ("offline" when it was served from the disk parser without touching the
+        // bridge; error results tag their origin too — "local" for caller-side
+        // validation, "offline" for a failed offline-first attempt with the
+        // bridge down). Derive `_route` from that tag: stamping route:"live"
+        // unconditionally mislabeled offline-served reads as bridge responses —
+        // contradictory metadata that pointed an agent's diagnostics at the
+        // bridge for data it never produced.
         if (isCompressible(toolName)) {
             const result = await routeCompressible(toolName, args, live, this.modelCache, this.projectPath);
-            return injectRouteMeta(result, { route: "live" });
+            const source = parseResultBody(result)?._source;
+            const meta = source === "offline" || source === "local"
+                ? { route: source }
+                : { route: "live" };
+            return injectRouteMeta(result, meta);
         }
         const canBatch = this.batch.isBatchTool(toolName);
         const isPing = toolName === "unity_open_mcp_ping";
@@ -528,10 +631,13 @@ export class ToolRouter {
             return this.batchPingResult();
         }
         const result = await this.batch.route(toolName, args);
-        return injectRouteMeta(result, {
+        // feedback-fable-04-08 §7 — when the batch fallback hit a live editor's
+        // project lock, the actionable signal is editor_busy, not live_unavailable.
+        const meta = this.rewriteEditorBusy(result, {
             route: "batch",
             fallbackReason: "live_unavailable",
         });
+        return injectRouteMeta(result, meta);
     }
     batchPingResult() {
         return {
@@ -546,6 +652,11 @@ export class ToolRouter {
                         mode: "batch",
                         compiling: false,
                         isPlaying: false,
+                        // feedback 2026-08-17 — provenance marker distinguishing this
+                        // synthesized fallback (no probe was possible; the live route was
+                        // unavailable) from the live route's verified probe answer
+                        // (source:"probe" + asOf).
+                        source: "unprobed",
                         _route: {
                             route: "batch",
                             fallbackReason: "live_unavailable",
@@ -556,6 +667,52 @@ export class ToolRouter {
             isError: false,
         };
     }
+    /**
+     * feedback-fable-04-08 §7 — when a `live_unavailable` batch fallback lands
+     * on `editor_instance_locked`, the message describes the BATCH SPAWNER's
+     * problem ("a live editor holds the project lock, so no headless spawn"),
+     * but the agent's actionable truth is "the editor is busy (TestRunner run /
+     * long import); retry later", not a lock conflict. Detect this case by
+     * inspecting the batch result for `error.code === "editor_instance_locked"`
+     * AND confirming a live PID still holds the project (a stale lock with no
+     * live PID is a genuine lock conflict — leave it as `live_unavailable`).
+     *
+     * Returns the rewritten meta (and the result unchanged — the lock error body
+     * is real and must stay intact) so the caller stamps it via injectRouteMeta.
+     * The live PID is surfaced as `editorPid` for agent correlation. Falls
+     * through unchanged when the code differs, no live PID exists, or the body
+     * is unparseable.
+     */
+    rewriteEditorBusy(result, meta) {
+        if (meta.fallbackReason !== "live_unavailable")
+            return meta;
+        const body = parseResultBody(result);
+        if (body === null)
+            return meta;
+        const err = body.error;
+        const code = typeof err === "object" && err !== null
+            ? err.code
+            : undefined;
+        if (code !== "editor_instance_locked")
+            return meta;
+        // Confirm a live editor actually holds the project. The batch pre-spawn
+        // lock check already read the lock, but a race (the editor quit between
+        // the batch check and here) or a corrupt lock must NOT be misreported as
+        // "busy" — fall through to the generic live_unavailable in that case.
+        try {
+            const lock = readInstanceLock(this.projectPath);
+            if (!lock?.pid || !isPidAlive(lock.pid))
+                return meta;
+            return {
+                route: "batch",
+                fallbackReason: "editor_busy",
+                editorPid: lock.pid,
+            };
+        }
+        catch {
+            return meta;
+        }
+    }
     async routeReadCompileErrors(args) {
         const tailBytes = typeof args.tail_bytes === "number" && args.tail_bytes >= 4096
             ? Math.min(Math.floor(args.tail_bytes), 1048576)
@@ -571,7 +728,7 @@ export class ToolRouter {
         // editor keeps writing. Pass the live PID from the instance lock so the
         // resolver can make the strong-signal decision.
         const livePid = this.resolveLiveEditorPid();
-        const resolvedLog = resolveEditorLogPath(this.projectPath, undefined, livePid);
+        const resolvedLog = resolveEditorLogPath(this.projectPath, undefined, livePid, this.globalLogPathOverride);
         const logPath = resolvedLog.path;
         const tail = readLogTail(logPath, tailBytes);
         if (tail.error) {
@@ -617,11 +774,6 @@ export class ToolRouter {
         // backward compatibility) so existing callers do not break.
         const health = summarizeProjectHealth(tail.content);
         const errors = health.compilerErrors;
-        const status = health.unhealthy
-            ? errors.length > 0
-                ? "compile_failed"
-                : "project_unhealthy"
-            : "no_errors_found";
         // specs/feedback.md 2026-07-05 — stale-log detection. When an assembly is
         // stuck in a failed-compile state, AssetDatabase.Refresh no-ops and the
         // log's most-recent CSxxxx block can reference on-disk source that has
@@ -644,12 +796,156 @@ export class ToolRouter {
         // newest Library/ScriptAssemblies/*.dll mtime against Assets/**/*.cs source
         // mtimes and surface staleAssembly when any source is newer than the DLL.
         const staleAsm = detectStaleAssembly(this.projectPath);
+        // specs/feedback.md 2026-08-14 — "these errors may predate your edits".
+        // Three consecutive reads returned the same error block for code that had
+        // already been fixed, with no staleness signal: Editor.log's FILE mtime
+        // was fresh (asset imports keep appending) while the error BLOCK inside it
+        // was old, so the staleLog heuristic could not fire. The built-assembly
+        // mtime is the anchor that works — a cited source newer than the newest
+        // built DLL proves no compile has COMPLETED since the edit.
+        const errorsPredateEdits = errors.length > 0
+            ? detectErrorsPredatingEdits(errors.map((e) => e.file), this.projectPath, staleAsm.dllMtimeMs)
+            : null;
+        // feedback-04-08-opus §2 — log-authorship cross-check. A batch run of a
+        // NEWER Unity writes a log whose errors (e.g. an API deprecation that is
+        // only an error on that version) CANNOT occur in the live editor. Parse the
+        // log header's version + batch-mode + date, compare against the live bridge
+        // version, and surface a mismatch so the agent does not "fix" 31 unrelated
+        // files or refuse to continue on errors that cannot occur here. The fields
+        // are always emitted when the header was parseable (so an agent can see the
+        // log was a batch run even when versions agree); the warning hint is added
+        // only on a real mismatch or a batch-mode log.
+        const authorship = parseLogAuthorship(tail.content);
+        const liveUnityVersion = this.resolveLiveUnityVersion();
+        const authorshipCheck = compareLogAuthorship(authorship, liveUnityVersion);
+        // feedback-fable-04-08 §4 — downgrade the top-level status when the errors
+        // may not apply to the running editor. An agent that trusts a
+        // `compile_failed` + `unhealthy: true` headline will start "fixing" 31
+        // phantom errors from a stale / batch-authored log. When EITHER the log is
+        // stale (a cited source is newer than the log) OR a version-mismatch is
+        // detected (a different Unity wrote the log), the verdict becomes
+        // `stale_log` — the errors[] are still attached as evidence, but the
+        // headline + status make clear they MUST NOT be acted on until a genuine
+        // recompile confirms them. The raw verdict (what the log itself says) is
+        // preserved in `logVerdict` for agents that want the literal signal.
+        const logVerdict = health.unhealthy
+            ? errors.length > 0
+                ? "compile_failed"
+                : "project_unhealthy"
+            : "no_errors_found";
+        const errorsMayNotApply = health.unhealthy &&
+            (!!staleLog || authorshipCheck.versionMismatch);
+        // feedback 2026-08-17 — a clean bill of health read from the ROTATED log
+        // is not a clean bill of health. When logSource is a prev_log_* value the
+        // resolver fell back to Editor-prev.log while a live Editor writes a
+        // different file; an agent reading only `status` got a false green. A
+        // no-errors read from a rotated log is explicitly `indeterminate`.
+        const prevLogRead = resolvedLog.reason.startsWith("prev_log_");
+        const status = errorsMayNotApply
+            ? "stale_log"
+            : logVerdict === "no_errors_found" && prevLogRead
+                ? "indeterminate"
+                : logVerdict;
+        // specs/feedback.md 2026-08-12 — partial-compile signal. Unity compiles
+        // assemblies in dependency order; when an early assembly fails the pipeline
+        // may not reach dependent ones, so the reported errors can be a SUBSET of
+        // the true error set. When there are errors AND the project has multiple
+        // compile assemblies, surface asmdefCount + assembliesWithErrors +
+        // partialCompileLikely so an agent does not treat `errorCount` as final
+        // (this is exactly the trap that masked 6 errors behind 1 during the
+        // input-simulation review).
+        // Only walk for asmdefs when there are errors — the signal is only
+        // meaningful with errors, and countProjectAsmdefs stats the whole Assets/
+        // tree synchronously (memoized per project, but still skip it when unused).
+        const hasErrors = errors.length > 0;
+        const asmdefs = hasErrors
+            ? countProjectAsmdefs(this.projectPath)
+            : { count: 0, sample: [] };
+        const partialCompileLikely = hasErrors && asmdefs.count > 1;
+        const assembliesWithErrors = partialCompileLikely
+            ? countAssembliesWithErrors(errors.map((e) => e.file), this.projectPath)
+            : 0;
+        // Headline assembly. Precedence (most severe first):
+        //   1. errorsMayNotApply — stale log / version mismatch: the errors may
+        //      not apply at all (feedback-fable-04-08 §4).
+        //   2. errorsPredateEdits — errors + a stale assembly: the error block
+        //      was written by a compile that predates the on-disk edits (no
+        //      compile has COMPLETED since: every built DLL is older than a cited
+        //      source). The log-mtime staleness heuristic cannot see this — asset
+        //      imports keep appending to Editor.log, so the FILE is fresh while
+        //      the error BLOCK inside it is old. Say so in the headline rather
+        //      than letting the agent re-read code it has already fixed
+        //      (specs/feedback.md 2026-08-14).
+        //   3. feedback 2026-08-17 — errors + staleAssembly WITHOUT the
+        //      cited-files proof: the whole-Assets scan still shows a source
+        //      newer than the newest built DLL, so the error block may come from
+        //      an earlier compile. The 2026-08-14 fix covered only the
+        //      errorsPredateEdits shape; this extends the headline caveat to the
+        //      staleAssembly shape (the field report's 12 stale CS errors had
+        //      staleAssembly:true but the headline stated them as fact).
+        //   4. indeterminate (feedback 2026-08-17) — no errors, but read from the
+        //      ROTATED log: not a verified clean bill of health.
+        //   5. the plain health headline.
+        const headline = errorsMayNotApply
+            ? `${errors.length} error(s) in Editor.log, but the log appears ` +
+                "STALE or authored by a different Unity — these errors may NOT " +
+                "apply to the running editor. Do NOT act on them until a genuine " +
+                `recompile (${toolHintReference("unity_open_mcp_recompile_scripts")}) ` +
+                "confirms them."
+            : errorsPredateEdits
+                ? `${health.headline} NOTE: these errors may PREDATE your edits — ` +
+                    `${errorsPredateEdits.files.length} cited source file(s) are newer ` +
+                    "than the newest built assembly, so no compile has completed since " +
+                    "you changed them. Force a recompile " +
+                    `(${toolHintReference("unity_open_mcp_recompile_scripts")}) and ` +
+                    "re-read before acting on them."
+                : hasErrors && staleAsm.staleAssembly
+                    ? `${health.headline} NOTE: the error block may PREDATE the current ` +
+                        `sources — ${staleAsm.newerSources.length} Assets/**/*.cs source(s) ` +
+                        "are newer than the newest built assembly, so these errors may come " +
+                        "from an earlier compile. Force a recompile " +
+                        `(${toolHintReference("unity_open_mcp_recompile_scripts")}) and ` +
+                        "re-read before acting on them."
+                    : status === "indeterminate"
+                        ? "No errors found, but this is NOT a verified clean bill of " +
+                            `health: the read came from the ROTATED log (${resolvedLog.reason === "prev_log_live_editor" ? "Editor-prev.log chosen because a live editor holds the project" : "Editor-prev.log fallback"}) ` +
+                            "while a live Editor may be writing a different log. Confirm via " +
+                            "the live bridge (unity_open_mcp_editor_status / a live tool " +
+                            "probe) or re-read after the Editor settles."
+                        : health.headline;
         return sourceResult({
             status,
-            unhealthy: health.unhealthy,
-            headline: health.headline,
+            // When the errors may not apply (stale log / version mismatch), the
+            // top-level verdict is downgraded to "stale_log" and unhealthy is
+            // suppressed so an agent branching on `unhealthy` does not treat
+            // phantom errors as a hard failure (feedback-fable-04-08 §4). The raw
+            // log verdict is preserved in `logVerdict` for callers that want the
+            // literal signal regardless of freshness.
+            unhealthy: errorsMayNotApply ? false : health.unhealthy,
+            headline,
+            // Raw verdict preserved whenever the top-level status was rewritten
+            // (stale_log downgrade OR the indeterminate prev-log case), so callers
+            // can still read what the log literally said.
+            ...(errorsMayNotApply || status === "indeterminate" ? { logVerdict } : {}),
             errorCount: errors.length,
             errors,
+            // specs/feedback.md 2026-08-12 — present only when there are errors AND
+            // the project has multiple compile assemblies. Unity's dependency-ordered
+            // pipeline means these errors may be a subset; fixing them lets dependent
+            // assemblies compile and may surface more. Re-check until errorCount is 0.
+            ...(partialCompileLikely
+                ? {
+                    partialCompileLikely: true,
+                    asmdefCount: asmdefs.count,
+                    // Distinct assemblies the reported errors span (null when none of
+                    // the cited files mapped to an asmdef — e.g. global/package code).
+                    assembliesWithErrors: assembliesWithErrors > 0 ? assembliesWithErrors : null,
+                    partialCompileHint: "Unity compiles assemblies in dependency order; the reported errors " +
+                        "may be a SUBSET — once these are fixed, dependent assemblies that " +
+                        "were not reached compile next and may surface additional errors. " +
+                        "Re-check read_compile_errors after each fix until errorCount is 0.",
+                }
+                : {}),
             // Package / assembly issues from the same log tail. Empty when the
             // only red flags are compiler errors (the common case).
             issues: health.issues,
@@ -681,6 +977,45 @@ export class ToolRouter {
                     staleAssemblyNewerSources: staleAsm.newerSources,
                 }
                 : {}),
+            // specs/feedback.md 2026-08-14 — machine-readable sibling of the
+            // headline caveat above. Present ONLY when errors were returned AND at
+            // least one file they cite is newer than the newest built assembly, so
+            // the error block cannot reflect the current source. Distinct from
+            // `staleLogSuspected` (log-file mtime) and `staleAssembly` (whole
+            // Assets/ scan): this names the cited files the agent is about to
+            // re-read.
+            ...(errorsPredateEdits
+                ? {
+                    errorsMayPredateEdits: true,
+                    errorsMayPredateEditsFiles: errorsPredateEdits.files,
+                    errorsMayPredateEditsHint: "These errors were parsed from a compile that ran BEFORE the " +
+                        "listed files were last edited (each is newer than the newest " +
+                        "Library/ScriptAssemblies/*.dll, so no compile has completed " +
+                        "since). Do not re-read or re-fix that code on the strength of " +
+                        "this block — force a recompile " +
+                        `(${toolHintReference("unity_open_mcp_recompile_scripts")}) ` +
+                        "and read again.",
+                }
+                : {}),
+            // feedback-04-08-opus §2 — log authorship. Emitted whenever the header
+            // was parseable (the live editor's long tail usually has no header, so
+            // these stay absent in the common case). On a version mismatch the hint
+            // says the errors CANNOT all occur in the live editor; on a batch-mode
+            // log it reminds the agent the errors are from a headless run.
+            ...(authorship.logUnityVersion !== null || authorship.logBatchMode !== null
+                ? {
+                    logUnityVersion: authorship.logUnityVersion,
+                    liveUnityVersion: authorshipCheck.liveUnityVersion,
+                    logBatchMode: authorship.logBatchMode,
+                    logDate: authorship.logDate,
+                    ...(authorshipCheck.hint
+                        ? {
+                            logAuthorshipMismatch: authorshipCheck.versionMismatch,
+                            logAuthorshipHint: authorshipCheck.hint,
+                        }
+                        : {}),
+                }
+                : {}),
         }, "offline");
     }
     // Resolve the live Unity Editor PID for this project from the instance lock,
@@ -702,6 +1037,27 @@ export class ToolRouter {
         }
         return undefined;
     }
+    // feedback-04-08-opus §2 — resolve the live bridge's Unity version from the
+    // instance lock, so read_compile_errors can cross-check the LOG's version
+    // header against the version of the editor that is actually running. A batch
+    // run of a NEWER Unity leaves a log whose errors cannot occur in the live
+    // editor; without this check the tool would surface them as current. Returns
+    // null when no live editor / no version recorded (the benign case — no
+    // version to compare against, so no false mismatch fires).
+    resolveLiveUnityVersion() {
+        if (!this.projectPath)
+            return null;
+        try {
+            const lock = readInstanceLock(this.projectPath);
+            if (lock && lock.pid && isPidAlive(lock.pid) && lock.unityVersion) {
+                return lock.unityVersion;
+            }
+        }
+        catch {
+            // Unreadable/missing lock → no live version known.
+        }
+        return null;
+    }
     async routeListAssets(args) {
         try {
             const result = await listAssetsOffline({
@@ -753,7 +1109,13 @@ export class ToolRouter {
         const maxEvents = typeof args.max_events === "number" && args.max_events > 0
             ? Math.min(args.max_events, 1000)
             : 50;
-        const result = this.eventStream.pull(maxEvents);
+        // feedback #8 — forward the caller-supplied subscriber id so each agent
+        // session gets its own read cursor (a fresh subscriber starts at the
+        // current high-water mark and does not replay the shared queue's backlog).
+        const subscriber = typeof args.subscriber === "string" && args.subscriber.length > 0
+            ? args.subscriber
+            : undefined;
+        const result = this.eventStream.pull(maxEvents, subscriber);
         return {
             content: [{ type: "text", text: JSON.stringify(result) }],
             isError: false,
@@ -764,6 +1126,12 @@ export class ToolRouter {
             ? args.kind
             : undefined;
         const includePlanned = args.include_planned !== false;
+        // specs/feedback.md 2026-08-24 — the tool surface defaults to `compact`
+        // (the unfolded catalog is ~513 KB, which overflows a typical harness
+        // per-result ceiling). `buildCapabilities` itself keeps returning the full
+        // shape so its other caller (generate_skill) is unaffected; the fold is a
+        // view applied here.
+        const profile = isOutputProfile(args.profile) ? args.profile : "compact";
         // M18 Plan 2 / T18.2.3 — when the bridge is live, probe its compiled-
         // state tool inventory so per-group `available` reflects whether each
         // domain dependency compiled in (e.g. UNITY_OPEN_MCP_EXT_NAVIGATION).
@@ -789,7 +1157,11 @@ export class ToolRouter {
             fixes: FIX_CATALOG,
             availableBridgeTools,
         }, { kind, includePlanned });
-        return sourceResult(result, "local");
+        return sourceResult(viewCapabilities(result, {
+            profile,
+            page_size: typeof args.page_size === "number" ? args.page_size : undefined,
+            cursor: typeof args.cursor === "string" ? args.cursor : undefined,
+        }), "local");
     }
     async routeListRules(args) {
         const assetKind = typeof args.asset_kind === "string" ? args.asset_kind : undefined;
@@ -1293,8 +1665,52 @@ export class ToolRouter {
             if (proc)
                 unityProcessPid = proc.pid;
         }
+        // specs/feedback.md 2026-08-14 — wedge detection, evaluated BEFORE the
+        // existing token ladder because both wedges masquerade as one of its
+        // healthy-looking outcomes.
+        //
+        // (a) main_thread_wedged. `dead_bridge` means "live PID + stale
+        //     heartbeat". A modal dialog produces exactly that (the heartbeat is
+        //     written from EditorApplication.update, which a blocked pump stops
+        //     running) — but a dead bridge ASSEMBLY cannot answer /ping at all,
+        //     because the listener lives in the assembly that failed to compile.
+        //     So a reachable /ping alongside a stale heartbeat rules out the
+        //     safe-mode diagnosis and identifies a stalled main thread instead.
+        // (b) editor_fd_exhaustion. Process, heartbeat and /ping all survive a
+        //     dead build driver, so nothing in the existing ladder can see it.
+        //     One regex over the freshest log tail can (the same scan
+        //     read_compile_errors runs), and it only runs when the ladder would
+        //     otherwise report a healthy editor — the offline/stopped paths have
+        //     no editor to be wedged.
+        let wedge = null;
+        if (classification === "dead_bridge" && pingReachable) {
+            wedge = {
+                reason: "main_thread_wedged",
+                detail: "The instance lock's heartbeat is stale (the editor main thread stopped " +
+                    "ticking) but the bridge listener still answers /ping. A failed bridge " +
+                    "assembly would take the listener down with it, so this is a blocked main " +
+                    "thread — almost always a modal dialog — not Safe Mode.",
+            };
+        }
+        else if (pingReachable && connected) {
+            const fd = scanForFdExhaustion(this.projectPath, this.resolveLiveEditorPid(), this.globalLogPathOverride);
+            if (fd.present) {
+                wedge = {
+                    reason: "editor_fd_exhaustion",
+                    detail: "The freshest Editor.log carries the Bee build-driver file-descriptor " +
+                        "exhaustion signature. The Editor answers HTTP but cannot build: " +
+                        "Library/ScriptAssemblies stops updating, so C# edits never take effect " +
+                        "and execute_csharp keeps running the previous assembly.",
+                    ...(fd.logPath ? { logPath: fd.logPath } : {}),
+                    ...(fd.raw ? { raw: fd.raw } : {}),
+                };
+            }
+        }
         let status;
-        if (classification === "dead_bridge") {
+        if (wedge !== null) {
+            status = "wedged";
+        }
+        else if (classification === "dead_bridge") {
             status = "dead_bridge";
         }
         else if (compiling) {
@@ -1336,7 +1752,13 @@ export class ToolRouter {
             // Safe Mode / compile failure", not the generic "stopped" the bare
             // status used to suggest.
             classification,
-            recoveryHint: bridgeStatusRecoveryHint(status),
+            recoveryHint: bridgeStatusRecoveryHint(status, wedge),
+            // specs/feedback.md 2026-08-14 — present ONLY when the editor is wedged.
+            // `classification` keeps mirroring the instance lock verbatim (healthy |
+            // reloading | dead_bridge | gone) so that contract is unchanged; the
+            // wedge is carried by the tool's own `status` token plus this block, and
+            // `ready` is false either way.
+            ...(wedge !== null ? { wedged: wedge } : {}),
             instance: {
                 lockPath: lockOnDisk,
                 classification,
@@ -1354,10 +1776,15 @@ export class ToolRouter {
                     isPlaying: pingBody?.isPlaying ?? null,
                     unityVersion: pingBody?.unityVersion ?? null,
                     bridgeVersion: pingBody?.bridgeVersion ?? null,
+                    wireContract: pingBody?.wireContract ?? null,
                     mode: pingBody?.mode ?? null,
                 }
                 : { reachable: false },
-            nextStep: bridgeStatusNextStep(status),
+            // specs/feedback.md 2026-08-24 — null when /ping was unreachable; a
+            // `stale: true` block is the signal to reinstall the Unity package
+            // rather than file a regression.
+            wireContract: wireContractBlock(pingReachable, pingBody?.wireContract),
+            nextStep: bridgeStatusNextStep(status, wedge),
         };
         // bridge_status never reports an error — even a stopped bridge is a
         // successful status read. _source=local because the synthesis happens in
@@ -1405,12 +1832,14 @@ export class ToolRouter {
         //    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, undefined, this.resolveLiveEditorPid()).path;
+        const logPath = resolveEditorLogPath(this.projectPath, undefined, this.resolveLiveEditorPid(), this.globalLogPathOverride).path;
         const tail = readLogTail(logPath, DEFAULT_LOG_TAIL_BYTES);
         let signaturePresent = false;
+        let signatureSource = null;
         let logWarning = null;
         if (tail.error || !tail.exists) {
-            // Without the log we cannot confirm the signature — refuse for safety.
+            // Without the log we cannot confirm the signature from the file. The
+            // live-console fallback below may still recover it.
             logWarning = tail.error
                 ? `Editor.log unreadable at ${logPath}: ${tail.error}`
                 : `No Editor.log found at ${logPath}.`;
@@ -1418,7 +1847,10 @@ export class ToolRouter {
         else {
             const issues = extractProjectHealthIssues(tail.content);
             signaturePresent = issues.some((i) => i.kind === "editor_fd_exhaustion");
-            if (!signaturePresent) {
+            if (signaturePresent) {
+                signatureSource = "editor_log";
+            }
+            else {
                 logWarning =
                     "The editor_fd_exhaustion signature is NOT present in the recent " +
                         "Editor.log tail. The Editor may be slow/stuck for a different " +
@@ -1427,34 +1859,87 @@ export class ToolRouter {
                         "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.
+        // feedback-fable-04-08 §2b — live-console signature fallback. When the log
+        // file did not carry the signature (it may be the wrong/stale log for the
+        // running session, or the bridge is still up and the Bee exception is only
+        // in the live console via LogEntries), probe the bridge's console read as a
+        // secondary signature source. The fd-exhaustion exception is raised into
+        // the live Unity console independently of whichever Editor.log file the
+        // resolver picked, so this catches the case the file read missed. The
+        // bridge is usually down by full fd-exhaustion, so this is opportunistic —
+        // a failure here leaves the file-based verdict standing.
+        if (!signaturePresent) {
+            try {
+                const liveAvailable = await live.isLiveAvailable();
+                if (liveAvailable) {
+                    const consoleResult = await live.route("unity_senses_read_console", { max_entries: 200, type: "error", detail: "verbose" });
+                    const consoleBody = parseResultBody(consoleResult);
+                    const text = this.serializeConsoleEntries(consoleBody);
+                    if (text) {
+                        const liveIssues = extractProjectHealthIssues(text);
+                        if (liveIssues.some((i) => i.kind === "editor_fd_exhaustion")) {
+                            signaturePresent = true;
+                            signatureSource = "live_console";
+                            logWarning = null;
+                        }
+                    }
+                }
+            }
+            catch {
+                // Bridge unreachable (expected on fd-exhaustion). The file-based
+                // verdict above is the authoritative fallback.
+            }
+        }
+        // 2. Resolve the live Unity PID. feedback #2 (2026-08-06): the instance
+        //    lock's `pid` is authoritative — the bridge only writes it from the
+        //    main interactive editor (it early-returns in worker/batch processes),
+        //    while the process scan could return an AssetImportWorker child that
+        //    shares the project path. Prefer the lock PID when it is live; fall
+        //    back to the scan (which now also excludes AssetImportWorker children)
+        //    only when no live lock PID exists.
         let pid = null;
-        try {
-            const proc = findUnityForProject(this.projectPath);
-            pid = proc ? proc.pid : null;
+        let pidSource = null;
+        const lockPid = this.resolveLiveEditorPid();
+        if (lockPid !== undefined) {
+            pid = lockPid;
+            pidSource = "instance_lock";
         }
-        catch {
-            pid = null;
+        else {
+            try {
+                const proc = findUnityForProject(this.projectPath);
+                if (proc) {
+                    pid = proc.pid;
+                    pidSource = "process_scan";
+                }
+            }
+            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.
+        //    preview before committing. feedback #2: include the PID source and
+        //    the resolved process's command line so a misattribution (e.g. an
+        //    AssetImportWorker child) is visible before confirm.
         if (!confirm) {
+            const processCommandLine = pid !== null ? readProcessCommandLine(pid) : null;
             return sourceResult({
                 action: "restart_editor",
                 confirm: false,
                 dryRun: true,
                 signaturePresent,
+                ...(signatureSource !== null ? { signatureSource } : {}),
                 ...(pid !== null ? { wouldKillPid: pid } : {}),
+                ...(pidSource !== null ? { pidSource } : {}),
+                ...(processCommandLine !== null ? { processCommandLine } : {}),
                 ...(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.",
+                    "can destroy unsaved scene work and in-flight asset imports. " +
+                    "Verify processCommandLine targets the main editor, not an " +
+                    "AssetImportWorker child.",
             }, "local");
         }
         // 4. Confirmed-path refusals. Each guard surfaces a structured code so
@@ -1510,10 +1995,10 @@ export class ToolRouter {
         }
         // 6. Kill the Editor.
         const kill = await killEditorProcess(pid, graceMs);
-        return this.restartEditorKillResponse(pid, graceMs, kill, dirtyScenesWarning);
+        return this.restartEditorKillResponse(pid, graceMs, kill, dirtyScenesWarning, signatureSource);
     }
     /** Build the confirmed-kill response from a {@link KillResult}. */
-    restartEditorKillResponse(pid, graceMs, kill, dirtyScenesWarning) {
+    restartEditorKillResponse(pid, graceMs, kill, dirtyScenesWarning, signatureSource) {
         if (kill.terminated) {
             return sourceResult({
                 action: "restart_editor",
@@ -1523,6 +2008,7 @@ export class ToolRouter {
                 method: kill.method,
                 elapsedMs: kill.elapsedMs,
                 graceMs,
+                ...(signatureSource !== null ? { signatureSource } : {}),
                 ...(dirtyScenesWarning !== null
                     ? {
                         dirtyScenesWarning,
@@ -1567,6 +2053,33 @@ export class ToolRouter {
             ],
         }, "local", true);
     }
+    /**
+     * Flatten a unity_senses_read_console result body into a single string the
+     * health-issue extractor can scan for the fd-exhaustion signature. The
+     * console result is a JSON object with an `entries[]` array of
+     * `{ message, stack, ... }`; we join message + stack so the Bee driver's
+     * `Could not register to wait for file descriptor N` frame (which lives in
+     * the stack trace) is reachable by {@link extractProjectHealthIssues}.
+     * Returns "" when the body has no entries.
+     */
+    serializeConsoleEntries(body) {
+        if (!body || typeof body !== "object")
+            return "";
+        const entries = body.entries;
+        if (!Array.isArray(entries))
+            return "";
+        const parts = [];
+        for (const ent of entries) {
+            if (!ent || typeof ent !== "object")
+                continue;
+            const e = ent;
+            if (typeof e.message === "string")
+                parts.push(e.message);
+            if (typeof e.stack === "string")
+                parts.push(e.stack);
+        }
+        return parts.join("\n");
+    }
     /**
      * 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
@@ -1580,20 +2093,27 @@ export class ToolRouter {
      * 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.
+        // 1. Resolve the PID. An explicit pid arg wins; otherwise prefer the
+        //    instance-lock PID (authoritative main editor — feedback #2) and fall
+        //    back to the process scan (which excludes AssetImportWorker children).
+        //    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;
+            const lockPid = this.resolveLiveEditorPid();
+            if (lockPid !== undefined) {
+                pid = lockPid;
             }
-            catch {
-                pid = null;
+            else {
+                try {
+                    const proc = findUnityForProject(this.projectPath);
+                    pid = proc ? proc.pid : null;
+                }
+                catch {
+                    pid = null;
+                }
             }
         }
         if (pid === null) {
@@ -1608,25 +2128,42 @@ export class ToolRouter {
                 },
             }, "local", true);
         }
-        // 2. Probe + record the sample. A failed probe still records a sample
+        // 2. Resolve the configured fd ceiling (default 1024, overridable per
+        //    project via `.unity-open-mcp/settings.json` for runtimes whose
+        //    internal limit differs from Mono's classic 1024). Read fresh —
+        //    resource_pressure is called rarely, and this lets an operator change
+        //    the setting without restarting the MCP server.
+        const { ceiling, source: ceilingSource } = readFdCeiling(this.projectPath);
+        // 3. 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 approximate = "approximate" in probe ? probe.approximate : false;
+        const headroom = computeFdHeadroom(count, approximate, ceiling);
         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 trend = analyzeFdTrend(samples, ceiling);
+        // 4. Decide whether to raise an operator warning. For an fd-heavy project
+        //    the OS-level count legitimately sits OVER the Mono-ceiling proxy on a
+        //    fresh healthy process (lsof counts mmap'd assets / file watchers /
+        //    FileStream handles that Mono's IOSelector never registers), so an
+        //    absolute `over_ceiling` state is NOT an alarm by itself. Alarm only on:
+        //    - a monotonic leak (the actionable trend signal), or
+        //    - approaching the ceiling from below (warn/critical).
+        //    A merely `rising` or stable/no-history over-ceiling process gets a
+        //    `pressureNote` instead. `rising` is any net-positive delta that is NOT a
+        //    qualifying leak — it fires on ordinary drift, so it must NOT alarm on its
+        //    own (the prior over_ceiling+rising alarm re-cried wolf on every sample
+        //    after the first).
         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"
+        const shouldWarn = trend.state === "leaking" ||
+            headroom.state === "warn" ||
+            headroom.state === "critical";
+        const warningState = shouldWarn
             ? {
                 level: headroom.state === "critical"
                     ? "critical"
@@ -1635,26 +2172,44 @@ export class ToolRouter {
                         : "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 ` +
+                        `the ${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.`
+                        ? headroom.state === "over_ceiling"
+                            ? `Editor fd usage (${count}) is ABOVE the ${ceiling}-descriptor ` +
+                                `ceiling and climbing monotonically (leak in progress): trend ` +
+                                `delta ${trend.delta} over ${trend.sampleCount} sample(s). The ` +
+                                `count has already crossed the ceiling proxy — save scene work ` +
+                                `and restart Unity via the Hub now.`
+                            : `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 ${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.`,
+                            `the ${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;
+        // Informational (non-alarming) note for the over-ceiling-but-stable case.
+        const pressureNote = !shouldWarn && headroom.state === "over_ceiling"
+            ? `OS-level fd count (${count}) is above the ${ceiling}-descriptor ceiling ` +
+                `proxy, but lsof / HandleCount count ALL OS file descriptors (mmap'd ` +
+                `assets, file watchers, regular FileStream handles) while only ` +
+                `Mono-IOSelector-registered descriptors (sockets/pipes under async IO) ` +
+                `count toward the real trip point. For an asset-heavy project this is ` +
+                `expected on a healthy process. Treat this as a concern ONLY if the trend ` +
+                `becomes a monotonic leak (leaking) — re-sample after the next domain ` +
+                `reload to establish one.`
+            : null;
         return sourceResult({
             pid,
             fdCount: count,
             fdMethod,
             approximate,
-            ceiling: FD_CEILING,
+            ceiling,
+            ceilingSource,
             headroom: headroom.headroom,
             pressureRatio: headroom.pressureRatio,
             state: headroom.state,
@@ -1685,6 +2240,7 @@ export class ToolRouter {
                     ],
                 }
                 : {}),
+            ...(pressureNote !== null ? { pressureNote } : {}),
         }, "local");
     }
     // ── M26 Plan 2 — Unity Hub control (local-routed) ────────────────
@@ -1975,6 +2531,9 @@ export class ToolRouter {
                 routeMeta = { route: "batch", fallbackReason: "live_unavailable" };
             }
         }
+        // feedback-fable-04-08 §7 — rewrite the generic live_unavailable to
+        // editor_busy when the batch hit a live editor's project lock.
+        routeMeta = this.rewriteEditorBusy(raw, routeMeta);
         const body = parseResultBody(raw);
         if (body === null) {
             // Body not parseable — fall back to the legacy injectRouteMeta path so
@@ -2030,7 +2589,14 @@ export class ToolRouter {
             }
             else {
                 raw = await this.batch.route("unity_open_mcp_scene_get_data", bridgeArgs);
-                raw = injectRouteMeta(raw, { route: "batch", fallbackReason: "live_unavailable" });
+                // feedback-fable-04-08 §7 — rewrite to editor_busy when the batch hit
+                // a live editor's project lock. Compute the meta from the raw result
+                // (which carries the editor_instance_locked error) before stamping.
+                const meta = this.rewriteEditorBusy(raw, {
+                    route: "batch",
+                    fallbackReason: "live_unavailable",
+                });
+                raw = injectRouteMeta(raw, meta);
             }
         }
         if (!wantPaging)
@@ -2081,12 +2647,25 @@ function pageSceneNodes(body, pageSize, cursor) {
     void roots;
     void rootGameObjects;
     void nodes;
-    void truncated;
+    // `truncated` is read at the source-truncated carry-through below, so it is
+    // not voided with the other intentionally-discarded scene fields.
     void moreHidden;
     void _existing;
     // Pull the top-level meta (everything except `scene`, which we rebuild).
-    const { scene: _s, ...topMeta } = body;
+    // B-N21 — strip the structural fields from the TOP level too. For a
+    // pre-unwrapped body (roots/rootGameObjects at the top level, no `scene`
+    // wrapper — the fallback flattenSceneBody handles), `scene` above resolves
+    // to {} and strips nothing, so spreading the raw remainder of `body` used
+    // to carry the ENTIRE unpaged roots array into the response alongside the
+    // page — paging never bounded the payload for that shape. flattenSceneBody
+    // already consumed those fields; drop them wherever they live.
+    const { scene: _s, roots: topRoots, rootGameObjects: topRootGameObjects, nodes: topNodes, truncated: topTruncated, moreHidden: topMoreHidden, pagination: _topExisting, ...topMeta } = body;
     void _s;
+    void topRoots;
+    void topRootGameObjects;
+    void topNodes;
+    void topMoreHidden;
+    void _topExisting;
     const result = {
         ...topMeta,
         status: body.status ?? "ok",
@@ -2099,8 +2678,10 @@ function pageSceneNodes(body, pageSize, cursor) {
     // 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;
+    // For a pre-unwrapped body the count lives at the top level (B-N21).
+    const sourceTruncated = typeof truncated === "number" ? truncated : topTruncated;
+    if (typeof sourceTruncated === "number" && sourceTruncated > 0) {
+        result.scene.truncated = sourceTruncated;
     }
     return attachPagination(result, block);
 }