unity-open-mcp 0.1.0 → 0.3.0

package/dist/live-client.js

@@ -1,14 +1,37 @@
 import { deriveIsError } from "./gate-error.js";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { pollAndDismissLaunchErrors, readDismissConfig, } from "./dialog-dismiss.js";
-import { readInstanceLock, classifyInstance, lockPath } from "./instance-discovery.js";
+import { pollAndDismissDialogs, readDismissConfig, } from "./dialog-dismiss.js";
+import { readInstanceLock, classifyInstance, lockPath, isPidAlive } from "./instance-discovery.js";
 import { makeErrorResult } from "./results.js";
 import { checkBridgeCompat, isVersionCheckSuppressed, } from "./compat.js";
-const MAX_COMPILE_WAIT_MS = 120_000;
-const COMPILE_POLL_INTERVAL_MS = 2_000;
+// M23 Plan 3 — structured retry policy + env-overridable tunables. Replaces
+// the hardcoded module constants that previously bounded the compile-wait and
+// transient-retry loops. The policy is keyed by lifecycle class (see
+// retryConfigFor); the tunables are resolved once at construction.
+import { readRetryTunables, } from "./retry-policy.js";
+// M23 Plan 3 — compile-verify failure-code detection (compile_noop /
+// dll_stale). Applied as an additive annotation on compile-reload results so
+// an agent can branch when a recompile reported success but the compiled state
+// did not advance.
+import { detectCompileVerify, buildCompileVerifyAnnotation, } from "./compile-verify.js";
+import { lifecycleFor } from "./capabilities/lifecycle.js";
+// M23 Plan 3 — per-process agent identity (sent as X-Agent-Id so the bridge's
+// 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;
 const DIRECT_RESPONSE_TOOLS = new Set([
     "unity_open_mcp_validate_edit",
     "unity_open_mcp_checkpoint_create",
@@ -40,6 +63,45 @@ const DIRECT_RESPONSE_TOOLS = new Set([
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * 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
+ * isolation (driving a real response-timeout through postTool takes 40s because
+ * the fetch timeout is floored at BRIDGE_DEFAULT_TIMEOUT_MS + slack).
+ *
+ * undici (Node's fetch) throws a DISTINGUISHABLE error class for the two
+ * failure modes that reach this catch:
+ *   - `TypeError` ("fetch failed") → CONNECTION failure: the socket never
+ *     connected, was reset before the request body flushed, or the listen port
+ *     is dead (ECONNREFUSED). No bytes reached the server → no Work was queued
+ *     → no side effect is possible. Re-POSTing is ALWAYS safe, even on an
+ *     unchanged endpoint (the same live bridge never received the first POST).
+ *   - `AbortError` (AbortController timer) → RESPONSE timeout: the request
+ *     connected and the server is still processing it. A side effect may have
+ *     happened or be queued. Re-POSTing is only safe when the endpoint CHANGED
+ *     during recovery (a restart → new bridge that never saw the original POST);
+ *     on an unchanged endpoint the original call may still complete there, so
+ *     re-POSTing would risk running the mutation a second time.
+ *
+ * This distinction matters because a burst of parallel /tools/* calls can leave
+ * a dead/reset connection in the pool: the next POST throws a TypeError on
+ * connect, and the old "unchanged endpoint → no retry" guard wedged the whole
+ * typed-editor surface even though the bridge was healthy and idle
+ * (specs/feedback.md entry 2026-07-02-b). The bug was that the guard conflated
+ * "endpoint unchanged" with "request in flight," which is only true when the
+ * fetch actually connected (AbortError), not when it failed to connect
+ * (TypeError).
+ */
+export function shouldRetryPostAfterFailure(err, endpointChanged) {
+    // An endpoint change (Unity restart detected during recovery) always makes a
+    // retry safe regardless of failure class — the new bridge never saw the POST.
+    if (endpointChanged)
+        return true;
+    // Unchanged endpoint: only retry on a connection failure (TypeError). A
+    // response timeout (AbortError or anything else) on the same endpoint means
+    // the request may have reached the bridge → suppress the retry.
+    return err instanceof TypeError;
+}
 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. " +
@@ -74,6 +136,13 @@ export class LiveClient {
     dismissEnabled;
     dismissTimeoutMs;
     dismissIntervalMs;
+    /** M23 Plan 2 — active dialog policy (auto/manual/ignore/recover/safe-mode/
+     *  cancel). Stored so waitForCompile can thread it into the dismiss loop
+     *  without re-reading the env on every stall. */
+    dialogPolicy;
+    /** M23 Plan 2 — opt-in for the Project Upgrade Required dialog (irreversible,
+     *  off by default). */
+    allowProjectUpgrade;
     /** M14 — per-session bearer token auto-discovered from the instance lock.
      *  Undefined when no live lock was found (older bridge / env port override);
      *  in that case no Authorization header is sent and the bridge must be in
@@ -87,20 +156,44 @@ export class LiveClient {
     /** One-shot guard so the version-compat warning (server vs bridge) is emitted
      *  at most once per process — every /ping would otherwise re-warn. */
     compatWarned;
-    constructor(port, pingCache, authToken, projectPath) {
+    /** M23 Plan 3 — env-overridable retry/compile-wait tunables. Resolved once
+     *  at construction (the env does not change mid-process). Replaces the
+     *  hardcoded MAX_COMPILE_WAIT_MS / COMPILE_POLL_INTERVAL_MS /
+     *  TRANSIENT_RETRY_* module constants. */
+    retry;
+    /** M23 Plan 3 — agent identity sent as X-Agent-Id on every request so the
+     *  bridge's fair round-robin queue can schedule across agents sharing one
+     *  bridge. Defaults to the process-wide id; a transient LiveClient built for
+     *  a per-request port override may carry a per-call id. */
+    agentId;
+    /** Parsed UNITY_OPEN_MCP_BRIDGE_PORT, or undefined. When set, the env
+     *  override is authoritative and refreshEndpointFromLock() is a no-op (there
+     *  is no lock to read — matches resolvePort/resolveAuthToken semantics).
+     *  Stored so a mid-session refresh can respect the same override precedence
+     *  the constructor used; without it a refresh would silently switch from an
+     *  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.pingCache = pingCache;
         this.authToken = authToken;
         this.projectPath = projectPath;
-        // M13 T4.5 — launch-errors / Safe Mode dialog auto-dismissal. Resolved
-        // once at construction; the env vars do not change mid-process. The
-        // feature is enabled by default (Unity-MCP parity) and runs concurrently
-        // with every compile/bridge readiness wait so it ticks on the same stall
-        // points agents hit, not only at process spawn.
+        this.retry = readRetryTunables();
+        this.agentId = agentId;
+        this.envPort = envPort;
+        // M13 T4.5 + M23 Plan 2 — startup dialog auto-dismissal. Resolved once at
+        // construction; the env vars do not change mid-process. The feature is
+        // enabled by default and runs concurrently with every compile/bridge
+        // readiness wait so it ticks on the same stall points agents hit, not
+        // only at process spawn. M23 Plan 2 generalizes T4.5's single Ignore
+        // click into the full 6-variant policy taxonomy (dialog-policy.ts) so
+        // different workflows can pick different buttons on the same dialog.
         const dismissCfg = readDismissConfig();
         this.dismissEnabled = dismissCfg.enabled;
         this.dismissTimeoutMs = dismissCfg.timeoutMs;
         this.dismissIntervalMs = dismissCfg.intervalMs;
+        this.dialogPolicy = dismissCfg.policy;
+        this.allowProjectUpgrade = dismissCfg.allowProjectUpgrade;
         this.compatWarned = false;
     }
     /**
@@ -176,7 +269,18 @@ export class LiveClient {
         const readyError = await this.ensureReady();
         if (readyError)
             return readyError;
-        return this.postTool(toolName, args, true);
+        // M23 Plan 3 — compile-verify annotation. For compile-reload tools, capture
+        // a before-snapshot (bridge tool count + newest ScriptAssemblies DLL mtime)
+        // so the post-call detectCompileVerify() can flag a no-op/stale compile.
+        // Non-compile-reload tools skip this entirely (no extra /tools round-trip,
+        // no fs scan). The annotation is additive: it never blocks a success.
+        const isCompileReload = lifecycleFor(toolName).class === "compile-reload";
+        const before = isCompileReload ? await this.captureCompileSnapshot() : null;
+        const result = await this.postTool(toolName, args, true);
+        if (isCompileReload && !result.isError && before !== null) {
+            return this.annotateCompileVerify(toolName, result, before, args);
+        }
+        return result;
     }
     async handleRunTests(args) {
         const readyError = await this.ensureReady();
@@ -258,11 +362,19 @@ export class LiveClient {
     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),
-            }, timeoutMs + 10_000);
+            }, fetchTimeout);
             if (res.status === 503 && retryOn503) {
                 const compileError = await this.waitForCompile();
                 if (compileError)
@@ -284,55 +396,113 @@ export class LiveClient {
                     },
                 });
             }
-            if (DIRECT_RESPONSE_TOOLS.has(toolName)) {
-                const directBody = (await res.json().catch(() => null));
-                // M20 Plan 1 / T20.1.1 — capture_inline returns an `inlineImage` base64
-                // PNG field. Unwrap it into an MCP image content block alongside a text
-                // metadata block (matching the AnkleBreaker unity_graphics_*_capture
-                // contract: [{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 = directBody?.inlineImage;
-                if (directBody != null &&
-                    typeof inlineImage === "string" &&
-                    inlineImage.length > 0 &&
-                    directBody.error == null) {
-                    const body = directBody;
-                    const mimeType = typeof body.mimeType === "string" ? body.mimeType : "image/png";
-                    const metadata = { ...body };
-                    delete metadata.inlineImage;
-                    return {
-                        content: [
-                            { type: "image", data: inlineImage, mimeType },
-                            { type: "text", text: JSON.stringify(metadata) },
-                        ],
-                        isError: false,
-                    };
-                }
+            // 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.
+            const parsed = (await res.json().catch(() => 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(directBody ?? {}),
-                        },
+                        { type: "image", data: inlineImage, mimeType },
+                        { type: "text", text: JSON.stringify(metadata) },
                     ],
-                    isError: directBody?.error != null,
+                    isError: false,
                 };
             }
-            const body = (await res.json());
+            // 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),
+                };
+            }
+            // 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(body) }],
-                isError: deriveIsError(body),
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(parsed ?? {}),
+                    },
+                ],
+                isError: parsed?.error != null,
             };
         }
-        catch {
+        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);
+            }
             return makeErrorResult({
                 code: "bridge_offline",
-                message: `Failed to reach bridge at ${this.baseUrl}. ${buildOfflineHint(this.projectPath)}`,
+                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: `Cannot connect to bridge at ${this.baseUrl}`,
+                        message: `Client timeout against unchanged endpoint ${this.baseUrl}; not retried to avoid duplicate side-effects.`,
                     },
                 },
             });
@@ -371,14 +541,42 @@ export class LiveClient {
         }
         catch {
             // Bridge is unreachable (ECONNREFUSED / timeout). Before falling back to
-            // the generic offline error, check whether the instance lock indicates a
-            // DEAD bridge assembly — the Unity process is still alive but the bridge
-            // failed to reload after a compile error. That case is NOT recoverable
-            // by waiting; surface it immediately so the agent can fetch the compiler
-            // errors and fix them instead of hanging on /ping.
-            const deadBridge = this.deadBridgeResult();
-            if (deadBridge)
-                return deadBridge;
+            // the generic offline error, classify the failure via the instance lock:
+            //   - dead_bridge    → bridge assembly failed to recompile (fail fast)
+            //   - reloading/compiling → a normal domain reload is in flight; wait it
+            //     out (the listener socket is torn down for the reload duration) then
+            //     re-probe once before declaring offline (T-fix-2)
+            //   - otherwise      → retry with backoff a few times, then offline
+            // handleTransientOffline refreshes the cached endpoint from the lock
+            // first, so a Unity restart (new PID/port) re-points this client before
+            // the retry probes (specs/feedback.md entry 2).
+            const recovered = await this.handleTransientOffline("ping");
+            if (recovered !== null)
+                return recovered;
+            // Recovery returned null ("recovered" — a /ping probe succeeded during
+            // handleTransientOffline, possibly against a freshly-refreshed endpoint
+            // after a restart). Re-probe /ping ONCE on the (possibly new) endpoint
+            // before declaring offline: without this, a restart that refreshed the
+            // endpoint mid-recovery would still surface bridge_offline here, and the
+            // caller (handleToolCall) treats any non-null ensureReady result as a
+            // terminal error — so the next tool call would fail despite the bridge
+            // being back. The single re-probe closes that gap.
+            try {
+                const retryRes = await this.fetchWithTimeout("/ping", { method: "GET" });
+                if (retryRes.status === 503)
+                    return this.waitForCompile();
+                if (retryRes.ok) {
+                    const retryBody = (await retryRes.json());
+                    this.pingCache.record(retryBody);
+                    if (retryBody.compiling)
+                        return this.waitForCompile();
+                    if (retryBody.connected)
+                        return null; // recovered against the new endpoint
+                }
+            }
+            catch {
+                // Re-probe also failed — fall through to the offline error below.
+            }
             return makeErrorResult({
                 code: "bridge_offline",
                 message: `Bridge is not reachable at ${this.baseUrl}. ${buildOfflineHint(this.projectPath)}`,
@@ -391,6 +589,157 @@ export class LiveClient {
             });
         }
     }
+    /**
+     * M20 Plan 4-5 / T-fix-2 — classify a transient /ping or tool-POST failure
+     * (ECONNREFUSED / timeout / socket reset) via the instance lock and either
+     * recover or surface the right error.
+     *
+     * Returns:
+     *   - a structured `bridge_compile_failed` result when the lock shows a dead
+     *     bridge assembly (fail fast — preserves the pre-existing fast-path),
+     *   - `null` to signal "recovered — the caller should retry its operation"
+     *     after either waiting out a `reloading`/`compiling` lock window or
+     *     succeeding a bounded backoff retry,
+     *   - a `bridge_offline` result when the bridge is genuinely unreachable after
+     *     the recovery attempts (so the caller's outer `bridge_offline` fallback
+     *     is reached only via this returned result).
+     *
+     * `operation` is "ping" | "post" and only affects the log line — both paths
+     * share the same recovery logic.
+     */
+    async handleTransientOffline(operation) {
+        // Before any classification/retry, re-sync the cached endpoint to the
+        // current live bridge. A Unity restart writes a fresh PID/port/authToken
+        // to the lock; without this refresh every retry below would keep hitting
+        // the dead cached listener (specs/feedback.md entry 2) and, on the POST
+        // path, re-dispatch the Work to the new bridge (duplicate side-effects,
+        // entry 4A). refreshEndpointFromLock is a no-op when an env-port override
+        // is in force or nothing has changed.
+        this.refreshEndpointFromLock();
+        // Dead bridge assembly — not recoverable by waiting. Fail fast so the
+        // agent can fetch compile errors instead of hanging on /ping.
+        const deadBridge = this.deadBridgeResult();
+        if (deadBridge)
+            return deadBridge;
+        const classification = this.classifyLockNow();
+        // A normal domain reload in flight: the listener socket is torn down for
+        // the reload duration (BridgeHttpServer.OnBeforeAssemblyReload →
+        // _listener.Stop()). classifyInstance folds both lock states
+        // "reloading" and "compiling" into the "reloading" classification
+        // (instance-discovery.ts) — so a single check covers the whole compile +
+        // reload window. Wait it out, then signal the caller to retry.
+        if (classification === "reloading") {
+            const waitError = await this.waitForCompile();
+            if (waitError)
+                return waitError; // timed out or dead_bridge mid-wait
+            return null; // recovered — caller retries the original operation
+        }
+        // No reload signal but a transient refusal/reset/timeout. Retry a bounded
+        // number of times with backoff before declaring offline. Covers brief
+        // socket churn that isn't reflected in the lock yet. The bounds come from
+        // the env-overridable retry tunables (M23 Plan 3 / retry-policy.ts).
+        const maxAttempts = this.retry.transientRetryAttempts;
+        const backoffMs = this.retry.transientBackoffMs;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            await sleep(backoffMs * attempt);
+            // Re-classify on each attempt: a reload may have begun between the
+            // first failure and now.
+            const reclass = this.classifyLockNow();
+            if (reclass === "dead_bridge")
+                return this.deadBridgeResult();
+            if (reclass === "reloading") {
+                const waitError = await this.waitForCompile();
+                if (waitError)
+                    return waitError;
+                return null;
+            }
+            // Probe whether the listener is back up.
+            try {
+                const res = await this.fetchWithTimeout("/ping", { method: "GET" });
+                if (res.ok || res.status === 503) {
+                    // Listener responded — recovered. Caller re-runs its readiness /
+                    // POST. (503 still counts: it means compiling, handled on retry.)
+                    return null;
+                }
+            }
+            catch {
+                // Still down — loop and back off again.
+            }
+        }
+        void operation; // log-only parameter, reserved for future telemetry
+        const retryMsg = `Bridge is not reachable at ${this.baseUrl} after ${maxAttempts} retries. ${buildOfflineHint(this.projectPath)}`;
+        return makeErrorResult({
+            code: "bridge_offline",
+            message: retryMsg,
+            detail: {
+                error: {
+                    code: "bridge_offline",
+                    message: retryMsg,
+                },
+            },
+        });
+    }
+    /**
+     * Re-resolve the bridge endpoint (port + authToken) from the on-disk instance
+     * lock and update the cached {@link baseUrl} / {@link authToken} when the
+     * live bridge has moved. Returns true when the endpoint changed.
+     *
+     * This is the single fix for two coupled failure modes (specs/feedback.md
+     * entries 2 + 4A): the client cached the port/token once at construction,
+     * so a Unity restart (new PID/port/authToken in the lock) left every retry
+     * hitting a dead listener — producing minutes of `bridge_offline` *and*
+     * (because {@link postTool} re-POSTs on recovery) duplicate side-effects
+     * once the editor came back. Refreshing here lets a restart self-heal.
+     *
+     * No-op (returns false) when there is no projectPath, an env-port override
+     * is in force (env is authoritative — no lock to read, matching
+     * resolvePort/resolveAuthToken), or the lock is missing/its PID is dead/
+     * nothing actually changed. Never throws — readInstanceLock/isPidAlive are
+     * already fault-tolerant.
+     */
+    refreshEndpointFromLock() {
+        if (!this.projectPath)
+            return false;
+        if (typeof this.envPort === "number")
+            return false; // env override wins
+        let lock;
+        try {
+            lock = readInstanceLock(this.projectPath);
+        }
+        catch {
+            return false;
+        }
+        if (!lock)
+            return false;
+        if (!isPidAlive(lock.pid))
+            return false;
+        const portChanged = typeof lock.port === "number" &&
+            lock.port > 0 &&
+            this.baseUrl !== `http://127.0.0.1:${lock.port}`;
+        const tokenChanged = lock.authToken !== this.authToken;
+        if (!portChanged && !tokenChanged)
+            return false;
+        if (portChanged)
+            this.baseUrl = `http://127.0.0.1:${lock.port}`;
+        if (tokenChanged)
+            this.authToken = lock.authToken;
+        return true;
+    }
+    /**
+     * Read + classify the instance lock at the current moment, without throwing.
+     * Returns "gone" (treated as no-signal) when the lock can't be read or the
+     * project path is unknown. T-fix-2 helper.
+     */
+    classifyLockNow() {
+        if (!this.projectPath)
+            return "gone";
+        try {
+            return classifyInstance(readInstanceLock(this.projectPath));
+        }
+        catch {
+            return "gone";
+        }
+    }
     // Detect the dead-bridge-assembly signature from the on-disk instance lock:
     // Unity process alive (PID running) but heartbeat stale (the bridge's
     // [InitializeOnLoad] never re-ran after a compile failure, so the heartbeat
@@ -433,14 +782,15 @@ export class LiveClient {
         };
     }
     async waitForCompile() {
-        const deadline = Date.now() + MAX_COMPILE_WAIT_MS;
+        const compileWaitMs = this.retry.compileWaitMs;
+        const deadline = Date.now() + compileWaitMs;
         // M13 T4.5 — run the launch-errors / Safe Mode dialog auto-dismiss loop
         // CONCURRENTLY with the compile poll. The dismiss loop ticks on the same
-        // stall point this method represents (UCP bridge-wait pattern): if a
-        // native modal is blocking the Editor, the compile poll below will spin
-        // until timeout with no recovery. The dismiss loop clicks Ignore on that
-        // modal; the moment compile resolves (compiling → idle), we abort the
-        // loop — there is no launch dialog left to dismiss once Unity is idle.
+        // stall point this method represents: if a native modal is blocking the
+        // Editor, the compile poll below will spin until timeout with no recovery.
+        // The dismiss loop clicks Ignore on that modal; the moment compile
+        // resolves (compiling → idle), we abort the loop — there is no launch
+        // dialog left to dismiss once Unity is idle.
         //
         // When auto-dismiss is opted out (UNITY_OPEN_MCP_NO_AUTO_DISMISS_LAUNCH_ERRORS=1),
         // `dismissEnabled` is false and this branch is skipped entirely,
@@ -452,13 +802,15 @@ export class LiveClient {
             const dismissOpts = {
                 timeoutMs: this.dismissTimeoutMs,
                 intervalMs: this.dismissIntervalMs,
+                policy: this.dialogPolicy,
+                allowProjectUpgrade: this.allowProjectUpgrade,
                 abortSignal: dismissAbort.signal,
             };
             dismissDone = this.runDismissLoop(dismissOpts);
         }
         try {
             while (Date.now() < deadline) {
-                await sleep(COMPILE_POLL_INTERVAL_MS);
+                await sleep(this.retry.compilePollIntervalMs);
                 try {
                     const res = await this.fetchWithTimeout("/ping", { method: "GET" });
                     if (res.status === 503)
@@ -489,12 +841,12 @@ export class LiveClient {
                 return deadBridge;
             return makeErrorResult({
                 code: "compile_timeout",
-                message: `Unity is still compiling after ${MAX_COMPILE_WAIT_MS / 1000}s. ` +
+                message: `Unity is still compiling after ${compileWaitMs / 1000}s. ` +
                     "The compile-wait timeout was exceeded.",
                 detail: {
                     error: {
                         code: "compile_timeout",
-                        message: `Compile-wait exceeded ${MAX_COMPILE_WAIT_MS / 1000}s`,
+                        message: `Compile-wait exceeded ${compileWaitMs / 1000}s`,
                     },
                 },
             });
@@ -507,13 +859,13 @@ export class LiveClient {
         }
     }
     /**
-     * Run the launch-errors dismiss polling loop. Indirected through a method
+     * Run the startup-dialog dismiss polling loop. Indirected through a method
      * so unit tests can stub the OS-clicking loop without invoking
      * PowerShell / osascript / xdotool. Production uses the real
-     * `pollAndDismissLaunchErrors`.
+     * `pollAndDismissDialogs`.
      */
     runDismissLoop(opts) {
-        return pollAndDismissLaunchErrors(opts);
+        return pollAndDismissDialogs(opts);
     }
     async readResource(route) {
         try {
@@ -563,6 +915,105 @@ export class LiveClient {
             return null;
         }
     }
+    // -------------------------------------------------------------------------
+    // M23 Plan 3 — compile-verify annotation (compile_noop / dll_stale).
+    //
+    // For compile-reload tools we capture a before/after snapshot and let the
+    // pure detectCompileVerify() flag a no-op or stale compile. The annotation
+    // is additive (`_compileVerify` on the result body) — it never blocks a
+    // successful response, only surfaces a structured signal so an agent can
+    // branch instead of trusting a no-op success. Snapshots degrade gracefully:
+    // if the bridge inventory or DLL mtimes can't be read, the fields are
+    // undefined and the detector returns null (no false positive).
+    // -------------------------------------------------------------------------
+    /**
+     * Capture a compile-verify snapshot: the bridge tool inventory count + the
+     * newest mtime under Library/ScriptAssemblies. Returns undefined fields
+     * (never throws) when the bridge or filesystem is unavailable.
+     */
+    async captureCompileSnapshot() {
+        const snap = {};
+        try {
+            const inventory = await this.listBridgeTools();
+            if (inventory)
+                snap.bridgeToolCount = inventory.tools.size;
+        }
+        catch {
+            // best-effort — undefined count is a valid "unknown" snapshot
+        }
+        const dllMtime = this.newestScriptAssembliesMtime();
+        if (dllMtime !== undefined)
+            snap.dllMtimeMs = dllMtime;
+        return snap;
+    }
+    /**
+     * Newest mtime (epoch ms) of `Library/ScriptAssemblies/*.dll` for this
+     * project, or undefined when the directory is missing/unreadable. Used by
+     * the compile-verify detector to tell whether a recompile actually advanced
+     * the compiled output.
+     */
+    newestScriptAssembliesMtime() {
+        if (!this.projectPath)
+            return undefined;
+        const dir = join(this.projectPath, "Library", "ScriptAssemblies");
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return undefined;
+        }
+        let newest;
+        for (const name of entries) {
+            if (!name.endsWith(".dll"))
+                continue;
+            try {
+                const m = statSync(join(dir, name)).mtimeMs;
+                if (newest === undefined || m > newest)
+                    newest = m;
+            }
+            catch {
+                // best-effort per file
+            }
+        }
+        return newest;
+    }
+    /**
+     * Apply the compile-verify annotation to a successful compile-reload result.
+     * Reads the after-snapshot, runs the pure detector, and — when flagged —
+     * injects `_compileVerify: { code, recommendation }` into the result body.
+     * The source-edit mtime is inferred from `args._sourceMtimeMs` when the
+     * caller (e.g. script_write) supplied it; otherwise only the no-op path
+     * (count + dll-mtime delta) is evaluated.
+     */
+    async annotateCompileVerify(_toolName, result, before, args) {
+        const after = await this.captureCompileSnapshot();
+        const sourceMtimeMs = typeof args._sourceMtimeMs === "number"
+            ? args._sourceMtimeMs
+            : undefined;
+        const detection = detectCompileVerify({ before, after, sourceMtimeMs });
+        const annotation = buildCompileVerifyAnnotation(detection);
+        if (annotation === null)
+            return result;
+        // Inject into the first text content block's JSON body. Mirrors the
+        // injectRouteMeta shape in tool-router.ts.
+        const textIndex = result.content.findIndex((c) => c.type === "text");
+        if (textIndex < 0)
+            return result;
+        const block = result.content[textIndex];
+        if (block.type !== "text")
+            return result;
+        try {
+            const body = JSON.parse(block.text);
+            body._compileVerify = annotation;
+            const newContent = result.content.slice();
+            newContent[textIndex] = { type: "text", text: JSON.stringify(body) };
+            return { ...result, content: newContent };
+        }
+        catch {
+            return result;
+        }
+    }
     fetchWithTimeout(path, init, timeoutMs = PING_TIMEOUT_MS) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -573,6 +1024,12 @@ export class LiveClient {
         if (this.authToken && !headers.has("Authorization")) {
             headers.set("Authorization", `Bearer ${this.authToken}`);
         }
+        // M23 Plan 3 — attach the agent identity so the bridge's fair round-robin
+        // queue can schedule across agents sharing one bridge. Merge so a caller-
+        // supplied header (rare) wins.
+        if (this.agentId && !headers.has("X-Agent-Id")) {
+            headers.set("X-Agent-Id", this.agentId);
+        }
         return fetch(`${this.baseUrl}${path}`, {
             ...init,
             headers,