unity-open-mcp 0.4.1 → 0.6.1

package/dist/live-client.js

@@ -3,6 +3,8 @@ import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "nod
 import { join } from "node:path";
 import { pollAndDismissDialogs, readDismissConfig, } from "./dialog-dismiss.js";
 import { readInstanceLock, classifyInstance, lockPath, isPidAlive, statusDir, hasRecentPendingTestRun } from "./instance-discovery.js";
+import { bridgeBaseUrl, BRIDGE_DEFAULT_TIMEOUT_MS, PORT_ENV_VAR, PROJECT_PATH_ENV_VAR, } from "./constants.js";
+import { findUnityForProject } from "./running-unity.js";
 import { makeErrorResult } from "./results.js";
 import { checkBridgeCompat, isVersionCheckSuppressed, } from "./compat.js";
 // M23 Plan 3 — structured retry policy + env-overridable tunables. Replaces
@@ -20,17 +22,9 @@ import { lifecycleFor } from "./capabilities/lifecycle.js";
 // fair round-robin queue can schedule across agents).
 import { PROCESS_AGENT_ID } from "./agent-identity.js";
 const PING_TIMEOUT_MS = 5_000;
-// The bridge's default per-tool wait before IT gives up and returns a timeout
-// envelope (packages/bridge/Editor/Bridge/BridgeRequestBody.cs
-// DefaultTimeoutMs). The client fetch timeout must never preempt this — if the
-// client aborts first it re-POSTs while the bridge is still processing the
-// original Work, manufacturing duplicate side-effects (specs/feedback.md entry
-// 4B/4A). postTool floors its fetch timeout at BRIDGE_DEFAULT_TIMEOUT_MS +
-// slack so a small/absent timeout_ms can't make the client give up before the
-// bridge. Kept as a literal here (not imported from the C# side) because the
-// bridge assembly isn't readable from the TS server; the cross-reference above
-// is the contract — bump both together.
-const BRIDGE_DEFAULT_TIMEOUT_MS = 30_000;
+// BRIDGE_DEFAULT_TIMEOUT_MS now lives in constants.ts (single source shared
+// with the bridge C# parity test). The client fetch timeout must never
+// preempt the bridge's default wait — see constants.ts for the contract.
 const DIRECT_RESPONSE_TOOLS = new Set([
     "unity_open_mcp_validate_edit",
     "unity_open_mcp_checkpoint_create",
@@ -62,6 +56,10 @@ const DIRECT_RESPONSE_TOOLS = new Set([
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+const COMPILE_REPOST_SENTINEL = { __compileRepost: 0 };
+function isCompileRepostSentinel(v) {
+    return typeof v === "object" && v !== null && "__compileRepost" in v;
+}
 /**
  * Decide whether {@link LiveClient#postTool}'s catch block should re-POST after
  * a transient fetch failure. Exported so the retry policy is unit-testable in
@@ -104,9 +102,9 @@ export function shouldRetryPostAfterFailure(err, endpointChanged) {
 const OFFLINE_HINT = "Ensure the Unity Editor is open with the Agent Bridge running. " +
     "The bridge port is per-project (20000 + sha256(projectPath) % 10000), not " +
     "fixed — if Unity is open the MCP server may be aimed at the wrong port. " +
-    "Check the instance lock at ~/.unity-open-mcp/instances/<sha256(projectPath)>.json " +
-    "for the live port/pid, or set UNITY_OPEN_MCP_BRIDGE_PORT. If Unity is not " +
-    "open, launch it (or set UNITY_PATH + UNITY_PROJECT_PATH for batch fallback).";
+    `Check the instance lock at ~/.unity-open-mcp/instances/<sha256(projectPath)>.json ` +
+    `for the live port/pid, or set ${PORT_ENV_VAR}. If Unity is not ` +
+    `open, launch it (or set UNITY_PATH + ${PROJECT_PATH_ENV_VAR} for batch fallback).`;
 /**
  * Build a per-instance offline hint that names THIS project's lock file path
  * and (when the lock is readable) its port/pid/state, so an agent debugging a
@@ -176,7 +174,7 @@ export class LiveClient {
      *  env-pinned port to the lock port. */
     envPort;
     constructor(port, pingCache, authToken, projectPath, agentId = PROCESS_AGENT_ID, envPort) {
-        this.baseUrl = `http://127.0.0.1:${port}`;
+        this.baseUrl = bridgeBaseUrl(port);
         this.pingCache = pingCache;
         this.authToken = authToken;
         this.projectPath = projectPath;
@@ -256,6 +254,16 @@ export class LiveClient {
             };
         }
         catch {
+            // M27 Plan 1 — ping is the first probe many agents use to decide
+            // whether to call read_compile_errors. Before returning a generic
+            // bridge_offline, check the cold Safe Mode signature (no lock + a live
+            // Unity process for this project) so the agent gets the same
+            // bridge_compile_failed recovery hint as the mid-session dead-bridge
+            // path. Without this an agent hitting ping first would see only
+            // bridge_offline and have to guess.
+            const coldSafeMode = this.coldSafeModeResult();
+            if (coldSafeMode)
+                return coldSafeMode;
             return makeErrorResult({
                 code: "bridge_offline",
                 message: `Bridge is not reachable at ${this.baseUrl}. ${buildOfflineHint(this.projectPath)}`,
@@ -362,258 +370,298 @@ export class LiveClient {
             },
         });
     }
+    /**
+     * POST a tool call to the bridge and shape the response. Decomposed in
+     * M28-refactoring Plan 3 (T3.3) into named steps so retry, compile-wait,
+     * transient-offline handling, and result shaping are independently readable.
+     *
+     * Pipeline:
+     *   1. {@link postToolFetch} — POST with a timeout floored above the bridge's
+     *      own default wait, handling 503-compile-retry and non-OK HTTP.
+     *   2. {@link shapeToolResult} — parse the body and dispatch mutation-envelope
+     *      vs direct-body vs inline-image vs reload/corruption outcomes.
+     *   3. On a transient fetch failure, {@link handlePostFailure} classifies +
+     *      recovers (re-syncing the endpoint, waiting out a reload, or surfacing
+     *      the structured offline/dead-bridge error) and re-POSTs only when safe.
+     *
+     * The retry/compile contract is unchanged from the former monolithic body.
+     */
     async postTool(toolName, args, retryOn503) {
         try {
-            const timeoutMs = typeof args.timeout_ms === "number" ? args.timeout_ms : 60_000;
-            // Floor the client fetch timeout at the bridge's own default wait + slack
-            // so the client never aborts before the bridge has had a chance to return
-            // its timeout envelope. Without this floor, a small/absent timeout_ms
-            // (MCP hosts often omit the field → schema default 30000, or smaller)
-            // makes the client re-POST while the bridge is still processing →
-            // duplicate mutations (specs/feedback.md entry 4B). An explicit large
-            // timeout_ms still wins via the Math.max.
-            const fetchTimeout = Math.max(timeoutMs + 10_000, BRIDGE_DEFAULT_TIMEOUT_MS + 10_000);
-            const res = await this.fetchWithTimeout(`/tools/${toolName}`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json; charset=utf-8" },
-                body: JSON.stringify(args),
-            }, fetchTimeout);
-            if (res.status === 503 && retryOn503) {
-                const compileError = await this.waitForCompile();
-                if (compileError)
-                    return compileError;
+            const res = await this.postToolFetch(toolName, args, retryOn503);
+            // 503 + compile settled cleanly → re-POST once without 503 retry.
+            if (isCompileRepostSentinel(res)) {
                 return this.postTool(toolName, args, false);
             }
-            if (!res.ok) {
-                const body = (await res
-                    .json()
-                    .catch(() => null));
-                return makeErrorResult({
-                    code: "bridge_http_error",
-                    message: body?.error?.message ?? `Bridge returned HTTP ${res.status}`,
-                    detail: body ?? {
-                        error: {
-                            code: "bridge_http_error",
-                            message: `HTTP ${res.status}`,
-                        },
+            return res;
+        }
+        catch (err) {
+            return this.handlePostFailure(toolName, args, err, retryOn503);
+        }
+    }
+    /**
+     * Step 1 of {@link postTool}: perform the HTTP POST with the timeout floor,
+     * then handle 503-compile-retry and non-OK HTTP. Returns either a shaped
+     * {@link CallToolResult} (handed straight back by postTool) or a sentinel
+     * `{ _repostAfterCompile: true }` signaling a clean compile settle that
+     * should re-POST without 503 retry. Throws on transient fetch failure so the
+     * caller's catch runs {@link handlePostFailure}.
+     */
+    async postToolFetch(toolName, args, retryOn503) {
+        const timeoutMs = typeof args.timeout_ms === "number" ? args.timeout_ms : 60_000;
+        // Floor the client fetch timeout at the bridge's own default wait + slack
+        // so the client never aborts before the bridge has had a chance to return
+        // its timeout envelope. Without this floor, a small/absent timeout_ms
+        // (MCP hosts often omit the field → schema default 30000, or smaller)
+        // makes the client re-POST while the bridge is still processing →
+        // duplicate mutations (specs/feedback.md entry 4B). An explicit large
+        // timeout_ms still wins via the Math.max.
+        const fetchTimeout = Math.max(timeoutMs + 10_000, BRIDGE_DEFAULT_TIMEOUT_MS + 10_000);
+        const res = await this.fetchWithTimeout(`/tools/${toolName}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json; charset=utf-8" },
+            body: JSON.stringify(args),
+        }, fetchTimeout);
+        if (res.status === 503 && retryOn503) {
+            const compileError = await this.waitForCompile();
+            if (compileError)
+                return compileError;
+            return COMPILE_REPOST_SENTINEL;
+        }
+        if (!res.ok) {
+            const body = (await res
+                .json()
+                .catch(() => null));
+            return makeErrorResult({
+                code: "bridge_http_error",
+                message: body?.error?.message ?? `Bridge returned HTTP ${res.status}`,
+                detail: body ?? {
+                    error: {
+                        code: "bridge_http_error",
+                        message: `HTTP ${res.status}`,
                     },
-                });
-            }
-            // The bridge returns TWO response shapes from /tools/*:
-            //   1. A MUTATION envelope: { mutation: { success, ... }, gate: {...} }
-            //      for gate-tracked mutating tools (gameobject_*, assets_*, etc.).
-            //   2. A DIRECT body: the tool's own JSON (e.g. { status, count, tags })
-            //      for read-only / state-only tools the bridge classifies as
-            //      DirectResponseTools (editor_get_tags, asmdef_list, shader_list_all,
-            //      scene_list_opened, material_get_properties, ~80 total).
-            //
-            // Previously postTool dispatched off a hardcoded DIRECT_RESPONSE_TOOLS set
-            // that was ~60 entries behind the bridge's set. Tools missing from it fell
-            // through to deriveIsError(body), which dereferences body.mutation.success
-            // — undefined for a direct body → TypeError. That thrown TypeError landed
-            // in the connection-recovery catch block, surfacing a misleading
-            // bridge_offline (and, with the entry-2026-07-02-b retry change, looping).
-            //
-            // The fix: detect the envelope shape from the BODY itself. A response with
-            // a top-level `mutation` object is a mutation envelope; anything else is a
-            // direct body. This is reliable because the bridge's DirectResponseTools
-            // path (HandleDirectResponseTool) never emits a `mutation` field and the
-            // gate path always does (BuildMutationEnvelope). The DIRECT_RESPONSE_TOOLS
-            // set is now only the inlineImage-unwrap allowlist (capture_inline), kept
-            // for that one special-case transform, not for shape routing.
-            //
-            // Capture the raw text first so the unparsable-body branch below can
-            // distinguish an EMPTY body (the signature of a compile-reload tool that
-            // triggered a domain reload mid-response — the bridge tore down its HTTP
-            // socket and the in-flight body was lost) from a SUBSTANTIAL-but-corrupt
-            // body (e.g. an execute_csharp snippet whose OutputSerializer output was
-            // truncated by a TypeLoadException). The reload case is a likely-success
-            // outcome; the corruption case is a real error. See specs/feedback.md
-            // 2026-07-05 (reload) + 2026-07-03-c (corruption).
-            const rawText = await res.text();
-            let parsed = null;
-            try {
-                parsed = JSON.parse(rawText);
-            }
-            catch {
-                parsed = null;
-            }
-            // capture_inline returns an `inlineImage` base64 PNG field. Unwrap it into
-            // an MCP image content block alongside a text metadata block
-            // ([{type: image}, {type: text}]). The image carries the same viewable
-            // payload a file-path screenshot would; the metadata keeps the view /
-            // resolution / byteLength fields without the base64 blob.
-            const inlineImage = parsed?.inlineImage;
-            if (DIRECT_RESPONSE_TOOLS.has(toolName) &&
-                parsed != null &&
-                typeof inlineImage === "string" &&
-                inlineImage.length > 0 &&
-                parsed.error == null) {
-                const mimeType = typeof parsed.mimeType === "string" ? parsed.mimeType : "image/png";
-                const metadata = { ...parsed };
-                delete metadata.inlineImage;
-                return {
-                    content: [
-                        { type: "image", data: inlineImage, mimeType },
-                        { type: "text", text: JSON.stringify(metadata) },
-                    ],
-                    isError: false,
-                };
-            }
-            // Mutation envelope vs direct body, decided from the body itself.
-            if (parsed != null && typeof parsed.mutation === "object" && parsed.mutation !== null) {
-                const body = parsed;
-                return {
-                    content: [{ type: "text", text: JSON.stringify(body) }],
-                    isError: deriveIsError(body),
-                };
-            }
-            // Malformed bridge body — JSON.parse rejected (parsed === null) on what
-            // should be a 200 OK application/json response. The bridge's two response
-            // shapes (BuildGateEnvelope, BuildDirectToolErrorJson) are always valid
-            // JSON, so a parse failure means the response was corrupted in transit or
-            // — the case that motivated this guard — a mutating tool's serialized
-            // output was interpolated raw into the gate envelope and produced
-            // unbalanced JSON (e.g. an execute_csharp snippet whose result threw a
-            // TypeLoadException during OutputSerializer's reflective walk).
-            //
-            // Previously this branch silently degraded to isError:false with an empty
-            // `{}` body, manufacturing a fake success. For compile-reload tools,
-            // annotateCompileVerify then stamped `_compileVerify` onto that `{}`,
-            // producing a malformed envelope `{"_compileVerify":{...}}` with NO
-            // `mutation` object — violating the documented contract and confusing
-            // agents that key off mutation.success (specs/feedback.md entry
-            // 2026-07-03-c). Surface a structured error instead so the failure is
-            // visible and annotateCompileVerify (gated on !result.isError) never
-            // annotates a body that lost its mutation block.
-            //
-            // Compile-reload special case (specs/feedback.md 2026-07-05 entry): for
-            // tools with the restart_then_settle lifecycle, an EMPTY (or near-empty)
-            // body on a 200 OK is the signature of a SUCCESSFUL mutation that
-            // triggered a domain reload mid-response — the bridge tore down its HTTP
-            // socket for the reload, the in-flight response was lost, and the agent
-            // observes a body that is empty or truncated to a few bytes. The
-            // mutation almost certainly committed (reimport_package,
-            // asmdef_create/modify, package_add/remove, … all commit before the
-            // reload). Returning bridge_response_unparsable here would frame a
-            // successful operation as corruption. Instead surface a typed
-            // triggered_reload outcome that tells the agent to verify post-state
-            // rather than suspect a corrupt response.
-            //
-            // The reload vs. corruption split keys off rawText length: a torn-down
-            // socket delivers zero or a handful of bytes (no Content-Length / chunk
-            // completing), while an OutputSerializer corruption leaves a substantial
-            // half-written envelope. A SUBSTANTIAL unparseable body on a
-            // compile-reload tool is STILL treated as corruption (the original
-            // 2026-07-03-c contract) — that path keeps bridge_response_unparsable.
-            if (parsed == null) {
-                const isEmptyLikeReload = rawText.trim().length === 0;
-                if (isEmptyLikeReload && lifecycleFor(toolName).class === "compile-reload") {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: JSON.stringify({
-                                    status: "triggered_reload",
-                                    // The bridge returned 200 (the mutation reached the
-                                    // dispatcher and the response was started) but the body was
-                                    // empty — the hallmark of a domain reload tearing down the
-                                    // socket mid-response. The mutation very likely committed;
-                                    // treat this as "verify post-state" rather than "response
-                                    // corrupt, retry".
-                                    triggeredReload: true,
-                                    message: `Bridge returned HTTP 200 for '${toolName}' with an empty ` +
-                                        `response body. '${toolName}' is a compile-reload tool, so ` +
-                                        `this is the expected signature of a mutation that triggered ` +
-                                        `a domain reload mid-response — the bridge tore down its HTTP ` +
-                                        `socket for the reload and the in-flight response was lost ` +
-                                        `before any bytes were written. The mutation very likely ` +
-                                        `committed (compile-reload tools commit before the reload ` +
-                                        `begins). Do NOT treat this as corruption and do NOT retry ` +
-                                        `blindly (that would re-run the mutation). Verify post-state: ` +
-                                        `call unity_open_mcp_editor_status / bridge_status to confirm ` +
-                                        `the reload settled, then unity_open_mcp_read_compile_errors ` +
-                                        `to confirm there are no compile errors.`,
-                                    agentNextSteps: [
-                                        "Poll unity_open_mcp_editor_status / bridge_status until the bridge reports running and not compiling.",
-                                        "Call unity_open_mcp_read_compile_errors to confirm the recompiled assembly has no CSxxxx errors (note: if the response carries staleLogSuspected, force a recompile via reimport_package / compile_check first).",
-                                        "Do NOT retry the original call — the mutation likely committed before the reload. Verify the effect via the appropriate read tool instead.",
-                                    ],
-                                    _route: { route: "live", outcome: "triggered_reload" },
-                                }),
-                            },
-                        ],
-                        isError: false,
-                    };
-                }
-                return makeErrorResult({
-                    code: "bridge_response_unparsable",
-                    message: `Bridge returned HTTP 200 for '${toolName}' but the response body ` +
-                        `was not valid JSON. This usually means a mutating tool's serialized ` +
-                        `output was corrupted (e.g. an execute_csharp snippet whose result ` +
-                        `threw during serialization). The result is unreliable — do not trust ` +
-                        `any partial output. Check editor_status / bridge_status, then retry. ` +
-                        `Endpoint: ${this.baseUrl}.`,
-                });
-            }
-            // Direct body: return it verbatim. isError when the tool reported a
-            // top-level error field (the bridge's direct-response convention).
+                },
+            });
+        }
+        return this.shapeToolResult(toolName, res);
+    }
+    /**
+     * Step 2 of {@link postTool}: parse the bridge response body and shape it into
+     * a {@link CallToolResult}. Handles the four response outcomes:
+     *   - inline-image unwrap (capture_inline → MCP image block + metadata),
+     *   - mutation envelope (derive isError from mutation.success),
+     *   - compile-reload empty body (triggered_reload — likely-success domain
+     *     reload tore down the socket mid-response),
+     *   - direct body (verbatim, isError when a top-level error field is present),
+     *   - unparsable body (bridge_response_unparsable corruption error).
+     */
+    async shapeToolResult(toolName, res) {
+        // The bridge returns TWO response shapes from /tools/*:
+        //   1. A MUTATION envelope: { mutation: { success, ... }, gate: {...} }
+        //      for gate-tracked mutating tools (gameobject_*, assets_*, etc.).
+        //   2. A DIRECT body: the tool's own JSON (e.g. { status, count, tags })
+        //      for read-only / state-only tools the bridge classifies as
+        //      DirectResponseTools (editor_get_tags, asmdef_list, shader_list_all,
+        //      scene_list_opened, material_get_properties, ~80 total).
+        //
+        // Previously postTool dispatched off a hardcoded DIRECT_RESPONSE_TOOLS set
+        // that was ~60 entries behind the bridge's set. Tools missing from it fell
+        // through to deriveIsError(body), which dereferences body.mutation.success
+        // — undefined for a direct body → TypeError. That thrown TypeError landed
+        // in the connection-recovery catch block, surfacing a misleading
+        // bridge_offline (and, with the entry-2026-07-02-b retry change, looping).
+        //
+        // The fix: detect the envelope shape from the BODY itself. A response with
+        // a top-level `mutation` object is a mutation envelope; anything else is a
+        // direct body. This is reliable because the bridge's DirectResponseTools
+        // path (HandleDirectResponseTool) never emits a `mutation` field and the
+        // gate path always does (BuildMutationEnvelope). The DIRECT_RESPONSE_TOOLS
+        // set is now only the inlineImage-unwrap allowlist (capture_inline), kept
+        // for that one special-case transform, not for shape routing.
+        //
+        // Capture the raw text first so the unparsable-body branch below can
+        // distinguish an EMPTY body (the signature of a compile-reload tool that
+        // triggered a domain reload mid-response — the bridge tore down its HTTP
+        // socket and the in-flight body was lost) from a SUBSTANTIAL-but-corrupt
+        // body (e.g. an execute_csharp snippet whose OutputSerializer output was
+        // truncated by a TypeLoadException). The reload case is a likely-success
+        // outcome; the corruption case is a real error. See specs/feedback.md
+        // 2026-07-05 (reload) + 2026-07-03-c (corruption).
+        const rawText = await res.text();
+        let parsed = null;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch {
+            parsed = null;
+        }
+        // capture_inline returns an `inlineImage` base64 PNG field. Unwrap it into
+        // an MCP image content block alongside a text metadata block
+        // ([{type: image}, {type: text}]). The image carries the same viewable
+        // payload a file-path screenshot would; the metadata keeps the view /
+        // resolution / byteLength fields without the base64 blob.
+        const inlineImage = parsed?.inlineImage;
+        if (DIRECT_RESPONSE_TOOLS.has(toolName) &&
+            parsed != null &&
+            typeof inlineImage === "string" &&
+            inlineImage.length > 0 &&
+            parsed.error == null) {
+            const mimeType = typeof parsed.mimeType === "string" ? parsed.mimeType : "image/png";
+            const metadata = { ...parsed };
+            delete metadata.inlineImage;
             return {
                 content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(parsed),
-                    },
+                    { type: "image", data: inlineImage, mimeType },
+                    { type: "text", text: JSON.stringify(metadata) },
                 ],
-                isError: parsed.error != null,
+                isError: false,
             };
         }
-        catch (err) {
-            // M20 Plan 4-5 / T-fix-2 — transient POST failure (ECONNREFUSED /
-            // timeout during a domain reload). Classify + recover before declaring
-            // offline. handleTransientOffline re-syncs the cached endpoint from the
-            // lock first (so a Unity restart self-heals).
-            //
-            // Re-POST discipline (specs/feedback.md entry 4A — duplicate side-effects):
-            // only re-POST when the endpoint CHANGED during recovery (a restart → new
-            // bridge that never saw the original POST, so a retry is safe). When the
-            // endpoint is unchanged the same live bridge is still processing — or has
-            // queued — the original POST's Work; re-POSTing would run the mutation a
-            // second time. In that case surface the timeout instead of retrying.
-            //
-            // shouldRetryPostAfterFailure additionally allows a re-POST on a genuine
-            // CONNECTION failure (TypeError — the socket never connected / was reset
-            // before the body flushed / ECONNREFUSED), because no bytes reached the
-            // server and no side effect is possible. This must NOT fire for a
-            // TypeError thrown by response parsing (e.g. deriveIsError on a malformed
-            // body) — that path is now guarded by parsing the body defensively above,
-            // but as a belt-and-braces measure the response-parsing path is structured
-            // so it cannot throw into this catch (every .json() is .catch()-guarded).
-            const endpointBefore = this.baseUrl;
-            const recovered = await this.handleTransientOffline("post");
-            if (recovered !== null)
-                return recovered;
-            const endpointChanged = this.baseUrl !== endpointBefore;
-            if (shouldRetryPostAfterFailure(err, endpointChanged)) {
-                return this.postTool(toolName, args, retryOn503);
+        // Mutation envelope vs direct body, decided from the body itself.
+        if (parsed != null && typeof parsed.mutation === "object" && parsed.mutation !== null) {
+            const body = parsed;
+            return {
+                content: [{ type: "text", text: JSON.stringify(body) }],
+                isError: deriveIsError(body),
+            };
+        }
+        // Malformed bridge body — JSON.parse rejected (parsed === null) on what
+        // should be a 200 OK application/json response. The bridge's two response
+        // shapes (BuildGateEnvelope, BuildDirectToolErrorJson) are always valid
+        // JSON, so a parse failure means the response was corrupted in transit or
+        // — the case that motivated this guard — a mutating tool's serialized
+        // output was interpolated raw into the gate envelope and produced
+        // unbalanced JSON (e.g. an execute_csharp snippet whose result threw a
+        // TypeLoadException during OutputSerializer's reflective walk).
+        //
+        // Previously this branch silently degraded to isError:false with an empty
+        // `{}` body, manufacturing a fake success. For compile-reload tools,
+        // annotateCompileVerify then stamped `_compileVerify` onto that `{}`,
+        // producing a malformed envelope `{"_compileVerify":{...}}` with NO
+        // `mutation` object — violating the documented contract and confusing
+        // agents that key off mutation.success (specs/feedback.md entry
+        // 2026-07-03-c). Surface a structured error instead so the failure is
+        // visible and annotateCompileVerify (gated on !result.isError) never
+        // annotates a body that lost its mutation block.
+        //
+        // Compile-reload special case (specs/feedback.md 2026-07-05 entry): for
+        // tools with the restart_then_settle lifecycle, an EMPTY (or near-empty)
+        // body on a 200 OK is the signature of a SUCCESSFUL mutation that
+        // triggered a domain reload mid-response — the bridge tore down its HTTP
+        // socket for the reload, the in-flight response was lost, and the agent
+        // observes a body that is empty or truncated to a few bytes. The
+        // mutation almost certainly committed (reimport_package,
+        // asmdef_create/modify, package_add/remove, … all commit before the
+        // reload). Returning bridge_response_unparsable here would frame a
+        // successful operation as corruption. Instead surface a typed
+        // triggered_reload outcome that tells the agent to verify post-state
+        // rather than suspect a corrupt response.
+        //
+        // The reload vs. corruption split keys off rawText length: a torn-down
+        // socket delivers zero or a handful of bytes (no Content-Length / chunk
+        // completing), while an OutputSerializer corruption leaves a substantial
+        // half-written envelope. A SUBSTANTIAL unparseable body on a
+        // compile-reload tool is STILL treated as corruption (the original
+        // 2026-07-03-c contract) — that path keeps bridge_response_unparsable.
+        if (parsed == null) {
+            const isEmptyLikeReload = rawText.trim().length === 0;
+            if (isEmptyLikeReload && lifecycleFor(toolName).class === "compile-reload") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "triggered_reload",
+                                // The bridge returned 200 (the mutation reached the
+                                // dispatcher and the response was started) but the body was
+                                // empty — the hallmark of a domain reload tearing down the
+                                // socket mid-response. The mutation very likely committed;
+                                // treat this as "verify post-state" rather than "response
+                                // corrupt, retry".
+                                triggeredReload: true,
+                                message: `Bridge returned HTTP 200 for '${toolName}' with an empty ` +
+                                    `response body. '${toolName}' is a compile-reload tool, so ` +
+                                    `this is the expected signature of a mutation that triggered ` +
+                                    `a domain reload mid-response — the bridge tore down its HTTP ` +
+                                    `socket for the reload and the in-flight response was lost ` +
+                                    `before any bytes were written. The mutation very likely ` +
+                                    `committed (compile-reload tools commit before the reload ` +
+                                    `begins). Do NOT treat this as corruption and do NOT retry ` +
+                                    `blindly (that would re-run the mutation). Verify post-state: ` +
+                                    `call unity_open_mcp_editor_status / bridge_status to confirm ` +
+                                    `the reload settled, then unity_open_mcp_read_compile_errors ` +
+                                    `to confirm there are no compile errors.`,
+                                agentNextSteps: [
+                                    "Poll unity_open_mcp_editor_status / bridge_status until the bridge reports running and not compiling.",
+                                    "Call unity_open_mcp_read_compile_errors to confirm the recompiled assembly has no CSxxxx errors (note: if the response carries staleLogSuspected, force a recompile via reimport_package / compile_check first).",
+                                    "Do NOT retry the original call — the mutation likely committed before the reload. Verify the effect via the appropriate read tool instead.",
+                                ],
+                                _route: { route: "live", outcome: "triggered_reload" },
+                            }),
+                        },
+                    ],
+                    isError: false,
+                };
             }
             return makeErrorResult({
-                code: "bridge_offline",
-                message: `Tool '${toolName}' did not return from the bridge within the client ` +
-                    `timeout. The bridge endpoint did not change (no restart detected) and ` +
-                    `the failure was a response timeout (not a connection failure), so ` +
-                    `the request was NOT retried — re-POSTing would risk running the ` +
-                    `mutation twice on the same bridge. If the editor was briefly slow ` +
-                    `(unfocused, GC, a long main-thread op), the original call may still ` +
-                    `complete there; verify the effect before retrying. Endpoint: ${this.baseUrl}.`,
-                detail: {
-                    error: {
-                        code: "bridge_offline",
-                        message: `Client timeout against unchanged endpoint ${this.baseUrl}; not retried to avoid duplicate side-effects.`,
-                    },
-                },
+                code: "bridge_response_unparsable",
+                message: `Bridge returned HTTP 200 for '${toolName}' but the response body ` +
+                    `was not valid JSON. This usually means a mutating tool's serialized ` +
+                    `output was corrupted (e.g. an execute_csharp snippet whose result ` +
+                    `threw during serialization). The result is unreliable — do not trust ` +
+                    `any partial output. Check editor_status / bridge_status, then retry. ` +
+                    `Endpoint: ${this.baseUrl}.`,
             });
         }
+        // Direct body: return it verbatim. isError when the tool reported a
+        // top-level error field (the bridge's direct-response convention).
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(parsed),
+                },
+            ],
+            isError: parsed.error != null,
+        };
+    }
+    /**
+     * Step 3 of {@link postTool}: classify + recover from a transient POST
+     * failure (ECONNREFUSED / timeout during a domain reload). Re-syncs the cached
+     * endpoint from the lock first (so a Unity restart self-heals), waits out a
+     * reload, and re-POSTs ONLY when safe (endpoint changed during recovery, or a
+     * genuine connection failure where no bytes reached the server).
+     *
+     * Re-POST discipline (specs/feedback.md entry 4A — duplicate side-effects):
+     * when the endpoint is unchanged the same live bridge is still processing —
+     * or has queued — the original POST's Work; re-POSTing would run the mutation
+     * a second time. In that case surface the timeout instead of retrying.
+     */
+    async handlePostFailure(toolName, args, err, retryOn503) {
+        const endpointBefore = this.baseUrl;
+        const recovered = await this.handleTransientOffline("post");
+        if (recovered !== null)
+            return recovered;
+        const endpointChanged = this.baseUrl !== endpointBefore;
+        if (shouldRetryPostAfterFailure(err, endpointChanged)) {
+            return this.postTool(toolName, args, retryOn503);
+        }
+        return makeErrorResult({
+            code: "bridge_offline",
+            message: `Tool '${toolName}' did not return from the bridge within the client ` +
+                `timeout. The bridge endpoint did not change (no restart detected) and ` +
+                `the failure was a response timeout (not a connection failure), so ` +
+                `the request was NOT retried — re-POSTing would risk running the ` +
+                `mutation twice on the same bridge. If the editor was briefly slow ` +
+                `(unfocused, GC, a long main-thread op), the original call may still ` +
+                `complete there; verify the effect before retrying. Endpoint: ${this.baseUrl}.`,
+            detail: {
+                error: {
+                    code: "bridge_offline",
+                    message: `Client timeout against unchanged endpoint ${this.baseUrl}; not retried to avoid duplicate side-effects.`,
+                },
+            },
+        });
     }
     async ensureReady() {
         try {
@@ -684,6 +732,15 @@ export class LiveClient {
             catch {
                 // Re-probe also failed — fall through to the offline error below.
             }
+            // M27 Plan 1 — before declaring a generic bridge_offline, check the
+            // cold Safe Mode signature: no lock (bridge never compiled) + a live
+            // Unity process for this project. A match surfaces the same
+            // bridge_compile_failed shape as the mid-session dead-bridge path so
+            // the agent gets the read_compile_errors recovery hint instead of a
+            // generic offline error it would have to guess past.
+            const coldSafeMode = this.coldSafeModeResult();
+            if (coldSafeMode)
+                return coldSafeMode;
             return makeErrorResult({
                 code: "bridge_offline",
                 message: `Bridge is not reachable at ${this.baseUrl}. ${buildOfflineHint(this.projectPath)}`,
@@ -774,6 +831,15 @@ export class LiveClient {
             }
         }
         void operation; // log-only parameter, reserved for future telemetry
+        // M27 Plan 1 — before declaring a generic bridge_offline, check the cold
+        // Safe Mode signature. handleTransientOffline is the shared recovery
+        // exhaustion point for both the ping and POST paths; surfacing
+        // bridge_compile_failed here covers tool POSTs that never reached the
+        // bridge (no listener, no lock, Unity in Safe Mode) without each caller
+        // having to repeat the scan.
+        const coldSafeMode = this.coldSafeModeResult();
+        if (coldSafeMode)
+            return coldSafeMode;
         const retryMsg = `Bridge is not reachable at ${this.baseUrl} after ${maxAttempts} retries. ${buildOfflineHint(this.projectPath)}`;
         return makeErrorResult({
             code: "bridge_offline",
@@ -822,12 +888,12 @@ export class LiveClient {
             return false;
         const portChanged = typeof lock.port === "number" &&
             lock.port > 0 &&
-            this.baseUrl !== `http://127.0.0.1:${lock.port}`;
+            this.baseUrl !== bridgeBaseUrl(lock.port);
         const tokenChanged = lock.authToken !== this.authToken;
         if (!portChanged && !tokenChanged)
             return false;
         if (portChanged)
-            this.baseUrl = `http://127.0.0.1:${lock.port}`;
+            this.baseUrl = bridgeBaseUrl(lock.port);
         if (tokenChanged)
             this.authToken = lock.authToken;
         return true;
@@ -899,6 +965,72 @@ export class LiveClient {
             isError: true,
         };
     }
+    /**
+     * M27 Plan 1 — cold Safe Mode detection. The mirror of
+     * {@link deadBridgeResult} for the no-lock case. When Unity launches
+     * straight into Safe Mode, the bridge's `[InitializeOnLoad]` never runs, so
+     * no instance lock is written and {@link classifyInstance} returns `gone` —
+     * the same classification as "Unity is not running." Without a positive
+     * signal the agent cannot tell that `read_compile_errors` is the right next
+     * step; it gets a generic `bridge_offline` and must guess.
+     *
+     * This method scans for a live Unity process whose `-projectPath` references
+     * this project. A match is a strong positive signal of cold Safe Mode (the
+     * only other case that produces no lock + a live Unity process is "bridge
+     * toolbar off", which shares the same recovery — check compile errors /
+     * enable the bridge). Returns the SAME `bridge_compile_failed` shape as
+     * {@link deadBridgeResult} so the agent-facing contract is identical to the
+     * mid-session dead-bridge path; returns null when no Unity process matches
+     * (genuine offline — the caller falls back to `bridge_offline`).
+     *
+     * Like {@link deadBridgeResult} this is cheap to call repeatedly: the scan
+     * is the only new cost, and it runs only when classification is `gone`
+     * (lock absent or PID dead) — never on the happy path or during a reload.
+     */
+    coldSafeModeResult() {
+        if (!this.projectPath)
+            return null;
+        let classification;
+        try {
+            classification = classifyInstance(readInstanceLock(this.projectPath));
+        }
+        catch {
+            return null;
+        }
+        // Only the no-lock / dead-PID case is a candidate for cold Safe Mode. A
+        // live lock with a stale heartbeat is the mid-session dead-bridge path —
+        // handled by deadBridgeResult, not here.
+        if (classification !== "gone")
+            return null;
+        const proc = findUnityForProject(this.projectPath);
+        if (!proc)
+            return null;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: {
+                            code: "bridge_compile_failed",
+                            message: "Unity is running but the bridge is unreachable and no " +
+                                "instance lock was found — Unity likely launched straight " +
+                                "into Safe Mode (the bridge assembly failed to compile from " +
+                                "a cold start, so [InitializeOnLoad] never wrote a lock). " +
+                                "The HTTP listener will not return until the C# error is " +
+                                "fixed. Call unity_open_mcp_read_compile_errors to retrieve " +
+                                "the compiler errors from Unity's Editor.log, fix the cited " +
+                                "file/line, then trigger a recompile (e.g. a no-op edit + " +
+                                "focus Unity, or unity_open_mcp_compile_check once the " +
+                                "source compiles). If Unity is NOT in safe mode, the bridge " +
+                                "toolbar toggle may be off — open the bridge window (Unity " +
+                                "menu: Tools/Unity Open MCP Bridge) and confirm it is started.",
+                        },
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
     async waitForCompile() {
         const compileWaitMs = this.retry.compileWaitMs;
         const deadline = Date.now() + compileWaitMs;