chainlesschain 0.165.6 → 0.165.9

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";
@@ -46,10 +47,16 @@ import {
 } 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.
@@ -237,6 +244,14 @@ 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",
@@ -246,6 +261,97 @@ export const SUPPORTED_MCP_PROTOCOL_VERSIONS = Object.freeze([
 ]);
 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(
@@ -911,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
@@ -1313,12 +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
@@ -1878,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;
+    }
   }
 
   /**
@@ -2020,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;
@@ -2112,22 +2337,46 @@ export class MCPClient extends EventEmitter {
         };
       }
     }
+    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;
-    if (sourceConfig.tls != null) {
-      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 },
-        );
+    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,
+        });
       }
-      tlsMaterial = _deps.loadMcpTlsMaterial(sourceConfig.tls);
+      connectionHeaders = await this._connectionHeaders(
+        name,
+        sourceConfig,
+        transportKind,
+      );
+    } catch (error) {
+      this._failLifecycle({ _lifecycleAttempt: lifecycleAttempt }, error);
+      throw error;
     }
-    const connectionHeaders = await this._connectionHeaders(
-      name,
-      sourceConfig,
-      transportKind,
-    );
     config = { ...runtimeConfig, headers: connectionHeaders };
     const entry = {
       // Keep the source config (static headers + helper command) so every
@@ -2154,6 +2403,7 @@ export class MCPClient extends EventEmitter {
       _toolMetadataBytes: 0,
       _stdioExecutionApproval: stdioExecutionApproval,
       _stdioExecutableIdentity: stdioExecutableIdentity,
+      _lifecycleAttempt: lifecycleAttempt,
       tools: [],
       resources: [],
       resourceTemplates: [],
@@ -2265,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", {
@@ -2289,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", {
@@ -2366,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", {
@@ -2400,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);
@@ -2412,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", {
@@ -2433,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", {
@@ -2460,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", {
@@ -2484,6 +2740,7 @@ export class MCPClient extends EventEmitter {
               outcomeUnknown: dispatched,
             },
           );
+          this._failLifecycle(entry, error);
           rejectPending(error);
           this._cancelServerElicitations(name);
           this.emit("server-disconnected", {
@@ -2511,6 +2768,7 @@ export class MCPClient extends EventEmitter {
               outcomeUnknown: dispatched,
             },
           );
+          this._failLifecycle(entry, error);
           rejectPending(error);
           this._cancelServerElicitations(name);
           this.emit("server-error", {
@@ -2626,6 +2884,7 @@ export class MCPClient extends EventEmitter {
             typeof data === "string"
               ? data
               : entry._decoder.decode(data, { stream: true }),
+            entry,
           );
         });
 
@@ -2655,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`,
           );
@@ -2669,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,
@@ -2685,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 });
@@ -2699,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 });
@@ -2711,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: {
@@ -2730,6 +2996,9 @@ export class MCPClient extends EventEmitter {
       entry.protocolVersion = assertSupportedMcpProtocolVersion(
         initResult?.protocolVersion,
       );
+      this._transitionLifecycle(entry, MCP_LIFECYCLE_PHASES.DISCOVERING, {
+        tlsIdentityDigest: entry._tlsIdentityDigest,
+      });
       // Send initialized notification
       this._sendNotification(name, "notifications/initialized", {});
 
@@ -2744,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,
@@ -2824,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
@@ -2887,14 +3254,17 @@ export class MCPClient extends EventEmitter {
       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;
     }
@@ -2908,16 +3278,73 @@ export class MCPClient extends EventEmitter {
       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);
@@ -2960,7 +3387,6 @@ export class MCPClient extends EventEmitter {
             // ignore — disconnect is best-effort
           }
         }
-        return true;
       } finally {
         try {
           await _deps.closeMcpTlsDispatcher(entry._httpDispatcher);
@@ -2969,11 +3395,32 @@ export class MCPClient extends EventEmitter {
         }
         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;
 
@@ -2989,7 +3436,10 @@ export class MCPClient extends EventEmitter {
    * Disconnect from all servers.
    */
   async disconnectAll() {
-    const names = [...this.servers.keys()];
+    const names = new Set([
+      ...this.servers.keys(),
+      ...this._lifecycleAttempts.keys(),
+    ]);
     try {
       for (const name of names) {
         await this.disconnect(name);
@@ -3215,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;
   }
@@ -3256,8 +3749,18 @@ export class MCPClient extends EventEmitter {
         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, { preserveResourceSubscriptions: true });
+          await this.disconnect(name, {
+            preserveResourceSubscriptions: true,
+            preserveLifecycleAuthority: true,
+          });
         } catch {
           // entry may already be gone — connect() below is what matters
         }
@@ -3270,14 +3773,16 @@ 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) {
-            await this.subscribeResource(name, uri);
+            if (!this.servers.get(name)?.resourceSubscriptions?.has(uri)) {
+              await this.subscribeResource(name, uri);
+            }
           }
         } catch {
           // A partially restored connection is unsafe: callers would believe
@@ -3385,6 +3890,13 @@ export class MCPClient extends EventEmitter {
       this._resourceSubscriptions.set(serverName, desired);
     }
     desired.add(normalizedUri);
+    if (entry._lifecycleAttempt) {
+      this._lifecycleAuthority.setSubscription(
+        entry._lifecycleAttempt,
+        normalizedUri,
+        true,
+      );
+    }
     return true;
   }
 
@@ -3405,6 +3917,13 @@ export class MCPClient extends EventEmitter {
     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;
   }
 
@@ -3537,6 +4056,7 @@ export class MCPClient extends EventEmitter {
         method,
         params,
       });
+      this._registerLifecycleRpc(entry, id, method);
 
       let timeout = null;
       let removeCallerAbort = null;
@@ -3555,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;
       };
@@ -3658,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
@@ -3679,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;
       };
@@ -3923,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;
@@ -4006,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",
@@ -4210,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),
         );
@@ -4243,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);
@@ -4286,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);
@@ -4346,7 +4914,7 @@ export class MCPClient extends EventEmitter {
         }
         continue;
       }
-      this._handleMessage(serverName, msg);
+      this._handleMessage(serverName, msg, entry);
     }
   }
 
@@ -4442,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);
@@ -4475,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);
@@ -4549,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 &&
@@ -4581,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,