unity-open-mcp 0.6.1 → 0.8.2

package/dist/live-client.js

@@ -1,5 +1,6 @@
+import { BridgeToolsCache } from "./bridge-tools-cache.js";
 import { deriveIsError } from "./gate-error.js";
-import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { pollAndDismissDialogs, readDismissConfig, } from "./dialog-dismiss.js";
 import { readInstanceLock, classifyInstance, lockPath, isPidAlive, statusDir, hasRecentPendingTestRun } from "./instance-discovery.js";
@@ -53,6 +54,39 @@ const DIRECT_RESPONSE_TOOLS = new Set([
     "unity_senses_profiler_rendering",
     "unity_senses_spatial_query",
 ]);
+// M4 — compile-reload tools whose PURPOSE is to trigger or observe a domain
+// reload, so a no-op compile is a meaningful signal worth annotating. This is
+// the annotation target set; it is a strict subset of the lifecycle
+// `compile-reload` class (capabilities/lifecycle.ts). The three "invoke
+// arbitrary code" tools — execute_csharp, invoke_method, execute_menu — are
+// deliberately EXCLUDED: they are classified `compile-reload` on the recovery
+// axis (the invoked code *can* trigger a reload), but most invocations
+// compile nothing, so the no-op detector fired a false `compile_noop` on
+// every such call (e.g. `execute_csharp {code:"return 42;"}` came back
+// carrying a "force a rebuild" recommendation). scene_open is also excluded:
+// its reload concern is unsaved-scene loss, not a script compile.
+const COMPILE_RELOAD_ANNOTATION_TOOLS = new Set([
+    "unity_open_mcp_asmdef_create",
+    "unity_open_mcp_asmdef_modify",
+    "unity_open_mcp_script_write",
+    "unity_open_mcp_script_delete",
+    "unity_open_mcp_build_set_target",
+    "unity_open_mcp_build_set_defines",
+    "unity_open_mcp_settings_set_player",
+    "unity_open_mcp_package_add",
+    "unity_open_mcp_package_remove",
+    "unity_open_mcp_reimport_package",
+    "unity_open_mcp_compile_check",
+]);
+/**
+ * M4 — should the compile-verify annotation run for this tool? Returns true
+ * only for compile-reload tools that reliably trigger (or observe) a domain
+ * reload, so the no-op detector is not handed a trivially-unchanged snapshot
+ * for tools whose normal success involves no recompile.
+ */
+function shouldAnnotateCompileVerify(toolName) {
+    return COMPILE_RELOAD_ANNOTATION_TOOLS.has(toolName);
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -130,6 +164,14 @@ function buildOfflineHint(projectPath) {
 export class LiveClient {
     baseUrl;
     pingCache;
+    /**
+     * M31-optimizations Plan 1 / M3 — short-TTL cache for the compiled-state
+     * tool inventory (`GET /tools`). The compiled-tool set changes only on a
+     * bridge recompile, but the meta-tools re-fetched it per call. Invalidated
+     * from the same lifecycle hooks as PingCache (handleTransientOffline,
+     * waitForCompile settle) so a reload or compile is observed promptly.
+     */
+    bridgeToolsCache;
     dismissEnabled;
     dismissTimeoutMs;
     dismissIntervalMs;
@@ -176,11 +218,22 @@ export class LiveClient {
     constructor(port, pingCache, authToken, projectPath, agentId = PROCESS_AGENT_ID, envPort) {
         this.baseUrl = bridgeBaseUrl(port);
         this.pingCache = pingCache;
+        this.bridgeToolsCache = new BridgeToolsCache();
         this.authToken = authToken;
         this.projectPath = projectPath;
         this.retry = readRetryTunables();
         this.agentId = agentId;
-        this.envPort = envPort;
+        // A port of 0 / negative / non-integer is not a real env override. Treating
+        // 0 as authoritative would permanently disable the mid-session endpoint
+        // refresh that re-points at a restarted Unity bridge (refreshEndpointFromLock
+        // bails when envPort is a number). Normalize those to undefined so the
+        // lock-driven self-healing path stays live. getEnv() already filters this,
+        // but the client is the contract owner and is also reached by per-request
+        // port overrides, so defend here too.
+        this.envPort =
+            typeof envPort === "number" && Number.isInteger(envPort) && envPort >= 1
+                ? envPort
+                : undefined;
         // 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
@@ -217,9 +270,9 @@ export class LiveClient {
             console.warn(result.message);
         }
     }
-    async isLiveAvailable() {
+    async isLiveAvailable(fetchTimeoutMs) {
         try {
-            const res = await this.fetchWithTimeout("/ping", { method: "GET" });
+            const res = await this.fetchWithTimeout("/ping", { method: "GET" }, fetchTimeoutMs);
             if (res.status === 503)
                 return true;
             if (!res.ok)
@@ -233,6 +286,15 @@ export class LiveClient {
             return false;
         }
     }
+    /**
+     * M14 — return the most recent cached /ping snapshot (any age), or null when
+     * no successful probe has populated the cache. Used by the CLI ping poller
+     * so a single {@link isLiveAvailable} probe answers BOTH "is it up?" and
+     * "what's its state?" without a second `/ping` round-trip per poll.
+     */
+    getCachedPing() {
+        return this.pingCache.get();
+    }
     async route(toolName, args) {
         if (toolName === "unity_open_mcp_ping") {
             return this.handlePing();
@@ -245,6 +307,37 @@ export class LiveClient {
     async handlePing() {
         try {
             const res = await this.fetchWithTimeout("/ping", { method: "GET" });
+            // L3 — mirror ensureReady's status discipline. A 503 is the bridge's
+            // "compiling / listener starting" signal (non-JSON body): report it as
+            // compiling, never as a generic offline or a successful ping. A non-OK
+            // status (401/500/…) must not be parsed as PingResponse and cached — the
+            // error body would set `connected`/`compiling` to undefined and be
+            // reported as isError:false on later cache hits. Only a 2xx carries a
+            // valid PingResponse worth recording.
+            if (res.status === 503) {
+                return makeErrorResult({
+                    code: "compiling",
+                    message: `Bridge at ${this.baseUrl} is compiling / restarting its listener (HTTP 503).`,
+                    detail: {
+                        error: {
+                            code: "compiling",
+                            message: "Bridge listener is not ready (HTTP 503).",
+                        },
+                    },
+                });
+            }
+            if (!res.ok) {
+                return makeErrorResult({
+                    code: "bridge_error",
+                    message: `Bridge /ping returned unexpected HTTP ${res.status}.`,
+                    detail: {
+                        error: {
+                            code: "bridge_error",
+                            message: `HTTP ${res.status}`,
+                        },
+                    },
+                });
+            }
             const body = await res.json();
             this.pingCache.record(body);
             this.maybeWarnCompat(body.bridgeVersion);
@@ -285,10 +378,21 @@ export class LiveClient {
         // 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.
+        //
+        // M4 — gate the annotation on tools that RELIABLY trigger a domain reload,
+        // not on the lifecycle class. `execute_csharp` / `invoke_method` /
+        // `execute_menu` are classified `compile-reload` (the recovery axis: they
+        // *can* trigger a reload if the invoked code does) but most invocations
+        // compile nothing, so `countUnchanged && dllDidNotAdvance` is trivially
+        // true and every such call came back carrying a false `compile_noop`
+        // warning that told the agent to "force a rebuild" after `return 42;`.
+        // The set below is the subset of compile-reload tools whose PURPOSE is to
+        // trigger or observe a recompile; see `shouldAnnotateCompileVerify`.
         const isCompileReload = lifecycleFor(toolName).class === "compile-reload";
-        const before = isCompileReload ? await this.captureCompileSnapshot() : null;
+        const annotate = isCompileReload && shouldAnnotateCompileVerify(toolName);
+        const before = annotate ? await this.captureCompileSnapshot() : null;
         const result = await this.postTool(toolName, args, true);
-        if (isCompileReload && !result.isError && before !== null) {
+        if (annotate && !result.isError && before !== null) {
             return this.annotateCompileVerify(toolName, result, before, args);
         }
         return result;
@@ -325,38 +429,128 @@ export class LiveClient {
         const minIntervalMs = 250;
         const maxIntervalMs = 1_000;
         const resultsPath = join(statusDir(), `test-results-${runId}.json`);
+        // M9 (round-2 review) — read the results file atomically. The bridge writes
+        // it with a plain `File.WriteAllText` (TestRunnerService.cs:104), which is
+        // NOT atomic: a poll landing mid-write observes a partial/truncated body.
+        // The previous implementation did `existsSync` → `readFileSync` →
+        // `unlinkSync` in one shot, so a mid-write read produced unparseable JSON
+        // that was reported as a bogus failure AND deleted (the only copy of the
+        // results). To avoid that, require the file's size + mtime to be STABLE
+        // across two probes before consuming it, and NEVER unlink a body that
+        // failed to parse — leave it for the next poll (it may still be growing).
+        // `mtimeMs` granularity is platform-dependent (ms on most FSes, 100ns on
+        // NTFS), so size is the primary signal and mtime is the tiebreaker; two
+        // equal `{size, mtimeMs}` snapshots mean no writes landed between them.
+        let prevSnapshot = null;
+        // B-N25 — extract the "read + parse + unlink" consume step so it can run
+        // BOTH inside the stability-gated loop AND once more after the loop. The
+        // stability gate requires two identical probes, so the file is consumed
+        // one poll interval (250 ms – 1 s) AFTER it is first observed. If the
+        // results land inside that last interval before `deadline`, the loop
+        // exits and used to return `test_results_timeout` even though a complete
+        // parseable result was on disk (and since the consume is the only thing
+        // that unlinks, the file was left for the next run to trip over). The
+        // post-loop attempt is a last-chance read with NO stability requirement —
+        // the deadline has passed, so a final single-shot parse is strictly
+        // better than declaring a timeout with a result on disk. Returns the
+        // CallToolResult on a successful parse, or null to keep polling / fall
+        // through to the timeout. `requireStable` gates whether the two-probe
+        // stability check must pass first.
+        const consumeIfReady = (snapshot, requireStable) => {
+            if (snapshot === null)
+                return null;
+            if (requireStable) {
+                const stable = prevSnapshot !== null &&
+                    prevSnapshot.size === snapshot.size &&
+                    prevSnapshot.mtimeMs === snapshot.mtimeMs;
+                if (!stable)
+                    return null;
+            }
+            // Two consecutive identical probes (or the post-loop last chance) → the
+            // bridge has finished writing. Read, then unlink ONLY on a successful
+            // parse so a truncated body is retried on the next iteration instead of
+            // being destroyed.
+            let content;
+            try {
+                content = readFileSync(resultsPath, "utf-8");
+            }
+            catch {
+                // readFileSync threw (e.g. file deleted between stat and read) —
+                // reset the baseline so the next poll re-establishes it.
+                prevSnapshot = null;
+                return null;
+            }
+            let isError = false;
+            try {
+                const parsed = JSON.parse(content);
+                isError = parsed.status === "error";
+            }
+            catch {
+                // Unparseable → the read raced a writer despite the stability check
+                // (rare, e.g. a size match on a still-flushing FS). Do NOT delete:
+                // the next poll re-reads once the writer is done.
+                prevSnapshot = null;
+                return null;
+            }
+            try {
+                unlinkSync(resultsPath);
+            }
+            catch {
+                // best-effort cleanup — the result is already in hand
+            }
+            prevSnapshot = null;
+            return {
+                content: [{ type: "text", text: content }],
+                isError,
+            };
+        };
         let intervalMs = minIntervalMs;
         while (Date.now() < deadline) {
+            let snapshot = null;
             try {
-                if (existsSync(resultsPath)) {
-                    const content = readFileSync(resultsPath, "utf-8");
-                    try {
-                        unlinkSync(resultsPath);
-                    }
-                    catch {
-                        // best-effort cleanup
-                    }
-                    let isError = false;
-                    try {
-                        const parsed = JSON.parse(content);
-                        isError = parsed.status === "error";
-                    }
-                    catch {
-                        // unparseable → treat as error
-                        isError = true;
-                    }
-                    return {
-                        content: [{ type: "text", text: content }],
-                        isError,
-                    };
-                }
+                const st = statSync(resultsPath);
+                snapshot = { size: st.size, mtimeMs: st.mtimeMs };
             }
             catch {
-                // continue polling
+                // File does not exist yet (or vanished between stat and read) — reset
+                // the stability tracker so a brand-new file gets a fresh two-probe
+                // window rather than inheriting a stale snapshot.
+                snapshot = null;
+                prevSnapshot = null;
+            }
+            if (snapshot !== null) {
+                const consumed = consumeIfReady(snapshot, true);
+                if (consumed)
+                    return consumed;
+                // Not yet stable → first sighting of this file, or it changed since
+                // the last probe. B-R2 — refresh the baseline to THIS probe
+                // unconditionally: stability means two CONSECUTIVE identical probes.
+                // Pinning the first-ever snapshot (a `=== null` guard here) meant one
+                // mid-write probe poisoned the baseline forever and the poll burned
+                // the full timeout, rescued only by the post-loop unstable read.
+                prevSnapshot = snapshot;
             }
             await sleep(intervalMs);
             intervalMs = Math.min(intervalMs * 2, maxIntervalMs);
         }
+        // B-N25 — one final last-chance read after the loop. The stability gate
+        // consumes the file one interval after it first appears, so a result that
+        // lands in the final interval used to time out with a parseable file on
+        // disk (and left there for the next run). The deadline has already
+        // passed, so a single-shot parse with no stability requirement is
+        // strictly better than the timeout below: a complete result is returned,
+        // and only a genuinely missing/incomplete file falls through to the
+        // timeout error.
+        try {
+            const st = statSync(resultsPath);
+            const finalSnapshot = { size: st.size, mtimeMs: st.mtimeMs };
+            const consumed = consumeIfReady(finalSnapshot, false);
+            if (consumed)
+                return consumed;
+        }
+        catch {
+            // File is genuinely absent — fall through to the timeout.
+        }
         return makeErrorResult({
             code: "test_results_timeout",
             message: `Test results for run ${runId} were not available within ` +
@@ -384,19 +578,30 @@ export class LiveClient {
      *      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.
+     * The retry/compile contract is unchanged from the former monolithic body
+     * EXCEPT for the recursion bound added in M10 (round-2 review): `attempt`
+     * counts the POST tries so the postTool → handlePostFailure → postTool loop
+     * cannot run forever. `shouldRetryPostAfterFailure` returns true for every
+     * `TypeError`, so if POSTs keep failing at the socket level while `/ping`
+     * answers during recovery, the previous code re-POSTed the mutation each pass
+     * with no depth limit. The bound is `this.retry.transientRetryAttempts + 1`
+     * (1 initial attempt + N retries), matching the documented RETRY_CONFIG
+     * semantics; once exhausted the offline error is surfaced instead of recursing.
      */
-    async postTool(toolName, args, retryOn503) {
+    async postTool(toolName, args, retryOn503, attempt = 1) {
         try {
             const res = await this.postToolFetch(toolName, args, retryOn503);
-            // 503 + compile settled cleanly → re-POST once without 503 retry.
+            // 503 + compile settled cleanly → re-POST once without 503 retry. This is
+            // a deliberate single re-dispatch (retryOn503 flips to false, so a second
+            // 503 surfaces the error), but it still counts as a POST attempt for the
+            // recursion bound.
             if (isCompileRepostSentinel(res)) {
-                return this.postTool(toolName, args, false);
+                return this.postTool(toolName, args, false, attempt + 1);
             }
             return res;
         }
         catch (err) {
-            return this.handlePostFailure(toolName, args, err, retryOn503);
+            return this.handlePostFailure(toolName, args, err, retryOn503, attempt);
         }
     }
     /**
@@ -636,16 +841,34 @@ export class LiveClient {
      * 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.
+     *
+     * M10 (round-2 review) — `attempt` is the 1-based POST attempt counter. When
+     * it exceeds the configured retry budget (`this.retry.transientRetryAttempts`
+     * retries beyond the initial attempt) the offline error is surfaced instead
+     * of recursing. Without this bound `shouldRetryPostAfterFailure` returning
+     * true for every `TypeError` made the loop unbounded: POSTs failing at the
+     * socket level while `/ping` answers during recovery re-POSTed the mutation
+     * each pass forever. The recovery probe inside `handleTransientOffline` is
+     * itself bounded (`transientRetryAttempts` iterations of `/ping`); this outer
+     * bound caps how many times we re-enter that recovery + re-POST cycle.
      */
-    async handlePostFailure(toolName, args, err, retryOn503) {
+    async handlePostFailure(toolName, args, err, retryOn503, attempt) {
         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);
+        // M10 — bound the postTool → handlePostFailure → postTool recursion. The
+        // budget is the initial attempt plus the configured transient retry count.
+        const maxAttempts = 1 + this.retry.transientRetryAttempts;
+        const attemptsExhausted = attempt >= maxAttempts;
+        if (!attemptsExhausted &&
+            shouldRetryPostAfterFailure(err, endpointChanged)) {
+            return this.postTool(toolName, args, retryOn503, attempt + 1);
         }
+        const exhaustedNote = attemptsExhausted
+            ? ` The POST retry budget (${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}) was exhausted after ${attempt} attempt${attempt === 1 ? "" : "s"}; the bridge is reachable by /ping but POSTs keep failing.`
+            : "";
         return makeErrorResult({
             code: "bridge_offline",
             message: `Tool '${toolName}' did not return from the bridge within the client ` +
@@ -654,7 +877,7 @@ export class LiveClient {
                 `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}.`,
+                `complete there; verify the effect before retrying. Endpoint: ${this.baseUrl}.${exhaustedNote}`,
             detail: {
                 error: {
                     code: "bridge_offline",
@@ -664,6 +887,18 @@ export class LiveClient {
         });
     }
     async ensureReady() {
+        // M31-optimizations Plan 1 / H1 — short-circuit the pre-flight probe when
+        // the PingCache has a fresh-enough ready snapshot (connected && !compiling
+        // && within TTL). The cache is updated on every successful /ping, every
+        // waitForCompile poll, and every isLiveAvailable call, so a burst of tool
+        // calls within the TTL collapses to zero extra probes. A `compiling` or
+        // disconnected snapshot forces a fresh probe (never short-circuit those),
+        // and the POST path's 503 / handleTransientOffline handling is unchanged
+        // when a cache hit turns out to be stale — the worst case is the existing
+        // network-probe path.
+        if (this.pingCache.fresh() !== null) {
+            return null;
+        }
         try {
             const res = await this.fetchWithTimeout("/ping", { method: "GET" });
             if (res.status === 503) {
@@ -780,6 +1015,13 @@ export class LiveClient {
         // entry 4A). refreshEndpointFromLock is a no-op when an env-port override
         // is in force or nothing has changed.
         this.refreshEndpointFromLock();
+        // M31-optimizations Plan 1 / M3 — a transient-offline signal means the
+        // bridge may have recompiled or moved endpoints, so the cached tool
+        // inventory is no longer trustworthy. Drop it; the next listBridgeTools
+        // call refetches even within the TTL. (The ping-cache short-circuit in
+        // ensureReady already probes fresh after a transient failure, so the two
+        // caches stay consistent.)
+        this.bridgeToolsCache.invalidate();
         // 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();
@@ -873,7 +1115,7 @@ export class LiveClient {
     refreshEndpointFromLock() {
         if (!this.projectPath)
             return false;
-        if (typeof this.envPort === "number")
+        if (this.envPort !== undefined)
             return false; // env override wins
         let lock;
         try {
@@ -1069,8 +1311,14 @@ export class LiveClient {
                     if (!res.ok)
                         continue;
                     const body = (await res.json());
-                    if (!body.compiling && body.connected)
+                    if (!body.compiling && body.connected) {
+                        // M31-optimizations Plan 1 / M3 — a compile settle means the
+                        // bridge recompiled, so its tool inventory likely changed (new /
+                        // removed scripts, asmdef edits, package_add/remove, …). Drop the
+                        // cache so the next listBridgeTools refetches the fresh set.
+                        this.bridgeToolsCache.invalidate();
                         return null;
+                    }
                 }
                 catch {
                     // Network failure during the poll — normal during a domain reload
@@ -1148,11 +1396,33 @@ export class LiveClient {
      * group availability in `unity_open_mcp_capabilities` and
      * `unity_open_mcp_manage_tools(list_groups)`.
      *
+     * M31-optimizations Plan 1 / M3 — backed by a short-TTL session cache. A
+     * second meta-tool call within the TTL reuses the cached inventory instead
+     * of re-issuing `GET /tools`. The cache is invalidated on dead-bridge /
+     * reload detection ({@link handleTransientOffline}) and on a compile settle
+     * ({@link waitForCompile} exit), so a recompile is observed promptly.
+     *
      * Returns null when the bridge is unreachable or the response is malformed
      * — callers fall back to `available: null` (unknown) so the agent is
      * directed at manage_tools when the bridge comes back up.
      */
     async listBridgeTools() {
+        const cached = this.bridgeToolsCache.get();
+        if (cached !== null)
+            return cached;
+        const fresh = await this.fetchBridgeToolsNow();
+        if (fresh !== null)
+            this.bridgeToolsCache.record(fresh);
+        return fresh;
+    }
+    /**
+     * Fetch the bridge inventory RIGHT NOW, bypassing the TTL cache. Used by
+     * {@link captureCompileSnapshot}, which needs the *actual* post-recompile
+     * tool count to detect a no-op vs. real compile (a cached count would mask
+     * the delta the detector is built around). Also the underlying fetch for
+     * {@link listBridgeTools} when the cache is empty/expired.
+     */
+    async fetchBridgeToolsNow() {
         try {
             const res = await this.fetchWithTimeout("/tools", { method: "GET" }, 5_000);
             if (!res.ok)
@@ -1185,7 +1455,10 @@ export class LiveClient {
     async captureCompileSnapshot() {
         const snap = {};
         try {
-            const inventory = await this.listBridgeTools();
+            // Bypass the TTL cache — the compile-verify detector compares before/
+            // after tool counts to flag a no-op vs. real compile, so a cached count
+            // would mask the very delta the detector is built around.
+            const inventory = await this.fetchBridgeToolsNow();
             if (inventory)
                 snap.bridgeToolCount = inventory.tools.size;
         }
@@ -1268,6 +1541,58 @@ export class LiveClient {
     fetchWithTimeout(path, init, timeoutMs = PING_TIMEOUT_MS) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
+        // M11 — the abort timer must cover the BODY read, not just the headers.
+        // Previously `.finally(() => clearTimeout(timer))` cleared the timer as
+        // soon as `fetch()` resolved (headers arrived), so every later
+        // `res.text()`/`res.json()` ran with no deadline: an Editor that flushed
+        // the headers then froze stalled until undici's 300s body timeout.
+        //
+        // The timer is now cleared only once the body is consumed. Rather than
+        // tee/observe the stream (which can deadlock when a caller never drains
+        // the body), we wrap the Response's `text`/`json`/`arrayBuffer` accessors
+        // so the timer is cleared as part of the body-read promise the caller
+        // already awaits. `disposed` guards against double-clear.
+        //
+        // B-N1 — a pending `setTimeout` is a live libuv handle that keeps Node's
+        // event loop alive. Every status-only return path (the caller inspects the
+        // response and returns without reading the body) left the abort timer
+        // armed for the full `timeoutMs` (40 s minimum on the POST path), so
+        // `npm test` printed all subtests as `ok` then never reached the `# tests`
+        // summary — CI hung. The accessor wrappers alone cannot fix this because a
+        // caller that never touches the body never triggers them. Arm a short
+        // fallback `claimTimer` (unref'd so it never pins the loop on its own):
+        // if the body is read within the grace window, `bodyClaimed` flips and the
+        // fallback becomes a no-op (the abort timer stays armed to protect the
+        // in-progress read); if the body is never claimed, the fallback fires and
+        // disposes, releasing the abort timer's loop handle. The abort timer
+        // itself is NOT unref'd — it must still fire to abort a genuinely stalled
+        // request while the process is alive (the in-progress socket keeps the
+        // loop alive in that case, so the abort lands).
+        //
+        // A-R1 — the claim timer is armed inside the fetch *fulfilled* handler
+        // (below, next to the accessor wrappers), NOT here at request creation.
+        // `bodyClaimed` can only flip once the Response exists, so an
+        // arm-at-creation timer fired before the headers arrived on any request
+        // slower than 100 ms and disposed the abort timer — disabling every fetch
+        // timeout exactly in the hung-Editor cases it exists for. Arming after
+        // the headers arrive means the grace window starts when the caller can
+        // first claim the body; until then the abort timer alone bounds the
+        // headers phase. On fetch rejection no claim timer was ever armed and the
+        // rejection handler disposes the abort timer directly.
+        let disposed = false;
+        let bodyClaimed = false;
+        let claimTimer;
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            clearTimeout(timer);
+            if (claimTimer !== undefined)
+                clearTimeout(claimTimer);
+        };
+        const markBodyClaimed = () => {
+            bodyClaimed = true;
+        };
         // M14 — attach the bearer token to every request when one was discovered
         // from the instance lock. Merge with any caller-supplied headers so we
         // never clobber a per-request value.
@@ -1285,7 +1610,39 @@ export class LiveClient {
             ...init,
             headers,
             signal: controller.signal,
-        }).finally(() => clearTimeout(timer));
+        }).then((res) => {
+            // Wrap the body-reading accessors so the abort timer is cleared when
+            // the body is consumed (the common path) or errors. The wrappers
+            // delegate to the original methods; they only add the dispose() side
+            // effect. Non-body responses (no body) clear the timer immediately.
+            const origText = res.text.bind(res);
+            const origJson = res.json.bind(res);
+            const origArrayBuffer = res.arrayBuffer.bind(res);
+            res.text = () => { markBodyClaimed(); return origText().finally(dispose); };
+            res.json = () => { markBodyClaimed(); return origJson().finally(dispose); };
+            res.arrayBuffer = () => { markBodyClaimed(); return origArrayBuffer().finally(dispose); };
+            if (!res.body) {
+                dispose();
+            }
+            else {
+                // A-R1 — short grace window for the caller to claim the body,
+                // armed only now that the Response (and thus the accessors) exist.
+                // Long enough that a synchronous `await res.text()` after an
+                // `await fetchWithTimeout(...)` always wins; short enough that a
+                // status-only caller releases its handles promptly (B-N1). If the
+                // body WAS claimed, the fallback is a no-op — the abort timer
+                // remains armed to protect the in-progress read.
+                claimTimer = setTimeout(() => {
+                    if (!bodyClaimed)
+                        dispose();
+                }, 100);
+                claimTimer.unref();
+            }
+            return res;
+        }, (err) => {
+            dispose();
+            throw err;
+        });
     }
 }
 //# sourceMappingURL=live-client.js.map