unity-open-mcp 1.0.0 → 1.2.3

package/dist/tool-router.js

@@ -1,6 +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, parseLogAuthorship, compareLogAuthorship } 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";
@@ -8,11 +10,12 @@ 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, TYPED_EDITOR_ACTIVATE_INSTRUCTION } from "./constants.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
@@ -51,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
@@ -339,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.";
@@ -371,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",
@@ -490,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";
@@ -561,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",
@@ -700,6 +796,16 @@ 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
@@ -729,7 +835,17 @@ export class ToolRouter {
             : "no_errors_found";
         const errorsMayNotApply = health.unhealthy &&
             (!!staleLog || authorshipCheck.versionMismatch);
-        const status = errorsMayNotApply ? "stale_log" : logVerdict;
+        // 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
@@ -749,6 +865,54 @@ export class ToolRouter {
         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,
             // When the errors may not apply (stale log / version mismatch), the
@@ -758,14 +922,11 @@ export class ToolRouter {
             // 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 } : {}),
+            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
@@ -816,6 +977,26 @@ 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
@@ -945,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).
@@ -970,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;
@@ -1474,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) {
@@ -1517,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,
@@ -1535,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
@@ -1894,74 +2140,110 @@ export class ToolRouter {
         const probe = countFileDescriptors(pid);
         const count = probe.count;
         const approximate = "approximate" in probe ? probe.approximate : false;
-        const headroom = computeFdHeadroom(count, approximate, ceiling);
+        const partial = "partial" in probe ? probe.partial === true : false;
+        // The threshold softening is about WHAT the metric counts, not about how
+        // precise the number is. Only Windows HandleCount counts more than fds; a
+        // timed-out lsof is imprecise but still counts real fds (a lower bound),
+        // so it takes the normal warn/critical thresholds — softening it made a
+        // partial 900/1024 report `ok` on the very platform this tool targets.
+        const broaderThanFds = probe.method === "handle_count";
+        const headroom = computeFdHeadroom(count, broaderThanFds, ceiling);
         const ts = Date.now();
         this.sessionState.recordFdSample({ ts, pid, count });
         const samples = this.sessionState.fdSamplesSnapshot();
         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:
+        // Samples are per-PID (as the tool description states): after an Editor
+        // restart the ring still holds the previous process's entries — report
+        // only this PID's series. The trend already analyzes the latest PID only.
+        const pidSamples = samples.filter((s) => s.pid === pid);
+        // 4. Decide whether to raise an operator warning. Alarm on:
+        //    - a real fd count at/past the ceiling (`over_ceiling` from lsof//proc):
+        //      POSIX allocates the lowest free descriptor number, so every NEW
+        //      descriptor now lands above the ceiling and the next IOSelector
+        //      registration (any async pipe/socket — e.g. the Bee build driver)
+        //      can hang the Editor. A fresh healthy Unity 6 editor sits at ~160
+        //      fds; real counts past 1024 are never legitimate now that
+        //      countLsofFdRows excludes the cwd/txt/mmap rows that once inflated
+        //      the count.
         //    - 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).
+        //    The one downgraded case is a Windows HandleCount probe over the
+        //    ceiling: handle counts cover kernel/GDI/user objects and routinely
+        //    exceed 1024 on a healthy process, so it gets a `pressureNote` and
+        //    alarms only on the trend. `rising` is any net-positive delta that is
+        //    NOT a qualifying leak — it fires on ordinary drift, so it never
+        //    alarms on its own.
         const fdMethod = probe.method;
         const probeReason = "reason" in probe ? probe.reason : null;
         const probeMessage = "message" in probe ? probe.message : null;
-        const shouldWarn = trend.state === "leaking" ||
+        // A partial (timed-out) lsof listing is a LOWER BOUND on real fds, so an
+        // over-ceiling verdict from it still stands; only the Windows HandleCount
+        // metric measures something broader than fds. Same predicate that picked
+        // the headroom thresholds above, so the two can never disagree.
+        const overCeilingRealFds = headroom.state === "over_ceiling" && !broaderThanFds;
+        const shouldWarn = overCeilingRealFds ||
+            trend.state === "leaking" ||
             headroom.state === "warn" ||
             headroom.state === "critical";
         const warningState = shouldWarn
             ? {
-                level: headroom.state === "critical"
+                level: headroom.state === "critical" || overCeilingRealFds
                     ? "critical"
                     : trend.state === "leaking"
                         ? "leaking"
                         : "warn",
-                message: headroom.state === "critical"
-                    ? `Editor fd usage is at ${Math.round(headroom.pressureRatio * 100)}% of ` +
-                        `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"
-                        ? 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 ` +
-                            `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.`,
+                message: overCeilingRealFds
+                    ? `Editor fd count (${count}) is at or above the ${ceiling}-descriptor ` +
+                        `Mono IOSelector ceiling. Every newly allocated descriptor number now ` +
+                        `lands above the ceiling, so the next async pipe/socket registration ` +
+                        `(e.g. the Bee build driver's IPC) can hang the Editor mid-build` +
+                        (trend.state === "leaking"
+                            ? ` — and the count is still climbing (trend delta ${trend.delta} ` +
+                                `over ${trend.sampleCount} sample(s))`
+                            : "") +
+                        `. Save scene work and restart Unity via the Hub now.`
+                    : headroom.state === "critical"
+                        ? broaderThanFds
+                            ? `Windows handle count is at ${Math.floor(headroom.pressureRatio * 100)}% ` +
+                                `of the ${ceiling}-descriptor ceiling proxy. HandleCount covers ` +
+                                `kernel/GDI/user objects — far broader than fds — so this is a soft ` +
+                                `signal, not fd risk: watch the trend, and treat a monotonic climb ` +
+                                `(trend.state "leaking") as the real alarm.`
+                            : `Editor fd usage is at ${Math.floor(headroom.pressureRatio * 100)}% of ` +
+                                `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"
+                            ? headroom.state === "over_ceiling"
+                                ? `Editor handle count (${count}) is ABOVE the ${ceiling} ceiling ` +
+                                    `proxy and climbing monotonically (leak in progress): trend ` +
+                                    `delta ${trend.delta} over ${trend.sampleCount} sample(s). ` +
+                                    `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.floor(headroom.pressureRatio * 100)}% of ` +
+                                `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.
+        // Informational note for the remaining soft case: a Windows HandleCount
+        // over the ceiling proxy with no qualifying leak trend.
         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.`
+            ? `Windows handle count (${count}) is above the ${ceiling} fd-ceiling ` +
+                `proxy, but HandleCount covers kernel/GDI/user objects — far broader ` +
+                `than Unix fds — so this is expected on a healthy process. Treat it 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,
+            ...(partial ? { partial } : {}),
             ceiling,
             ceilingSource,
             headroom: headroom.headroom,
@@ -1969,12 +2251,12 @@ export class ToolRouter {
             state: headroom.state,
             reliable: headroom.reliable,
             trend,
-            samples: samples.map((s) => ({
+            samples: pidSamples.map((s) => ({
                 ts: s.ts,
                 pid: s.pid,
                 count: s.count,
             })),
-            sampleCount: samples.length,
+            sampleCount: pidSamples.length,
             launchContextCaveat: LAUNCH_CONTEXT_CAVEAT,
             ...(probeReason !== null ? { probeReason } : {}),
             ...(probeMessage !== null ? { probeMessage } : {}),