chainlesschain 0.165.5 → 0.165.8

package/src/harness/mcp-client.js

@@ -10,6 +10,7 @@
 
 import { executionBroker } from "../lib/process-execution-broker/index.js";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 import { EventEmitter } from "events";
 import { pathToFileURL } from "url";
 import { isProxy } from "node:util/types";
@@ -45,6 +46,17 @@ import {
   prepareMcpStdioExecutableIdentity,
 } from "../lib/mcp-stdio-executable-identity.js";
 import { resolveMcpStdioSandboxContext } from "../lib/mcp-stdio-workspace-authority.js";
+import {
+  assertManagedMcpTlsConfig,
+  closeMcpTlsDispatcher,
+  createMcpTlsDispatcher,
+  loadMcpTlsMaterial,
+} from "../lib/mcp-tls.js";
+import {
+  MCP_LIFECYCLE_ERROR_CODES,
+  MCP_LIFECYCLE_PHASES,
+  McpLifecycleAuthority,
+} from "../lib/mcp-lifecycle-authority.js";
 
 /**
  * Injectable dependencies — overridable from tests.
@@ -63,6 +75,9 @@ export const _deps = {
   verifyMcpStdioApprovedWorkingDirectory,
   prepareMcpStdioExecutableIdentity,
   resolveMcpStdioSandboxContext,
+  loadMcpTlsMaterial,
+  createMcpTlsDispatcher,
+  closeMcpTlsDispatcher,
   // Backoff sleep seam (tests override with a no-op so retries don't wait).
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
@@ -229,7 +244,124 @@ const MCP_HTTP_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
  * hard 30s regardless of its config — an inconsistency with HTTP servers.
  */
 const STDIO_REQUEST_TIMEOUT_MS = 30000;
+// Long-running MCP tools are allowed to exceed the ordinary request deadline,
+// but may not retain an agent turn forever without any protocol progress. A
+// server-specific value can only tighten this host ceiling; zero/invalid values
+// never disable it.
+const MCP_TOOL_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+const MCP_DISCOVERY_CACHE_TTL_MS = 60 * 1000;
+const MCP_DISCOVERY_CACHE_MAX_STALE_MS = 10 * 60 * 1000;
+const MCP_DISCOVERY_CACHE_MAX_STRIKES = 2;
 const MCP_PROTOCOL_VERSION = "2025-11-25";
+export const SUPPORTED_MCP_PROTOCOL_VERSIONS = Object.freeze([
+  "2024-11-05",
+  "2025-03-26",
+  "2025-06-18",
+  MCP_PROTOCOL_VERSION,
+]);
+const supportedMcpProtocolVersions = new Set(SUPPORTED_MCP_PROTOCOL_VERSIONS);
+
+function mcpToolIdleTimeoutMs(config, options = {}) {
+  const candidate = Number.isFinite(options.idleTimeoutMs)
+    ? options.idleTimeoutMs
+    : config?.toolIdleTimeoutMs;
+  if (Number.isFinite(candidate) && candidate > 0) {
+    return Math.min(MCP_TOOL_IDLE_TIMEOUT_MS, Math.floor(candidate));
+  }
+  return MCP_TOOL_IDLE_TIMEOUT_MS;
+}
+
+function mcpToolIdleTimeoutError(serverName, toolName, timeoutMs) {
+  const error = new Error(
+    `MCP tool "${toolName}" on server "${serverName}" made no progress for ${timeoutMs}ms`,
+  );
+  error.code = "CC_MCP_TOOL_IDLE_TIMEOUT";
+  error.timeoutMs = timeoutMs;
+  return error;
+}
+
+function boundedPositiveInt(value, fallback, maximum) {
+  if (!Number.isFinite(value) || value <= 0) return fallback;
+  return Math.min(maximum, Math.floor(value));
+}
+
+function discoveryCachePolicy(config = {}) {
+  const configured = config?.discoveryCache;
+  if (configured !== true && (!configured || typeof configured !== "object")) {
+    return { enabled: false };
+  }
+  if (configured?.enabled === false) return { enabled: false };
+  const fields = configured === true ? {} : configured;
+  const ttlMs = boundedPositiveInt(
+    fields.ttlMs,
+    MCP_DISCOVERY_CACHE_TTL_MS,
+    MCP_DISCOVERY_CACHE_MAX_STALE_MS,
+  );
+  const maxStaleMs = boundedPositiveInt(
+    fields.maxStaleMs,
+    MCP_DISCOVERY_CACHE_MAX_STALE_MS,
+    24 * 60 * 60 * 1000,
+  );
+  return {
+    enabled: true,
+    ttlMs,
+    maxStaleMs: Math.max(ttlMs, maxStaleMs),
+    maxStrikes: boundedPositiveInt(
+      fields.maxStrikes,
+      MCP_DISCOVERY_CACHE_MAX_STRIKES,
+      10,
+    ),
+  };
+}
+
+function discoveryCapabilitiesSignature(capabilities) {
+  const value =
+    capabilities && typeof capabilities === "object" ? capabilities : {};
+  return JSON.stringify({
+    tools: value.tools !== undefined,
+    resources: value.resources !== undefined,
+    prompts: value.prompts !== undefined,
+  });
+}
+
+function discoveryCacheKey(name, entry) {
+  const config = entry?.config || {};
+  // This key never leaves process memory. Bind to an endpoint/launcher so a
+  // same-named server pointed at a different target cannot inherit tools.
+  return JSON.stringify([
+    String(name),
+    entry?.transportKind || inferTransport(config),
+    entry?.httpUrl || entry?.socketUrl || config.url || null,
+    config.command || null,
+    Array.isArray(config.args) ? config.args : [],
+  ]);
+}
+
+function cloneDiscoveryList(value) {
+  return Array.isArray(value)
+    ? value.map((item) =>
+        item && typeof item === "object" ? { ...item } : item,
+      )
+    : [];
+}
+
+function applyDiscoveryCache(entry, cached) {
+  entry.resources = cloneDiscoveryList(cached.resources);
+  entry.resourceTemplates = cloneDiscoveryList(cached.resourceTemplates);
+  entry.prompts = cloneDiscoveryList(cached.prompts);
+  entry.toolsError = null;
+}
+
+export function assertSupportedMcpProtocolVersion(value) {
+  if (typeof value !== "string" || !supportedMcpProtocolVersions.has(value)) {
+    const error = new Error(
+      "MCP server selected an unsupported protocol version",
+    );
+    error.code = "CC_MCP_PROTOCOL_VERSION_UNSUPPORTED";
+    throw error;
+  }
+  return value;
+}
 const URL_ELICITATION_REQUIRED = -32042;
 const MCP_RPC_ERROR_CODE = "CC_MCP_RPC_ERROR";
 const mcpRpcControlData = new WeakMap();
@@ -885,6 +1017,10 @@ function isMcpNonRetryableProtocolError(error) {
   );
 }
 
+function isMcpFatalDiscoveryError(error) {
+  return isMcpNonRetryableProtocolError(error) || isMcpJsonBudgetError(error);
+}
+
 /**
  * Heuristic: does this error look like the server went away (vs. the tool
  * itself failing)? Used to gate reconnect-and-retry for servers that have a
@@ -1287,8 +1423,27 @@ export class MCPClient extends EventEmitter {
     this._nextId = 1;
     this._reconnectors = new Map(); // name → async () => config|null
     this._reconnecting = new Map(); // name → in-flight reconnect promise
+    // progressToken → reset-idle callback for in-flight tools/call requests.
+    // Tokens are generated by this client and are removed on every terminal
+    // path, so a peer notification cannot retain timers or request state.
+    this._toolProgress = new Map();
+    // Capability metadata stays process-local by default. A server must opt in
+    // through `discoveryCache`; each reconnect still performs initialize and
+    // all policy/transport admission before a cache entry is considered.
+    this._discoveryCache =
+      options?.discoveryCache instanceof Map
+        ? options.discoveryCache
+        : new Map();
+    // Desired resource subscriptions outlive a single transport entry. Keeping
+    // them on the client lets a later reconnect retry restoration even when a
+    // previous partial reconnect was torn down fail-closed.
+    this._resourceSubscriptions = new Map(); // name → Set<uri>
+    this._lifecycleAttempts = new Map(); // name → latest durable generation token
     this._sessionId =
       options && options.sessionId != null ? String(options.sessionId) : null;
+    this._lifecycleSessionId = this._sessionId || "default";
+    this._lifecycleAuthority =
+      options?.lifecycleAuthority || new McpLifecycleAuthority();
     this._workspaceBinding =
       options?.workspaceBinding || currentHostHooksV2WorkspaceBinding();
     // MCP roots capability (Claude-Code 2.1.203 parity): servers may ask the
@@ -1848,6 +2003,90 @@ export class MCPClient extends EventEmitter {
    */
   setSessionId(id) {
     this._sessionId = id != null && id !== "" ? String(id) : null;
+    if (this.servers.size === 0) {
+      this._lifecycleSessionId = this._sessionId || "default";
+    }
+  }
+
+  lifecycleSnapshot(name) {
+    return this._lifecycleAuthority.snapshot({
+      name,
+      sessionId: this._lifecycleSessionId,
+    });
+  }
+
+  _transitionLifecycle(
+    entry,
+    phase,
+    details = {},
+    { tolerateFence = false } = {},
+  ) {
+    if (!entry?._lifecycleAttempt) return null;
+    try {
+      return this._lifecycleAuthority.transition(
+        entry._lifecycleAttempt,
+        phase,
+        details,
+      );
+    } catch (error) {
+      if (tolerateFence && error?.code === MCP_LIFECYCLE_ERROR_CODES.FENCED) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  _registerLifecycleRpc(entry, requestId, method) {
+    if (!entry?._lifecycleAttempt) return null;
+    return this._lifecycleAuthority.registerRpc(
+      entry._lifecycleAttempt,
+      requestId,
+      method,
+    );
+  }
+
+  _settleLifecycleRpc(entry, requestId, outcome) {
+    if (!entry?._lifecycleAttempt) return true;
+    return this._lifecycleAuthority.settleRpc(
+      entry._lifecycleAttempt,
+      requestId,
+      outcome,
+    );
+  }
+
+  _staleLifecycleCallbackError() {
+    const error = new Error(
+      "MCP callback belongs to a stale lifecycle generation",
+    );
+    error.code = MCP_LIFECYCLE_ERROR_CODES.FENCED;
+    return error;
+  }
+
+  _rejectUnexpectedLifecycleRpc(entry, requestId, reason) {
+    if (!entry?._lifecycleAttempt) return false;
+    return this._lifecycleAuthority.rejectUnexpectedRpc(
+      entry._lifecycleAttempt,
+      requestId,
+      reason,
+    );
+  }
+
+  _failLifecycle(entry, error) {
+    try {
+      return this._transitionLifecycle(
+        entry,
+        MCP_LIFECYCLE_PHASES.FAILED,
+        { reasonCode: error?.code || "CC_MCP_TRANSPORT_FAILED" },
+        { tolerateFence: true },
+      );
+    } catch (transitionError) {
+      if (
+        transitionError?.code === MCP_LIFECYCLE_ERROR_CODES.INVALID_TRANSITION
+      ) {
+        return null;
+      }
+      return null;
+    }
   }
 
   /**
@@ -1990,11 +2229,27 @@ export class MCPClient extends EventEmitter {
    * @param {string} name - Server name
    * @param {object} config - { command?, args?, env?, url?, transport? }
    */
-  async connect(name, config, _authRetryUsed = false) {
+  async connect(name, config, internalOptions = false) {
     if (this.servers.has(name)) {
       throw new Error(`Server "${name}" already connected`);
     }
 
+    const internal =
+      internalOptions && typeof internalOptions === "object"
+        ? internalOptions
+        : { authRetryUsed: internalOptions === true };
+    const authRetryUsed = internal.authRetryUsed === true;
+    if (config?.disabled === true || config?.enabled === false) {
+      this._lifecycleAuthority.markDisabled({
+        name,
+        sessionId: this._lifecycleSessionId,
+        config,
+      });
+      const error = new Error(`MCP server "${name}" is disabled`);
+      error.code = MCP_LIFECYCLE_ERROR_CODES.DISABLED;
+      throw error;
+    }
+
     const transportKind = inferTransport(config);
     let stdioExecutionApproval = null;
     let approvedStdioInvocation = null;
@@ -2082,11 +2337,46 @@ export class MCPClient extends EventEmitter {
         };
       }
     }
-    const connectionHeaders = await this._connectionHeaders(
-      name,
-      sourceConfig,
-      transportKind,
-    );
+    const lifecycleAttempt =
+      internal.lifecycleAttempt ||
+      this._lifecycleAuthority.beginConnection({
+        name,
+        sessionId: this._lifecycleSessionId,
+        config: sourceConfig,
+        reconnect: internal.reconnect === true,
+        explicitEnable: true,
+      });
+    this._lifecycleAttempts.set(name, lifecycleAttempt);
+    let tlsMaterial = null;
+    let connectionHeaders;
+    try {
+      if (sourceConfig.tls != null) {
+        // Source provenance is enforced before header helpers, dispatcher
+        // creation, or any transport work. `configScope` alone is not trusted:
+        // the TLS object must carry the opaque managed-loader provenance too.
+        assertManagedMcpTlsConfig(sourceConfig.tls, {
+          configScope: sourceConfig.configScope,
+        });
+        if (transportKind !== "https" && transportKind !== "wss") {
+          throw mcpTransportError(
+            "CC_MCP_TLS_TRANSPORT_REQUIRED",
+            `MCP TLS configuration requires https or wss (server "${name}")`,
+            { transport: transportKind, url: sourceConfig.url },
+          );
+        }
+        tlsMaterial = _deps.loadMcpTlsMaterial(sourceConfig.tls, {
+          configScope: sourceConfig.configScope,
+        });
+      }
+      connectionHeaders = await this._connectionHeaders(
+        name,
+        sourceConfig,
+        transportKind,
+      );
+    } catch (error) {
+      this._failLifecycle({ _lifecycleAttempt: lifecycleAttempt }, error);
+      throw error;
+    }
     config = { ...runtimeConfig, headers: connectionHeaders };
     const entry = {
       // Keep the source config (static headers + helper command) so every
@@ -2104,6 +2394,8 @@ export class MCPClient extends EventEmitter {
       _httpRequestControllers: new Set(),
       _httpDiscardControllers: new Set(),
       _httpDiscardStopping: false,
+      _httpDispatcher: null,
+      _tlsIdentityDigest: tlsMaterial?.identityDigest || null,
       _disconnectPromise: null,
       _webSocketPayloadError: null,
       _webSocketInboundError: null,
@@ -2111,6 +2403,7 @@ export class MCPClient extends EventEmitter {
       _toolMetadataBytes: 0,
       _stdioExecutionApproval: stdioExecutionApproval,
       _stdioExecutableIdentity: stdioExecutableIdentity,
+      _lifecycleAttempt: lifecycleAttempt,
       tools: [],
       resources: [],
       resourceTemplates: [],
@@ -2157,6 +2450,9 @@ export class MCPClient extends EventEmitter {
         }
         entry.httpUrl = config.url;
         entry.httpHeaders = connectionHeaders;
+        entry._httpDispatcher = tlsMaterial
+          ? _deps.createMcpTlsDispatcher(tlsMaterial)
+          : null;
       } else if (isWebSocketTransport(transportKind)) {
         if (!config.url) {
           throw mcpTransportError(
@@ -2203,6 +2499,7 @@ export class MCPClient extends EventEmitter {
           ...(transportKind === "wss" && config.rejectUnauthorized === false
             ? { rejectUnauthorized: false }
             : {}),
+          ...(tlsMaterial?.connectOptions || {}),
         });
         entry.socket = socket;
 
@@ -2218,6 +2515,7 @@ export class MCPClient extends EventEmitter {
           });
           entry._webSocketPayloadError = error;
           entry.state = ServerState.ERROR;
+          this._failLifecycle(entry, error);
           rejectPending(error);
           this._cancelServerElicitations(name);
           this.emit("server-error", {
@@ -2242,6 +2540,7 @@ export class MCPClient extends EventEmitter {
           }
           entry._webSocketInboundError = error;
           entry.state = ServerState.ERROR;
+          this._failLifecycle(entry, error);
           rejectPending(error);
           this._cancelServerElicitations(name);
           this.emit("server-error", {
@@ -2319,6 +2618,7 @@ export class MCPClient extends EventEmitter {
               { transport: transportKind, url: config.url },
             );
             entry.state = ServerState.ERROR;
+            this._failLifecycle(entry, error);
             rejectPending(error);
             this._cancelServerElicitations(name);
             this.emit("server-error", {
@@ -2353,7 +2653,7 @@ export class MCPClient extends EventEmitter {
             ) {
               throw new Error("expected one JSON-RPC object");
             }
-            this._handleMessage(name, message);
+            this._handleMessage(name, message, entry);
           } catch (cause) {
             if (isMcpJsonBudgetError(cause)) {
               recordInboundFailure(cause);
@@ -2365,6 +2665,7 @@ export class MCPClient extends EventEmitter {
               { transport: transportKind, url: config.url },
             );
             entry.state = ServerState.ERROR;
+            this._failLifecycle(entry, error);
             rejectPending(error);
             this._cancelServerElicitations(name);
             this.emit("server-error", {
@@ -2386,6 +2687,7 @@ export class MCPClient extends EventEmitter {
           const inboundError = entry._webSocketInboundError;
           if (inboundError) {
             entry.state = ServerState.ERROR;
+            this._failLifecycle(entry, inboundError);
             rejectPending(inboundError);
             this._cancelServerElicitations(name);
             this.emit("server-disconnected", {
@@ -2413,6 +2715,7 @@ export class MCPClient extends EventEmitter {
           }
           if (payloadError) {
             entry.state = ServerState.ERROR;
+            this._failLifecycle(entry, payloadError);
             rejectPending(payloadError);
             this._cancelServerElicitations(name);
             this.emit("server-disconnected", {
@@ -2437,6 +2740,7 @@ export class MCPClient extends EventEmitter {
               outcomeUnknown: dispatched,
             },
           );
+          this._failLifecycle(entry, error);
           rejectPending(error);
           this._cancelServerElicitations(name);
           this.emit("server-disconnected", {
@@ -2464,6 +2768,7 @@ export class MCPClient extends EventEmitter {
               outcomeUnknown: dispatched,
             },
           );
+          this._failLifecycle(entry, error);
           rejectPending(error);
           this._cancelServerElicitations(name);
           this.emit("server-error", {
@@ -2579,6 +2884,7 @@ export class MCPClient extends EventEmitter {
             typeof data === "string"
               ? data
               : entry._decoder.decode(data, { stream: true }),
+            entry,
           );
         });
 
@@ -2608,6 +2914,7 @@ export class MCPClient extends EventEmitter {
           if (!entry._stdioFrameError) {
             entry.state = ServerState.DISCONNECTED;
           }
+          this._failLifecycle(entry, { code: "CC_MCP_STDIO_EXIT" });
           failPending(
             `MCP server "${name}" process exited (code ${code}) before responding`,
           );
@@ -2622,6 +2929,7 @@ export class MCPClient extends EventEmitter {
               if (cleanup?.verifiable && !cleanup.confirmed) {
                 entry.state = ServerState.ERROR;
                 const cleanupError = mcpStdioCleanupError(name, cleanup);
+                this._failLifecycle(entry, cleanupError);
                 this.emit("server-error", {
                   name,
                   error: cleanupError.message,
@@ -2638,6 +2946,7 @@ export class MCPClient extends EventEmitter {
 
         proc.on("error", (err) => {
           entry.state = ServerState.ERROR;
+          this._failLifecycle(entry, err);
           failPending(`MCP server "${name}" process error: ${err.message}`);
           this._cancelServerElicitations(name);
           this.emit("server-error", { name, error: err.message });
@@ -2652,6 +2961,7 @@ export class MCPClient extends EventEmitter {
         if (proc.stdin && typeof proc.stdin.on === "function") {
           proc.stdin.on("error", (err) => {
             entry.state = ServerState.ERROR;
+            this._failLifecycle(entry, err);
             failPending(`MCP server "${name}" stdin error: ${err.message}`);
             this._cancelServerElicitations(name);
             this.emit("server-error", { name, error: err.message });
@@ -2664,6 +2974,9 @@ export class MCPClient extends EventEmitter {
       }
 
       // Initialize MCP protocol (retried on transient network errors).
+      this._transitionLifecycle(entry, MCP_LIFECYCLE_PHASES.INITIALIZING, {
+        tlsIdentityDigest: entry._tlsIdentityDigest,
+      });
       const initResult = await this._requestWithRetry(name, "initialize", {
         protocolVersion: this._protocolVersion,
         capabilities: {
@@ -2680,9 +2993,12 @@ export class MCPClient extends EventEmitter {
         clientInfo: { name: "chainlesschain-cli", version: "0.37.9" },
       });
 
-      entry.protocolVersion = String(
-        initResult?.protocolVersion || this._protocolVersion,
+      entry.protocolVersion = assertSupportedMcpProtocolVersion(
+        initResult?.protocolVersion,
       );
+      this._transitionLifecycle(entry, MCP_LIFECYCLE_PHASES.DISCOVERING, {
+        tlsIdentityDigest: entry._tlsIdentityDigest,
+      });
       // Send initialized notification
       this._sendNotification(name, "notifications/initialized", {});
 
@@ -2697,62 +3013,150 @@ export class MCPClient extends EventEmitter {
           ? initResult.instructions
           : null;
 
-      // Fetch available tools. Per MCP a server advertises a `tools` capability
-      // in its initialize response; if it does and tools/list then fails, that
-      // is a genuine fetch failure we must surface (Claude-Code 2.1.181 — show
-      // "Connected · tools fetch failed" rather than a misleading "Tools: 0").
-      // A server that did not advertise tools simply has none, so a failure
-      // there is expected and stays quiet.
-      entry.tools = [];
-      entry.toolsError = null;
-      const advertisesTools =
-        entry.capabilities && entry.capabilities.tools !== undefined;
-      try {
-        const toolsResult = await this._requestWithRetry(
+      const cachePolicy = discoveryCachePolicy(entry.config);
+      const cacheKey = discoveryCacheKey(name, entry);
+      const cached = cachePolicy.enabled
+        ? this._discoveryCache.get(cacheKey) || null
+        : null;
+      const now = Date.now();
+      const capabilitiesSignature = discoveryCapabilitiesSignature(
+        entry.capabilities,
+      );
+      const cacheCompatible =
+        cached?.capabilitiesSignature === capabilitiesSignature;
+      const cacheAgeMs = cacheCompatible
+        ? Math.max(0, now - cached.savedAt)
+        : 0;
+      entry._discoveryCacheKey = cachePolicy.enabled ? cacheKey : null;
+
+      if (cacheCompatible && cacheAgeMs <= cachePolicy.ttlMs) {
+        this._replaceToolInventory(name, entry, cached.tools);
+        applyDiscoveryCache(entry, cached);
+        entry.discoveryCache = { state: "fresh", ageMs: cacheAgeMs };
+        this.emit("server-discovery-cache", {
           name,
-          "tools/list",
-          {},
-        );
-        this._replaceToolInventory(name, entry, toolsResult?.tools || []);
-      } catch (err) {
-        if (advertisesTools) {
-          entry.toolsError = err?.message || String(err);
+          state: "fresh",
+          ageMs: cacheAgeMs,
+        });
+      } else {
+        // Fetch available tools. Per MCP a server advertises a `tools`
+        // capability in its initialize response; if it does and tools/list
+        // fails, that is a genuine fetch failure we must surface. A server that
+        // did not advertise tools simply has none, so a failure stays quiet.
+        entry.tools = [];
+        entry.toolsError = null;
+        const advertisesTools =
+          entry.capabilities && entry.capabilities.tools !== undefined;
+        let toolsDiscoveryFailed = false;
+        try {
+          const toolsResult = await this._requestWithRetry(
+            name,
+            "tools/list",
+            {},
+          );
+          this._replaceToolInventory(name, entry, toolsResult?.tools || []);
+        } catch (err) {
+          if (isMcpFatalDiscoveryError(err)) throw err;
+          if (advertisesTools) {
+            toolsDiscoveryFailed = true;
+            entry.toolsError = err?.message || String(err);
+          }
+          // else: server did not advertise tools — legitimately none.
         }
-        // else: server did not advertise tools — legitimately none.
-      }
 
-      // Fetch available resources
-      try {
-        const resourcesResult = await this._sendRequest(
-          name,
-          "resources/list",
-          {},
-        );
-        entry.resources = resourcesResult?.resources || [];
-      } catch {
-        // Server may not support resources
-      }
+        // Fetch available resources
+        try {
+          const resourcesResult = await this._sendRequest(
+            name,
+            "resources/list",
+            {},
+          );
+          entry.resources = resourcesResult?.resources || [];
+        } catch (error) {
+          if (isMcpFatalDiscoveryError(error)) throw error;
+          // Server may not support resources
+        }
 
-      // Resource templates are optional even when resources are supported.
-      try {
-        const templatesResult = await this._sendRequest(
-          name,
-          "resources/templates/list",
-          {},
-        );
-        entry.resourceTemplates = templatesResult?.resourceTemplates || [];
-      } catch {
-        // Server may not support resource templates.
+        // Resource templates are optional even when resources are supported.
+        try {
+          const templatesResult = await this._sendRequest(
+            name,
+            "resources/templates/list",
+            {},
+          );
+          entry.resourceTemplates = templatesResult?.resourceTemplates || [];
+        } catch (error) {
+          if (isMcpFatalDiscoveryError(error)) throw error;
+          // Server may not support resource templates.
+        }
+
+        // Fetch available prompts (server-provided slash commands)
+        try {
+          const promptsResult = await this._sendRequest(
+            name,
+            "prompts/list",
+            {},
+          );
+          entry.prompts = promptsResult?.prompts || [];
+        } catch (error) {
+          if (isMcpFatalDiscoveryError(error)) throw error;
+          // Server may not support prompts
+        }
+
+        const staleUsable =
+          cacheCompatible &&
+          cacheAgeMs <= cachePolicy.maxStaleMs &&
+          cached.strikes < cachePolicy.maxStrikes;
+        if (toolsDiscoveryFailed && staleUsable) {
+          cached.strikes += 1;
+          cached.lastFailureAt = now;
+          this._replaceToolInventory(name, entry, cached.tools);
+          applyDiscoveryCache(entry, cached);
+          entry.discoveryCache = {
+            state: "stale",
+            ageMs: cacheAgeMs,
+            strikes: cached.strikes,
+          };
+          this.emit("server-discovery-cache", {
+            name,
+            state: "stale",
+            ageMs: cacheAgeMs,
+            strikes: cached.strikes,
+          });
+        } else if (cachePolicy.enabled && !toolsDiscoveryFailed) {
+          this._discoveryCache.set(cacheKey, {
+            savedAt: now,
+            strikes: 0,
+            capabilitiesSignature,
+            tools: cloneDiscoveryList(entry.tools),
+            resources: cloneDiscoveryList(entry.resources),
+            resourceTemplates: cloneDiscoveryList(entry.resourceTemplates),
+            prompts: cloneDiscoveryList(entry.prompts),
+          });
+          entry.discoveryCache = { state: "miss", ageMs: null };
+        }
       }
 
-      // Fetch available prompts (server-provided slash commands)
-      try {
-        const promptsResult = await this._sendRequest(name, "prompts/list", {});
-        entry.prompts = promptsResult?.prompts || [];
-      } catch {
-        // Server may not support prompts
+      // Desired v2 subscriptions belong to the logical authority, not a
+      // transport object. Restore them after initialize + capability discovery
+      // so both hot reconnect and process restart preserve live updates.
+      for (const uri of this._lifecycleAuthority.desiredSubscriptions(
+        lifecycleAttempt,
+      )) {
+        await this._sendRequest(name, "resources/subscribe", { uri });
+        entry.resourceSubscriptions.add(uri);
+        let desired = this._resourceSubscriptions.get(name);
+        if (!desired) {
+          desired = new Set();
+          this._resourceSubscriptions.set(name, desired);
+        }
+        desired.add(uri);
       }
 
+      this._transitionLifecycle(entry, MCP_LIFECYCLE_PHASES.READY, {
+        tlsIdentityDigest: entry._tlsIdentityDigest,
+      });
+
       this.emit("server-connected", {
         name,
         tools: entry.tools.length,
@@ -2777,6 +3181,16 @@ export class MCPClient extends EventEmitter {
       };
     } catch (err) {
       entry.state = ServerState.ERROR;
+      try {
+        this._transitionLifecycle(
+          entry,
+          MCP_LIFECYCLE_PHASES.FAILED,
+          { reasonCode: err?.code || "CC_MCP_CONNECTION_FAILED" },
+          { tolerateFence: true },
+        );
+      } catch {
+        // The original transport/protocol failure remains authoritative.
+      }
       this._cancelServerElicitations(name);
       // The initialize notification is fire-and-forget. If later capability
       // discovery fails, connect() deletes this entry without going through
@@ -2831,17 +3245,26 @@ export class MCPClient extends EventEmitter {
           // teardown is best-effort
         }
       }
+      try {
+        await _deps.closeMcpTlsDispatcher(entry._httpDispatcher);
+      } catch {
+        // Preserve the connection failure; dispatcher cleanup is best-effort.
+      }
+      entry._httpDispatcher = null;
       this._releaseToolInventory(entry);
       this.servers.delete(name);
       if (
-        !_authRetryUsed &&
+        !authRetryUsed &&
         sourceConfig.headersHelper &&
         isMcpAuthenticationError(err)
       ) {
         // A helper is intentionally uncached. One authentication rejection may
         // mean its short-lived token expired between generation and initialize;
         // execute it once more and retry the connection exactly once.
-        return this.connect(name, sourceConfig, true);
+        return this.connect(name, sourceConfig, {
+          authRetryUsed: true,
+          reconnect: true,
+        });
       }
       throw err;
     }
@@ -2850,18 +3273,78 @@ export class MCPClient extends EventEmitter {
   /**
    * Disconnect from an MCP server.
    */
-  disconnect(name) {
+  disconnect(name, options = {}) {
+    if (options.preserveResourceSubscriptions !== true) {
+      this._resourceSubscriptions.delete(name);
+    }
     const entry = this.servers.get(name);
+    const lifecycleAttempt =
+      entry?._lifecycleAttempt || this._lifecycleAttempts.get(name) || null;
     if (!entry) {
       this._cancelServerElicitations(name);
+      if (options.preserveResourceSubscriptions !== true && lifecycleAttempt) {
+        try {
+          this._lifecycleAuthority.clearSubscriptions(lifecycleAttempt);
+          const snapshot = this._lifecycleAuthority.snapshot({
+            name,
+            sessionId: this._lifecycleSessionId,
+          });
+          if (
+            snapshot &&
+            snapshot.phase !== MCP_LIFECYCLE_PHASES.IDLE &&
+            snapshot.phase !== MCP_LIFECYCLE_PHASES.DISABLED
+          ) {
+            this._lifecycleAuthority.transition(
+              lifecycleAttempt,
+              MCP_LIFECYCLE_PHASES.DISCONNECTING,
+            );
+            this._lifecycleAuthority.transition(
+              lifecycleAttempt,
+              MCP_LIFECYCLE_PHASES.IDLE,
+            );
+          }
+        } catch (error) {
+          if (error?.code !== MCP_LIFECYCLE_ERROR_CODES.FENCED) {
+            return Promise.reject(error);
+          }
+        } finally {
+          if (this._lifecycleAttempts.get(name) === lifecycleAttempt) {
+            this._lifecycleAttempts.delete(name);
+          }
+        }
+      }
       return Promise.resolve(false);
     }
     if (entry._disconnectPromise) return entry._disconnectPromise;
 
+    let subscriptionClearError = null;
+    if (options.preserveResourceSubscriptions !== true && lifecycleAttempt) {
+      try {
+        this._lifecycleAuthority.clearSubscriptions(lifecycleAttempt);
+      } catch (error) {
+        if (error?.code !== MCP_LIFECYCLE_ERROR_CODES.FENCED) {
+          subscriptionClearError = error;
+        }
+      }
+    }
+
     // Make disconnect visible before any teardown awaits. In particular, an
     // HTTP session DELETE may wait for response headers; no new tool/resource
     // request may enter the transport during that window or trigger a hot
     // reconnect that resurrects a server the caller is intentionally closing.
+    if (options.preserveLifecycleAuthority !== true) {
+      try {
+        this._transitionLifecycle(
+          entry,
+          MCP_LIFECYCLE_PHASES.DISCONNECTING,
+          {},
+          { tolerateFence: true },
+        );
+      } catch {
+        // Local transport teardown must still run if durable state is
+        // temporarily unavailable. No further request is admitted below.
+      }
+    }
     entry.state = ServerState.DISCONNECTED;
     entry._httpDiscardStopping = true;
     this._cancelServerElicitations(name);
@@ -2904,14 +3387,40 @@ export class MCPClient extends EventEmitter {
             // ignore — disconnect is best-effort
           }
         }
-        return true;
       } finally {
+        try {
+          await _deps.closeMcpTlsDispatcher(entry._httpDispatcher);
+        } catch {
+          // Transport teardown remains best-effort.
+        }
+        entry._httpDispatcher = null;
         entry.state = ServerState.DISCONNECTED;
+        if (options.preserveLifecycleAuthority !== true) {
+          try {
+            this._transitionLifecycle(
+              entry,
+              MCP_LIFECYCLE_PHASES.IDLE,
+              {},
+              { tolerateFence: true },
+            );
+          } catch {
+            // The transport is already closed; retain the durable failure for
+            // the next generation's restart recovery.
+          }
+        }
         this._releaseToolInventory(entry);
         // A future connection may reuse the same name. Never let a delayed
         // teardown delete that replacement entry.
         if (this.servers.get(name) === entry) this.servers.delete(name);
+        if (
+          options.preserveResourceSubscriptions !== true &&
+          this._lifecycleAttempts.get(name) === lifecycleAttempt
+        ) {
+          this._lifecycleAttempts.delete(name);
+        }
       }
+      if (subscriptionClearError) throw subscriptionClearError;
+      return true;
     });
     entry._disconnectPromise = disconnecting;
 
@@ -2927,9 +3436,19 @@ export class MCPClient extends EventEmitter {
    * Disconnect from all servers.
    */
   async disconnectAll() {
-    const names = [...this.servers.keys()];
-    for (const name of names) {
-      await this.disconnect(name);
+    const names = new Set([
+      ...this.servers.keys(),
+      ...this._lifecycleAttempts.keys(),
+    ]);
+    try {
+      for (const name of names) {
+        await this.disconnect(name);
+      }
+    } finally {
+      // A failed reconnect may have already removed its transport entry while
+      // retaining desired subscriptions for another retry. disconnectAll()
+      // is the explicit terminal teardown and must clear those tombstones too.
+      this._resourceSubscriptions.clear();
     }
   }
 
@@ -3146,15 +3665,58 @@ export class MCPClient extends EventEmitter {
       throw new Error(`Server "${serverName}" is not connected`);
     }
 
-    const result = await this._sendRequest(
-      serverName,
-      "tools/call",
-      {
-        name: toolName,
-        arguments: args,
-      },
-      options,
-    );
+    const timeoutMs = mcpToolIdleTimeoutMs(entry.config, options);
+    const progressToken = `cc:${randomUUID()}`;
+    const controller = new AbortController();
+    let idleError = null;
+    let idleTimer = null;
+    let removeCallerAbort = null;
+    const resetIdleTimer = () => {
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        idleError = mcpToolIdleTimeoutError(serverName, toolName, timeoutMs);
+        controller.abort();
+      }, timeoutMs);
+      idleTimer.unref?.();
+    };
+    const callerSignal = options?.signal || null;
+    if (callerSignal?.addEventListener) {
+      const abortFromCaller = () => controller.abort();
+      callerSignal.addEventListener("abort", abortFromCaller, { once: true });
+      removeCallerAbort = () =>
+        callerSignal.removeEventListener?.("abort", abortFromCaller);
+      if (callerSignal.aborted) controller.abort();
+    }
+    this._toolProgress.set(progressToken, resetIdleTimer);
+    resetIdleTimer();
+
+    let result;
+    try {
+      result = await this._sendRequest(
+        serverName,
+        "tools/call",
+        {
+          name: toolName,
+          arguments: args,
+          _meta: { progressToken },
+        },
+        { ...options, signal: controller.signal },
+      );
+    } catch (error) {
+      // The inner transport supplies cancellation and JSON-RPC
+      // notifications/cancelled. Preserve the idle classification at the host
+      // boundary instead of leaking its generic AbortError/cancelled detail.
+      if (idleError) throw idleError;
+      throw error;
+    } finally {
+      if (idleTimer) clearTimeout(idleTimer);
+      try {
+        removeCallerAbort?.();
+      } catch {
+        // Best-effort cleanup for non-native AbortSignal adapters.
+      }
+      this._toolProgress.delete(progressToken);
+    }
 
     return admitMcpToolResult(serverName, result, entry.config).result;
   }
@@ -3173,11 +3735,32 @@ export class MCPClient extends EventEmitter {
       try {
         const currentEntry = this.servers.get(name) || null;
         const currentConfig = currentEntry?.config || null;
+        // Resource subscriptions belong to the logical client/server
+        // relationship, not to one transport connection. Snapshot them before
+        // disconnect() removes the old entry so a hot reconnect cannot
+        // silently stop delivering resource update notifications.
+        const resourceSubscriptions = new Set([
+          ...(this._resourceSubscriptions.get(name) || []),
+          ...(currentEntry?.resourceSubscriptions || []),
+        ]);
+        if (resourceSubscriptions.size > 0) {
+          this._resourceSubscriptions.set(name, new Set(resourceSubscriptions));
+        }
         const resolver = this._reconnectors.get(name);
         const fresh = resolver ? await resolver() : currentConfig;
         if (!fresh) return false;
+        const lifecycleAttempt = this._lifecycleAuthority.beginConnection({
+          name,
+          sessionId: this._lifecycleSessionId,
+          config: fresh,
+          reconnect: true,
+          explicitEnable: true,
+        });
         try {
-          await this.disconnect(name);
+          await this.disconnect(name, {
+            preserveResourceSubscriptions: true,
+            preserveLifecycleAuthority: true,
+          });
         } catch {
           // entry may already be gone — connect() below is what matters
         }
@@ -3190,11 +3773,32 @@ export class MCPClient extends EventEmitter {
               { serverName: name, config: reconnectConfig },
             );
         }
-        await this.connect(
-          name,
-          reconnectConfig,
-          options.connectAuthRetryUsed === true,
-        );
+        await this.connect(name, reconnectConfig, {
+          authRetryUsed: options.connectAuthRetryUsed === true,
+          lifecycleAttempt,
+          reconnect: true,
+        });
+        try {
+          for (const uri of resourceSubscriptions) {
+            if (!this.servers.get(name)?.resourceSubscriptions?.has(uri)) {
+              await this.subscribeResource(name, uri);
+            }
+          }
+        } catch {
+          // A partially restored connection is unsafe: callers would believe
+          // the reconnect recovered their live subscriptions while some were
+          // already lost. Tear it down and let the original operation surface
+          // its connection error.
+          try {
+            await this.disconnect(name, {
+              preserveResourceSubscriptions: true,
+            });
+          } catch {
+            // The outer reconnect result remains fail-closed even if cleanup
+            // itself reports an error.
+          }
+          return false;
+        }
         this.emit("server-reconnected", { name, url: fresh.url || null });
         return true;
       } catch {
@@ -3269,9 +3873,30 @@ export class MCPClient extends EventEmitter {
   async subscribeResource(serverName, uri) {
     const entry = this.servers.get(serverName);
     if (!entry) throw new Error(`Server "${serverName}" not found`);
-    await this._sendRequest(serverName, "resources/subscribe", { uri });
+    if (typeof uri !== "string" || !uri.trim()) {
+      throw new TypeError(
+        "MCP resource subscription URI must be a non-empty string",
+      );
+    }
+    const normalizedUri = uri;
+    await this._sendRequest(serverName, "resources/subscribe", {
+      uri: normalizedUri,
+    });
     entry.resourceSubscriptions ||= new Set();
-    entry.resourceSubscriptions.add(String(uri));
+    entry.resourceSubscriptions.add(normalizedUri);
+    let desired = this._resourceSubscriptions.get(serverName);
+    if (!desired) {
+      desired = new Set();
+      this._resourceSubscriptions.set(serverName, desired);
+    }
+    desired.add(normalizedUri);
+    if (entry._lifecycleAttempt) {
+      this._lifecycleAuthority.setSubscription(
+        entry._lifecycleAttempt,
+        normalizedUri,
+        true,
+      );
+    }
     return true;
   }
 
@@ -3279,8 +3904,26 @@ export class MCPClient extends EventEmitter {
   async unsubscribeResource(serverName, uri) {
     const entry = this.servers.get(serverName);
     if (!entry) throw new Error(`Server "${serverName}" not found`);
-    await this._sendRequest(serverName, "resources/unsubscribe", { uri });
-    entry.resourceSubscriptions?.delete(String(uri));
+    if (typeof uri !== "string" || !uri.trim()) {
+      throw new TypeError(
+        "MCP resource subscription URI must be a non-empty string",
+      );
+    }
+    const normalizedUri = uri;
+    await this._sendRequest(serverName, "resources/unsubscribe", {
+      uri: normalizedUri,
+    });
+    entry.resourceSubscriptions?.delete(normalizedUri);
+    const desired = this._resourceSubscriptions.get(serverName);
+    desired?.delete(normalizedUri);
+    if (desired?.size === 0) this._resourceSubscriptions.delete(serverName);
+    if (entry._lifecycleAttempt) {
+      this._lifecycleAuthority.setSubscription(
+        entry._lifecycleAttempt,
+        normalizedUri,
+        false,
+      );
+    }
     return true;
   }
 
@@ -3413,6 +4056,7 @@ export class MCPClient extends EventEmitter {
         method,
         params,
       });
+      this._registerLifecycleRpc(entry, id, method);
 
       let timeout = null;
       let removeCallerAbort = null;
@@ -3431,6 +4075,20 @@ export class MCPClient extends EventEmitter {
         if (settled) return false;
         settled = true;
         cleanup();
+        try {
+          const admitted = this._settleLifecycleRpc(
+            entry,
+            id,
+            settler === resolve ? "completed" : "failed-closed",
+          );
+          if (!admitted && settler === resolve) {
+            reject(this._staleLifecycleCallbackError());
+            return true;
+          }
+        } catch (authorityError) {
+          reject(authorityError);
+          return true;
+        }
         settler(value);
         return true;
       };
@@ -3534,6 +4192,7 @@ export class MCPClient extends EventEmitter {
     return new Promise((resolve, reject) => {
       const id = this._nextId++;
       const message = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+      this._registerLifecycleRpc(entry, id, method);
       const longRunning = Boolean(entry.config?.longRunning);
       const timeoutMs = Number.isFinite(entry.config?.requestTimeoutMs)
         ? entry.config.requestTimeoutMs
@@ -3555,6 +4214,20 @@ export class MCPClient extends EventEmitter {
         if (settled) return false;
         settled = true;
         cleanup();
+        try {
+          const admitted = this._settleLifecycleRpc(
+            entry,
+            id,
+            settler === resolve ? "completed" : "failed-closed",
+          );
+          if (!admitted && settler === resolve) {
+            reject(this._staleLifecycleCallbackError());
+            return true;
+          }
+        } catch (authorityError) {
+          reject(authorityError);
+          return true;
+        }
         settler(value);
         return true;
       };
@@ -3752,6 +4425,9 @@ export class MCPClient extends EventEmitter {
                 ...(stream.controller
                   ? { signal: stream.controller.signal }
                   : {}),
+                ...(entry._httpDispatcher
+                  ? { dispatcher: entry._httpDispatcher }
+                  : {}),
               }),
               stream.controller?.signal,
             );
@@ -3796,7 +4472,8 @@ export class MCPClient extends EventEmitter {
                 if (error) throw error;
               },
               parseJson: (text) => parseMcpJson(text, serverName, entry),
-              onMessage: (message) => this._handleMessage(serverName, message),
+              onMessage: (message) =>
+                this._handleMessage(serverName, message, entry),
             });
           } catch (error) {
             if (stream.stopped) return;
@@ -3879,6 +4556,14 @@ export class MCPClient extends EventEmitter {
 
     const id = this._nextId++;
     const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    this._registerLifecycleRpc(entry, id, method);
+    let lifecycleSettled = false;
+    const settleLifecycle = (outcome) => {
+      if (lifecycleSettled) return true;
+      const admitted = this._settleLifecycleRpc(entry, id, outcome);
+      lifecycleSettled = true;
+      return admitted;
+    };
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json, text/event-stream",
@@ -3997,6 +4682,9 @@ export class MCPClient extends EventEmitter {
             headers,
             body,
             ...(controller ? { signal: controller.signal } : {}),
+            ...(entry._httpDispatcher
+              ? { dispatcher: entry._httpDispatcher }
+              : {}),
           });
         },
       );
@@ -4080,7 +4768,7 @@ export class MCPClient extends EventEmitter {
           response,
           id,
           cap,
-          (message) => this._handleMessage(serverName, message),
+          (message) => this._handleMessage(serverName, message, entry),
           controller?.signal,
           (text) => parseMcpJson(text, serverName, entry),
         );
@@ -4113,9 +4801,18 @@ export class MCPClient extends EventEmitter {
         throw mcpRpcError(wire.error);
       }
       throwIfAborted();
+      if (!settleLifecycle("completed")) {
+        throw this._staleLifecycleCallbackError();
+      }
       return wire.result;
     } catch (err) {
-      throwIfAborted();
+      try {
+        throwIfAborted();
+      } catch (abortError) {
+        settleLifecycle("failed-closed");
+        throw abortError;
+      }
+      settleLifecycle("failed-closed");
       throw err;
     } finally {
       if (timer) clearTimeout(timer);
@@ -4156,8 +4853,9 @@ export class MCPClient extends EventEmitter {
     });
   }
 
-  _handleData(serverName, data) {
-    const entry = this.servers.get(serverName);
+  _handleData(serverName, data, sourceEntry = null) {
+    const entry = sourceEntry || this.servers.get(serverName);
+    if (sourceEntry && this.servers.get(serverName) !== sourceEntry) return;
     if (!entry || entry._stdioFrameError) return;
 
     const cap = stdioFrameByteLimit(entry.config?.maxBufferChars);
@@ -4216,7 +4914,7 @@ export class MCPClient extends EventEmitter {
         }
         continue;
       }
-      this._handleMessage(serverName, msg);
+      this._handleMessage(serverName, msg, entry);
     }
   }
 
@@ -4312,6 +5010,7 @@ export class MCPClient extends EventEmitter {
     entry._buffer = "";
     entry._bufferBytes = 0;
     entry.state = ServerState.ERROR;
+    this._failLifecycle(entry, error);
     if (entry._pending instanceof Map) {
       for (const pending of entry._pending.values()) {
         if (pending.timeout) clearTimeout(pending.timeout);
@@ -4345,12 +5044,21 @@ export class MCPClient extends EventEmitter {
     return error;
   }
 
-  _handleMessage(serverName, msg) {
-    const entry = this.servers.get(serverName);
+  _handleMessage(serverName, msg, sourceEntry = null) {
+    const currentEntry = this.servers.get(serverName);
+    const entry = sourceEntry || currentEntry;
     if (!entry) return;
+    if (sourceEntry && currentEntry !== sourceEntry) {
+      const wire = snapshotRpcMessage(msg);
+      if (wire?.hasId && !wire.hasMethod) {
+        this._rejectUnexpectedLifecycleRpc(sourceEntry, wire.id, "stale");
+      }
+      return;
+    }
 
     const failMessage = (error) => {
       entry.state = ServerState.ERROR;
+      this._failLifecycle(entry, error);
       if (entry._pending instanceof Map) {
         for (const pending of entry._pending.values()) {
           clearTimeout(pending.timeout);
@@ -4419,6 +5127,13 @@ export class MCPClient extends EventEmitter {
     // one of ours). Previously these fell into the notification branch and
     // never got a response, so a server calling e.g. roots/list hung until its
     // own timeout. Answer the ones our advertised capabilities invite.
+    // A response without a live pending request is never delivered. The
+    // durable authority records whether it was duplicate or uncorrelated.
+    if (wire.hasId && !wire.hasMethod) {
+      this._rejectUnexpectedLifecycleRpc(entry, wire.id, "unmatched");
+      return;
+    }
+
     if (wire.hasId && typeof wire.method === "string" && wire.method) {
       if (
         wire.hasParams &&
@@ -4451,10 +5166,35 @@ export class MCPClient extends EventEmitter {
       // tool-search's prompt-cache stability depends on an append-only,
       // stable-prefix tool list.)
       if (wire.method === "notifications/tools/list_changed") {
+        if (entry._discoveryCacheKey) {
+          this._discoveryCache.delete(entry._discoveryCacheKey);
+        }
         this._refreshServerList(serverName, "tools");
       } else if (wire.method === "notifications/resources/list_changed") {
+        if (entry._discoveryCacheKey) {
+          this._discoveryCache.delete(entry._discoveryCacheKey);
+        }
         this._refreshServerList(serverName, "resources");
         this._refreshServerList(serverName, "resourceTemplates");
+      } else if (wire.method === "notifications/progress") {
+        const progressToken = safeRpcProperty(wire.params, "progressToken");
+        const resetIdle =
+          typeof progressToken === "string"
+            ? this._toolProgress.get(progressToken)
+            : null;
+        if (resetIdle) resetIdle();
+        // Project only numeric progress. Server-controlled status text belongs
+        // to the tool result, not host diagnostics/events.
+        this.emit("tool-progress", {
+          server: serverName,
+          ...(typeof progressToken === "string" ? { progressToken } : {}),
+          ...(Number.isFinite(safeRpcProperty(wire.params, "progress"))
+            ? { progress: safeRpcProperty(wire.params, "progress") }
+            : {}),
+          ...(Number.isFinite(safeRpcProperty(wire.params, "total"))
+            ? { total: safeRpcProperty(wire.params, "total") }
+            : {}),
+        });
       } else if (wire.method === "notifications/resources/updated") {
         this.emit("resource-updated", {
           server: serverName,
@@ -4729,6 +5469,7 @@ async function _fetchAndDiscardHttpResponse(entry, options) {
     const response = await _deps.fetch(entry.httpUrl, {
       ...options,
       ...(controller ? { signal: controller.signal } : {}),
+      ...(entry._httpDispatcher ? { dispatcher: entry._httpDispatcher } : {}),
     });
     _cancelHttpResponseBody(response);
     if (timedOut) {