comisai 1.0.42 → 1.0.45

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/mcp-client-discover.js

@@ -19,8 +19,22 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { systemEnvSnapshot, systemNowMs } from "@comis/core";
+import { systemNowMs } from "@comis/core";
 import { qualifyToolName } from "./mcp-client-types.js";
+import { createRedirectPolicyFetch } from "./mcp-client-redirect-policy.js";
+import { getPrlimitAvailableCached, getPrlimitWarnEmitted, setPrlimitWarnEmitted, } from "./mcp-client-prlimit-probe.js";
+// Re-export the prlimit probe public + test surface so existing callers
+// (and the co-located mcp-client-discover.test.ts) continue to import
+// from this leaf — the helpers were moved to a sibling leaf to keep this
+// file under the 500-line per-subdirectory cap, not to change the API.
+export { getPrlimitAvailable, refreshPrlimitAvailable, __resetPrlimitWarnForTests, __resetPrlimitProbeForTests, } from "./mcp-client-prlimit-probe.js";
+// The stdio env allowlist + interpreter-control blocklist + `scrubStdioEnv`
+// builder were moved to a sibling leaf to keep this file under the 500-line
+// per-subdirectory cap (the tools/list_changed diff helpers pushed it over).
+// Re-exported here so existing callers and the co-located
+// mcp-client-discover.test.ts keep importing from this leaf — not an API change.
+import { scrubStdioEnv, MCP_STDIO_BUILTIN_ENV_ALLOWLIST } from "./mcp-client-stdio-env.js";
+export { scrubStdioEnv, MCP_STDIO_BUILTIN_ENV_ALLOWLIST };
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -31,38 +45,85 @@ const INSTRUCTIONS_TRUNCATED_SUFFIX = " [truncated]";
 // Transport creation helpers
 // ---------------------------------------------------------------------------
 /**
- * Wrap a stdio command so the child Node process (if any) does NOT inherit
- * the daemon's --permission flags via NODE_OPTIONS.
+ * Wrap a stdio command so:
+ *   1. NODE_OPTIONS strip — child Node process does NOT inherit the daemon's
+ *      `--permission` flags. `env -u NODE_OPTIONS` clears it before Node reads
+ *      it. Non-Node servers (uvx, Python) pass through as no-op. See
+ *      COMIS-E2E-FOLLOWUP-DESIGN.md Issue 2.
+ *   2. Per-server rlimits via `prlimit(1)`. When `rlimits`
+ *      is set AND prlimit is available, prepends `prlimit --as=N --nofile=N
+ *      --cpu=N --`. Partial overrides accepted (`{ cpu: 600 }` → only `--cpu`).
+ *      When `rlimits` is unset → no prlimit wrap. When prlimit is absent
+ *      (macOS dev) → env-only wrap + ONE WARN per daemon process
+ *      (`errorKind: "platform"`).
  *
- * Node 22's permission model propagates by setting NODE_OPTIONS on spawned
- * children, even when the caller passes an override env. Unsetting
- * NODE_OPTIONS via `env -u NODE_OPTIONS <cmd>` is the only mechanism that
- * clears it before the child Node process reads it at startup.
- *
- * Non-Node MCP servers (uvx, Python, etc.) are unaffected by NODE_OPTIONS
- * but still go through the wrapper for uniformity — `env -u` on a missing
- * var is a no-op. Linux-only production target (per CLAUDE.md); macOS and
- * WSL both have `/usr/bin/env` with `-u` support.
- *
- * See COMIS-E2E-FOLLOWUP-DESIGN.md Issue 2 for the empirical rationale.
+ * Composition: `[prlimit --as=N --nofile=N --cpu=N --]  /usr/bin/env -u NODE_OPTIONS  <cmd> <args>`.
+ * Exported for unit-test assertion.
  */
-function wrapStdioCommand(command, args) {
+export function wrapStdioCommand(command, args, rlimits, logger, serverName) {
+    const innerArgs = ["-u", "NODE_OPTIONS", command, ...(args ?? [])];
+    // No rlimits requested: return the existing env-only wrap unchanged.
+    if (!rlimits ||
+        (rlimits.as === undefined &&
+            rlimits.nofile === undefined &&
+            rlimits.cpu === undefined)) {
+        return { command: "/usr/bin/env", args: innerArgs };
+    }
+    // Rlimits requested but prlimit unavailable (macOS dev): WARN once + degrade.
+    // Read the lazily-cached probe result. The very first call to
+    // wrapStdioCommand triggers the probe; subsequent calls hit the cache.
+    // Operators who install util-linux post-hoc can force a re-probe via
+    // refreshPrlimitAvailable().
+    if (!getPrlimitAvailableCached()) {
+        if (!getPrlimitWarnEmitted()) {
+            logger.warn({
+                serverName,
+                hint: "prlimit(1) not on PATH; rlimits not applied (Linux util-linux required). " +
+                    "Production target is Linux; macOS dev runs without rlimit defense-in-depth. " +
+                    "If util-linux was installed AFTER daemon start, call refreshPrlimitAvailable() to re-probe.",
+                errorKind: "platform",
+            }, "MCP rlimits skipped — prlimit unavailable");
+            setPrlimitWarnEmitted();
+        }
+        return { command: "/usr/bin/env", args: innerArgs };
+    }
+    // Build prlimit flag set — emit ONLY the flags for fields explicitly set
+    // (partial-override semantics).
+    const prlimitFlags = [];
+    if (rlimits.as !== undefined)
+        prlimitFlags.push(`--as=${rlimits.as}`);
+    if (rlimits.nofile !== undefined)
+        prlimitFlags.push(`--nofile=${rlimits.nofile}`);
+    if (rlimits.cpu !== undefined)
+        prlimitFlags.push(`--cpu=${rlimits.cpu}`);
     return {
-        command: "/usr/bin/env",
-        args: ["-u", "NODE_OPTIONS", command, ...(args ?? [])],
+        command: "prlimit",
+        args: [...prlimitFlags, "--", "/usr/bin/env", ...innerArgs],
     };
 }
-export function createTransport(config) {
+/** No-op fallback logger for createTransport callers that don't thread one (test fixtures). */
+const NO_OP_LOGGER = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    debug: () => { },
+};
+export function createTransport(config, logger = NO_OP_LOGGER) {
     if (config.transport === "stdio") {
         if (!config.command) {
             throw new Error(`MCP server "${config.name}": stdio transport requires "command"`);
         }
-        const wrapped = wrapStdioCommand(config.command, config.args);
+        const wrapped = wrapStdioCommand(config.command, config.args, config.rlimits, logger, config.name);
         return new StdioClientTransport({
             command: wrapped.command,
             args: wrapped.args,
             stderr: "pipe", // capture stderr for debugging
-            ...(config.env ? { env: { ...systemEnvSnapshot(), ...config.env } } : {}),
+            // Strict allowlist + operator-extension scrub. Replaces the prior
+            // `{ ...systemEnvSnapshot(), ...config.env }` spread, which leaked
+            // every daemon-process credential env var into every spawned MCP child.
+            // The architecture-test dangerous-key negative-control list at
+            // test/architecture/mcp-prespawn-allowlist.test.ts enforces the denylist.
+            env: scrubStdioEnv(config.env, config.safetyAllowedEnvKeys),
             ...(config.cwd ? { cwd: config.cwd } : {}),
         });
     }
@@ -74,6 +135,23 @@ export function createTransport(config) {
             requestInit: config.headers
                 ? { headers: config.headers }
                 : undefined,
+            // An auth:"oauth" server with the OAuth seam wired uses the deduped-refresh
+            // fetch (which itself composes the redirect-policy fetch inside it, so
+            // cross-host header scrub still applies). The bare redirect-policy fetch is
+            // the legacy/non-OAuth fallback.
+            // Cross-host redirect header scrub: strips Authorization / Cookie /
+            // Proxy-Authorization on cross-host redirect (URL.host string mismatch
+            // including port); preserves on same-host (including http to https upgrade);
+            // throws [max_redirects_exceeded] after 20 hops. See
+            // mcp-client-redirect-policy.ts for the full policy.
+            fetch: config.oauthFetch ?? createRedirectPolicyFetch({ maxRedirections: 20 }),
+            // Attach the OAuthClientProvider adapter ONLY for auth:"oauth" servers with
+            // a constructed provider (threaded onto the runtime config by connectServer).
+            // The SDK then drives tokens()/saveTokens() and, on a 401, the auth()
+            // refresh path. requestInit + fetch above are untouched.
+            ...(config.auth === "oauth" && config.oauthProvider
+                ? { authProvider: config.oauthProvider }
+                : {}),
         });
     }
     else if (config.transport === "http") {
@@ -84,11 +162,71 @@ export function createTransport(config) {
             requestInit: config.headers
                 ? { headers: config.headers }
                 : undefined,
+            // Deduped-refresh fetch for auth:"oauth" (symmetric with the SSE branch).
+            // The wrapper composes on top of the redirect-policy fetch so cross-host
+            // header scrub still applies. Same policy as the SSE branch above;
+            // see mcp-client-redirect-policy.ts.
+            fetch: config.oauthFetch ?? createRedirectPolicyFetch({ maxRedirections: 20 }),
+            // Attach the OAuthClientProvider adapter ONLY for auth:"oauth" servers with
+            // a constructed provider (symmetric with the SSE branch). requestInit +
+            // fetch above are untouched.
+            ...(config.auth === "oauth" && config.oauthProvider
+                ? { authProvider: config.oauthProvider }
+                : {}),
         });
     }
     throw new Error(`MCP server "${config.name}": unsupported transport "${config.transport}"`);
 }
 // ---------------------------------------------------------------------------
+// tools/list_changed diff (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Stable, content-free fingerprint of a tool's MUTABLE contract surface
+ * (`description` + `inputSchema`). Two tools sharing a name are "changed"
+ * iff their fingerprints differ. JSON.stringify gives a deterministic
+ * serialization for the plain JSON-Schema objects MCP servers return
+ * (object/array/string/number/boolean/null — no functions, no symbols).
+ */
+function toolContractFingerprint(tool) {
+    return JSON.stringify({
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    });
+}
+/**
+ * Diff a previous vs. new MCP tool list by NAME, plus detect IN-PLACE
+ * mutation of a surviving tool's contract.
+ *
+ *   - addedTools:   names present in `next` but not `previous`
+ *   - removedTools: names present in `previous` but not `next`
+ *   - changedTools: names present in BOTH whose `description` or `inputSchema`
+ *     changed — the CVE-2025-54136 "rug-pull" (a tool approved/seen with one
+ *     schema is silently swapped for another mid-session). A name-only diff
+ *     misses this entirely.
+ *
+ * Returns NAMES ONLY in every bucket — never the (untrusted, server-controlled)
+ * schemas/descriptions themselves, so the result is safe to put on an event
+ * payload / log line. Pure: no I/O, no state.
+ */
+export function diffToolLists(previousTools, newTools) {
+    const previousByName = new Map(previousTools.map((t) => [t.name, t]));
+    const currentNames = new Set(newTools.map((t) => t.name));
+    const addedTools = newTools.filter((t) => !previousByName.has(t.name)).map((t) => t.name);
+    const removedTools = previousTools
+        .filter((t) => !currentNames.has(t.name))
+        .map((t) => t.name);
+    const changedTools = [];
+    for (const t of newTools) {
+        const prev = previousByName.get(t.name);
+        if (!prev)
+            continue; // added — handled above
+        if (toolContractFingerprint(prev) !== toolContractFingerprint(t)) {
+            changedTools.push(t.name);
+        }
+    }
+    return { addedTools, removedTools, changedTools };
+}
+// ---------------------------------------------------------------------------
 // MCP Client creation helper (with listChanged handler)
 // ---------------------------------------------------------------------------
 /**
@@ -124,19 +262,26 @@ export function createClient(state, deps, serverName) {
                             tools: newTools,
                             lastHealthCheck: systemNowMs(),
                         });
-                        const previousNames = new Set(previousTools.map(t => t.name));
-                        const currentNames = new Set(newTools.map(t => t.name));
-                        const addedTools = newTools.filter(t => !previousNames.has(t.name)).map(t => t.name);
-                        const removedTools = previousTools.filter(t => !currentNames.has(t.name)).map(t => t.name);
-                        deps.eventBus.emit("mcp:server:tools_changed", {
-                            serverName,
-                            previousToolCount: previousTools.length,
-                            currentToolCount: newTools.length,
-                            addedTools,
-                            removedTools,
-                            timestamp: systemNowMs(),
-                        });
-                        logger.info({ serverName, previousCount: previousTools.length, currentCount: newTools.length, added: addedTools, removed: removedTools }, "MCP server tool list changed");
+                        // Diff BY NAME (added/removed) AND detect in-place mutation of a
+                        // surviving tool's contract (changedTools) — the CVE-2025-54136
+                        // "rug-pull" a name-only diff would miss.
+                        const { addedTools, removedTools, changedTools } = diffToolLists(previousTools, newTools);
+                        // Fire only when something actually changed (add / remove /
+                        // in-place schema-or-description mutation). A bare
+                        // tools/list_changed notification that resolves to an identical
+                        // list emits no signal.
+                        if (addedTools.length || removedTools.length || changedTools.length) {
+                            deps.eventBus.emit("mcp:server:tools_changed", {
+                                serverName,
+                                previousToolCount: previousTools.length,
+                                currentToolCount: newTools.length,
+                                addedTools,
+                                removedTools,
+                                changedTools,
+                                timestamp: systemNowMs(),
+                            });
+                            logger.info({ serverName, previousCount: previousTools.length, currentCount: newTools.length, added: addedTools, removed: removedTools, changed: changedTools }, "MCP server tool list changed");
+                        }
                     },
                 },
             },

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/mcp-client-idle-eviction.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-server idle eviction.
+ *
+ * Schedules a per-server `systemSetTimeout` that fires `evictIdleServer`
+ * when no successful tool call has reset the timer for `config.idleTtlMs`
+ * milliseconds. Default `idleTtlMs: 0` → ticker is NOT started (opt-in
+ * semantics, mirroring the keepalive ticker's `0`-disables convention).
+ *
+ * **Critical divergence from disconnectServer (the load-bearing point):**
+ * `evictIdleServer` mirrors `disconnectServer`'s teardown (abort reconnect
+ * controller, close client, stop keepalive ticker, clear/delete the call
+ * queue, delete the connection) but pointedly does NOT add the server name
+ * to `state.userDisconnectedFlags` AND does NOT delete `state.serverConfigs`.
+ * `disconnectServer` (mcp-client-connect.ts) does both. The flag would
+ * suppress auto-reconnect at mcp-client-reconnect.ts:136-138; retaining the
+ * stored config lets the lazy-reconnect branch in mcp-client-call.ts read it
+ * and call `reconnectServer`, producing the spec's "next callTool reconnects
+ * transparently" UX.
+ *
+ * @module
+ */
+import type { McpClientManagerDeps, McpClientManagerState, McpServerConfig } from "./mcp-client-types.js";
+/**
+ * Start the idle-eviction ticker for a freshly-connected server. Called from
+ * connectServer immediately after startKeepaliveTicker.
+ *
+ * Resolution: per-server `config.idleTtlMs` (no global default — eviction is
+ * opt-in per server). `0` (or undefined) is a NO-OP: the ticker is never
+ * scheduled and `resetIdleActivity` becomes inert for this server.
+ */
+export declare function startIdleTicker(state: McpClientManagerState, deps: McpClientManagerDeps, config: McpServerConfig): void;
+/**
+ * Stop the idle ticker. Called from disconnectServer (after stopKeepaliveTicker)
+ * AND from evictIdleServer itself. Clears the pending timer handle and drops
+ * the last-activity bookkeeping so a future reconnect starts clean.
+ */
+export declare function stopIdleTicker(state: McpClientManagerState, name: string): void;
+/**
+ * Record activity for a server. Called from mcp-client-call.ts on the success
+ * path. Only refreshes the timestamp when a timer is armed (i.e. idleTtlMs > 0
+ * for this server) — otherwise inert. Does NOT reschedule: the self-rescheduling
+ * timer re-reads lastActivityMs on each fire and pushes the deadline forward.
+ */
+export declare function resetIdleActivity(state: McpClientManagerState, name: string): void;

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/mcp-client-idle-eviction.js

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-server idle eviction.
+ *
+ * Schedules a per-server `systemSetTimeout` that fires `evictIdleServer`
+ * when no successful tool call has reset the timer for `config.idleTtlMs`
+ * milliseconds. Default `idleTtlMs: 0` → ticker is NOT started (opt-in
+ * semantics, mirroring the keepalive ticker's `0`-disables convention).
+ *
+ * **Critical divergence from disconnectServer (the load-bearing point):**
+ * `evictIdleServer` mirrors `disconnectServer`'s teardown (abort reconnect
+ * controller, close client, stop keepalive ticker, clear/delete the call
+ * queue, delete the connection) but pointedly does NOT add the server name
+ * to `state.userDisconnectedFlags` AND does NOT delete `state.serverConfigs`.
+ * `disconnectServer` (mcp-client-connect.ts) does both. The flag would
+ * suppress auto-reconnect at mcp-client-reconnect.ts:136-138; retaining the
+ * stored config lets the lazy-reconnect branch in mcp-client-call.ts read it
+ * and call `reconnectServer`, producing the spec's "next callTool reconnects
+ * transparently" UX.
+ *
+ * @module
+ */
+import { systemClearTimeout, systemNowMs, systemSetTimeout } from "@comis/core";
+import { stopKeepaliveTicker } from "./mcp-client-keepalive.js";
+/**
+ * Start the idle-eviction ticker for a freshly-connected server. Called from
+ * connectServer immediately after startKeepaliveTicker.
+ *
+ * Resolution: per-server `config.idleTtlMs` (no global default — eviction is
+ * opt-in per server). `0` (or undefined) is a NO-OP: the ticker is never
+ * scheduled and `resetIdleActivity` becomes inert for this server.
+ */
+export function startIdleTicker(state, deps, config) {
+    const ttl = config.idleTtlMs ?? 0;
+    if (ttl === 0)
+        return; // Disabled (default; opt-in per server)
+    // Seed last-activity to "now" so the first eviction fires ttl ms after connect.
+    state.lastActivityMs.set(config.name, systemNowMs());
+    scheduleNextEviction(state, deps, config.name, ttl);
+}
+/**
+ * Stop the idle ticker. Called from disconnectServer (after stopKeepaliveTicker)
+ * AND from evictIdleServer itself. Clears the pending timer handle and drops
+ * the last-activity bookkeeping so a future reconnect starts clean.
+ */
+export function stopIdleTicker(state, name) {
+    const handle = state.idleEvictionTimers.get(name);
+    if (handle !== undefined) {
+        systemClearTimeout(handle);
+        state.idleEvictionTimers.delete(name);
+    }
+    state.lastActivityMs.delete(name);
+}
+/**
+ * Record activity for a server. Called from mcp-client-call.ts on the success
+ * path. Only refreshes the timestamp when a timer is armed (i.e. idleTtlMs > 0
+ * for this server) — otherwise inert. Does NOT reschedule: the self-rescheduling
+ * timer re-reads lastActivityMs on each fire and pushes the deadline forward.
+ */
+export function resetIdleActivity(state, name) {
+    if (!state.idleEvictionTimers.has(name))
+        return;
+    state.lastActivityMs.set(name, systemNowMs());
+}
+/**
+ * Schedule (or reschedule) the single-fire eviction timer. On fire it compares
+ * elapsed idle time against the FULL TTL: evict when idle long enough,
+ * otherwise reschedule for the remaining window (so activity since the last
+ * schedule transparently defers eviction).
+ *
+ * `originalTtl` is the configured idleTtlMs and is threaded UNCHANGED
+ * through every reschedule — the eviction always fires at last-activity +
+ * idleTtlMs. `remainingMs` is only the timer delay for the NEXT fire
+ * (defaults to `originalTtl` on the first call). A previous version passed
+ * `ttl - idleFor` as the new `ttl`, which shrank the comparison threshold on
+ * every activity bounce — bursty servers drifted toward premature eviction
+ * (and ever-shorter poll intervals).
+ */
+function scheduleNextEviction(state, deps, name, originalTtl, remainingMs) {
+    // Clear any prior pending timer for safety (idempotent reschedule).
+    const prior = state.idleEvictionTimers.get(name);
+    if (prior !== undefined)
+        systemClearTimeout(prior);
+    const delay = remainingMs ?? originalTtl;
+    const handle = systemSetTimeout(() => {
+        const lastActivity = state.lastActivityMs.get(name);
+        const conn = state.connections.get(name);
+        if (lastActivity === undefined || !conn || conn.status !== "connected") {
+            // Server already gone (disconnected / errored / reconnecting). Nothing to do.
+            state.idleEvictionTimers.delete(name);
+            return;
+        }
+        const idleFor = systemNowMs() - lastActivity;
+        if (idleFor >= originalTtl) {
+            // Never tear down a connection with an outstanding tool call.
+            // The success path resets lastActivityMs, but a call that is in-flight
+            // (or queued) when the timer fires has not reached that reset yet — an
+            // in-flight callTool IS activity. Treat a non-empty call queue as a
+            // deferral signal and reschedule a fresh full window rather than
+            // evicting mid-flight (which would race callTool's queue.add /
+            // generation-capture and surface a misleading error to the caller).
+            const queue = state.callQueues.get(name);
+            if (queue && (queue.pending > 0 || queue.size > 0)) {
+                scheduleNextEviction(state, deps, name, originalTtl);
+                return;
+            }
+            void evictIdleServer(state, deps, name);
+            return;
+        }
+        // Activity since last schedule → reschedule for the remaining window
+        // measured against the ORIGINAL TTL (deadline = lastActivity + originalTtl).
+        scheduleNextEviction(state, deps, name, originalTtl, originalTtl - idleFor);
+    }, delay);
+    // No .unref() here: daemon shutdown routes through disconnectAllServers →
+    // disconnectServer → stopIdleTicker, which clears the handle deterministically.
+    state.idleEvictionTimers.set(name, handle);
+}
+/**
+ * Tear down an idle server. Mirrors disconnectServer's teardown EXCEPT for two
+ * load-bearing omissions (see module docblock): it does NOT mutate
+ * userDisconnectedFlags and does NOT delete serverConfigs.
+ */
+async function evictIdleServer(state, deps, name) {
+    const { logger } = deps;
+    // Idle eviction is normal scheduled behavior, not an error condition.
+    // errorKind (and hint) belong on WARN/ERROR logs only —
+    // attaching them to this INFO line misleads observability tooling that
+    // filters on errorKind. The serverName alone is sufficient for correlation.
+    logger.info({ serverName: name }, "MCP server idle eviction");
+    // Abort any in-flight reconnection (mirrors disconnectServer).
+    const ac = state.reconnectionAbortControllers.get(name);
+    if (ac) {
+        ac.abort();
+        state.reconnectionAbortControllers.delete(name);
+    }
+    // Close the transport. Errors during close are non-fatal — log and continue.
+    const conn = state.connections.get(name);
+    if (conn?.client && conn.status === "connected") {
+        try {
+            await conn.client.close();
+        }
+        catch (error) {
+            logger.warn({
+                serverName: name,
+                err: error instanceof Error ? error.message : String(error),
+                hint: "Idle eviction close failed; teardown continues",
+                errorKind: "dependency",
+            }, "MCP idle-eviction client.close() failed");
+        }
+    }
+    // Stop the keepalive ticker BEFORE deleting the queue (mirrors disconnectServer:
+    // the ticker must not fire one last queue.add against a queue we are deleting).
+    stopKeepaliveTicker(state, name);
+    // Clear + delete the call queue.
+    const queue = state.callQueues.get(name);
+    if (queue) {
+        queue.clear();
+        state.callQueues.delete(name);
+    }
+    // Tear down the dedicated keepalive queue alongside the
+    // call queue (only populated when primary concurrency > 1). Mirrors
+    // disconnectServer so the queue cannot leak across reconnect generations.
+    const keepaliveQueue = state.keepaliveQueues.get(name);
+    if (keepaliveQueue) {
+        keepaliveQueue.clear();
+        state.keepaliveQueues.delete(name);
+    }
+    // Stop our own idle ticker (clears handle + lastActivity).
+    stopIdleTicker(state, name);
+    // Delete the connection.
+    state.connections.delete(name);
+    // **CRITICAL (divergence 1):** do NOT call state.userDisconnectedFlags.add(name).
+    // disconnectServer (mcp-client-connect.ts:264) adds it unconditionally, which
+    // suppresses auto-reconnect at mcp-client-reconnect.ts:136-138. Idle eviction
+    // must leave auto-reconnect enabled.
+    // **CRITICAL (divergence 2):** do NOT call state.serverConfigs.delete(name).
+    // disconnectServer (mcp-client-connect.ts:298) deletes it; the lazy-reconnect
+    // branch in mcp-client-call.ts reads serverConfigs to reconnect transparently.
+    // generations is preserved too (disconnectServer keeps it as well).
+}

package/node_modules/@comis/skills/dist/skills/integrations/mcp-client/mcp-client-keepalive.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Per-server keepalive ticker.
+ *
+ * Schedules a periodic Client.ping() through the per-server PQueue. On
+ * failure, triggers handleDisconnection so the existing reconnect engine
+ * recovers. Ping is SKIPPED when the queue has pending items (recent
+ * activity is a stronger liveness signal than the keepalive itself).
+ *
+ * Extracted into its own ~80L file to keep mcp-client-connect.ts under
+ * the 800-line file-size cap. Future work may revisit keepalive queue
+ * routing for parallel-tool-call mode.
+ *
+ * @module
+ */
+export { stopKeepaliveTicker } from "./mcp-client-ticker.js";
+import type { McpClientManagerDeps, McpClientManagerState, McpServerConfig } from "./mcp-client-types.js";
+import { type RefreshDeduper } from "./oauth/refresh-deduper.js";
+/** Default keepalive interval for http/sse/streamable-http transports (beats ~60s idle window). */
+export declare const KEEPALIVE_INTERVAL_HTTP_SSE_MS = 30000;
+/** Default keepalive interval for stdio transports (unchanged; stdio has no idle-close). */
+export declare const KEEPALIVE_INTERVAL_STDIO_MS = 180000;
+/**
+ * Pre-expiry buffer for proactive OAuth token refresh.
+ * When a token's remaining lifetime (expires_in) is within this threshold,
+ * the keepalive tick refreshes it proactively so the next tool call does not 401.
+ * 5 minutes: ensures at least one keepalive tick fires within the window
+ * for both http (30s interval) and stdio (180s interval) transports.
+ */
+export declare const PRE_EXPIRY_BUFFER_MS: number;
+/**
+ * Resolve the default keepalive interval for a given transport type.
+ *
+ * This is the single source of truth for keepalive defaults:
+ *   - stdio: 180 000 ms (no idle window; unchanged from previous global default)
+ *   - http / sse / streamable-http: 30 000 ms (beats the ~60s server-side idle close)
+ *
+ * Per-server `config.keepaliveIntervalMs` always takes precedence over this default
+ * (via the nullish coalescing in startKeepaliveTicker).
+ *
+ * @param transport - The McpServerConfig transport type string.
+ */
+export declare function resolveDefaultKeepaliveIntervalMs(transport: McpServerConfig["transport"]): number;
+/**
+ * Start the keepalive ticker for a freshly-connected server. Called from
+ * connectServer immediately after state.callQueues.set(...). The ticker
+ * is .unref()'d so SIGTERM teardown is not blocked.
+ *
+ * Resolution at this call site: `config.keepaliveIntervalMs` ??
+ * resolveDefaultKeepaliveIntervalMs(config.transport).
+ *
+ * The upstream callers (mcp-handlers.ts mcp.connect, setup-mcp.ts) apply the
+ * full three-tier chain before populating config.keepaliveIntervalMs:
+ *   per-server RPC param ?? persisted per-server entry ?? global
+ *   integrations.mcp.keepaliveIntervalMs. The result lands in
+ *   config.keepaliveIntervalMs before startKeepaliveTicker is called, so
+ *   this function only needs to resolve the final transport-aware default.
+ * Uses `??` (NOT `||`) so an operator can set `0` to disable per-server.
+ *
+ * @param onFailure - Optional callback invoked when a keepalive ping fails. Callers
+ *   supply `(name) => handleDisconnection(state, deps, name, "keepalive_failed")` so
+ *   this module does not import mcp-client-reconnect.ts (which would create a
+ *   keepalive ↔ reconnect source cycle detected by no-cycles.test.ts). When omitted
+ *   (tests that exercise registration without testing failure paths) the failure
+ *   callback is a silent no-op.
+ * @returns void — `0` interval is a NO-OP (explicit semantics: zero disables keepalive).
+ */
+export declare function startKeepaliveTicker(state: McpClientManagerState, deps: McpClientManagerDeps, config: McpServerConfig, onFailure?: (serverName: string) => void): void;
+/**
+ * Tick callback. Routes a Client.ping() based on the primary call queue's
+ * concurrency:
+ *
+ *  - concurrency === 1 (default/stdio): the ping shares the primary PQueue
+ *    (stdio single-pipe serialization) and is SKIPPED when the queue is
+ *    busy. Recent tool-call activity is a stronger liveness signal than a
+ *    synthetic probe.
+ *
+ *  - concurrency > 1 (supportsParallelToolCalls): a synthetic ping must not
+ *    interleave with real parallel tool calls. The ping is enqueued on a
+ *    DEDICATED concurrency-1 queue whose body first awaits the primary
+ *    queue's onIdle() (NOT onEmpty — onEmpty resolves while in-flight calls
+ *    still run). The dedicated queue is lazily created here and torn down on
+ *    disconnect / idle-eviction (mirrors callQueues), so it cannot leak.
+ *
+ * On ping failure, invokes `onFailure(serverName)` in BOTH routes — the
+ * reconnect engine handles recovery from there. When `onFailure` is
+ * undefined (test-only call sites that don't test the failure path) the
+ * failure is a silent no-op.
+ *
+ * Deadlock-free proactive refresh:
+ * The near-expiry check and `await dedupedRefresh(...)` run inside
+ * `primary.add(refreshAndPing)` but the deduper's internal critical section
+ * uses a DEDICATED per-tick cc-1 queue (not the primary queue) so there is no
+ * nested `primary.add` inside a running `primary.add`. This preserves the
+ * single-queue atomicity contract for the dedup map check+set while
+ * eliminating the deadlock. The dedup guarantee is provided by `inflightRefreshes`
+ * (shared across proactive + 401 paths); the per-tick queue merely prevents
+ * two concurrent ticks from double-refreshing via the same accessToken key.
+ *
+ * @param deduper - Optional test seam. When provided (tests), the
+ *   proactive-refresh path uses the injected deduper's dedupedRefresh as the spy.
+ *   When omitted (all production call sites — startKeepaliveTicker stays 4-arg),
+ *   the deduper is reconstructed in-place from state.inflightRefreshes + a fresh
+ *   per-tick cc-1 queue (uses a dedicated queue, not primary, to prevent the
+ *   concurrency-1 deadlock; inflightRefreshes still coalesces with the 401 path).
+ *   Do NOT thread this param through startKeepaliveTicker.
+ */
+export declare function maybeEnqueueKeepalivePing(state: McpClientManagerState, deps: McpClientManagerDeps, serverName: string, onFailure?: (serverName: string) => void, deduper?: RefreshDeduper): void;