unity-open-mcp 0.9.0 → 1.0.0

package/dist/tool-router.js

@@ -1,7 +1,8 @@
 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, parseLogAuthorship, compareLogAuthorship } from "./unity-log.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";
@@ -11,8 +12,8 @@ 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, TYPED_EDITOR_ACTIVATE_INSTRUCTION } 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 +39,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 = {
@@ -388,6 +390,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 +447,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 +463,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);
@@ -528,10 +540,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 {
@@ -556,6 +571,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 +632,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 +678,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 +700,91 @@ 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);
+        // 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);
+        const status = errorsMayNotApply ? "stale_log" : 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;
         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: 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 (unity_open_mcp_recompile_scripts, in the typed-editor " +
+                    `group — ${TYPED_EDITOR_ACTIVATE_INSTRUCTION} first) confirms them.`
+                : health.headline,
+            ...(errorsMayNotApply ? { 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 +816,25 @@ export class ToolRouter {
                     staleAssemblyNewerSources: staleAsm.newerSources,
                 }
                 : {}),
+            // 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 +856,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 +928,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,
@@ -1405,12 +1586,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 +1601,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 +1613,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 +1749,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 +1762,7 @@ export class ToolRouter {
                 method: kill.method,
                 elapsedMs: kill.elapsedMs,
                 graceMs,
+                ...(signatureSource !== null ? { signatureSource } : {}),
                 ...(dirtyScenesWarning !== null
                     ? {
                         dirtyScenesWarning,
@@ -1567,6 +1807,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 +1847,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 +1882,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 +1926,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 +1994,7 @@ export class ToolRouter {
                     ],
                 }
                 : {}),
+            ...(pressureNote !== null ? { pressureNote } : {}),
         }, "local");
     }
     // ── M26 Plan 2 — Unity Hub control (local-routed) ────────────────
@@ -1975,6 +2285,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 +2343,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 +2401,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 +2432,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);
 }