@juspay/neurolink 12.27.0 → 12.27.2

package/dist/cli/factories/commandFactory.js

@@ -15,6 +15,7 @@ import { createThinkingConfigFromRecord } from "../../utils/thinkingConfig.js";
 import { buildToolRoutingConfigFromCli } from "../utils/toolRoutingFlags.js";
 import { buildClassifierRouterConfigFromCli } from "../utils/classifierRouterFlags.js";
 import { buildSkillsConfigFromCli } from "../utils/skillsFlags.js";
+import { ensureStdinRef } from "../utils/stdinRef.js";
 import { SkillsManager } from "../../skills/skillsManager.js";
 import { configManager } from "../commands/config.js";
 import { MCPCommandFactory } from "../commands/mcp.js";
@@ -2275,6 +2276,11 @@ export class CLICommandFactory {
         const isSttOnly = !!(argv.stt &&
             argv.inputAudio);
         if (!argv.input && !process.stdin.isTTY) {
+            // The SDK's MCP stdio transport unrefs stdin on import so an idle
+            // process can exit on its own (see externalServerManager.ts). This
+            // path actually reads stdin and must block on it, so ref it back
+            // before consuming.
+            ensureStdinRef();
             let stdinData = "";
             process.stdin.setEncoding("utf8");
             for await (const chunk of process.stdin) {
@@ -3322,6 +3328,11 @@ export class CLICommandFactory {
         // as the prompt). Skip the stdin/empty-input rejection in that case.
         const isSttOnly = !!argv.stt && !!argv.inputAudio;
         if (!argv.input && !process.stdin.isTTY) {
+            // The SDK's MCP stdio transport unrefs stdin on import so an idle
+            // process can exit on its own (see externalServerManager.ts). This
+            // path actually reads stdin and must block on it, so ref it back
+            // before consuming.
+            ensureStdinRef();
             let stdinData = "";
             process.stdin.setEncoding("utf8");
             for await (const chunk of process.stdin) {
@@ -4320,6 +4331,11 @@ export class CLICommandFactory {
                 logger.always(chalk.yellow(`Usage: neurolink memory delete ${argv.sessionId} --force`));
                 return;
             }
+            // The SDK's MCP stdio transport unrefs stdin on import so an idle
+            // process can exit on its own (see externalServerManager.ts). This
+            // prompt actually reads stdin and must block on it, so ref it back
+            // before consuming.
+            ensureStdinRef();
             const readline = await import("readline");
             const rl = readline.createInterface({
                 input: process.stdin,

package/dist/cli/loop/session.js

@@ -10,6 +10,7 @@ import { tracers } from "../../telemetry/tracers.js";
 import { handleError } from "../errorHandler.js";
 import { ConversationSelector } from "./conversationSelector.js";
 import { textGenerationOptionsSchema } from "./optionsSchema.js";
+import { ensureStdinRef } from "../utils/stdinRef.js";
 // Banner Art
 const NEUROLINK_BANNER = `
 ▗▖  ▗▖▗▄▄▄▖▗▖ ▗▖▗▄▄▖  ▗▄▖ ▗▖   ▗▄▄▄▖▗▖  ▗▖▗▖ ▗▖
@@ -455,6 +456,11 @@ export class LoopSession {
      * Get command input with history support using readline
      */
     async getCommandWithHistory() {
+        // The SDK's MCP stdio transport unrefs stdin on import so an idle
+        // process can exit on its own (see externalServerManager.ts). The
+        // interactive loop reads a line from stdin on every prompt and must
+        // block on it, so ref it back before consuming.
+        ensureStdinRef();
         return new Promise((resolve) => {
             const rl = readline.createInterface({
                 input: process.stdin,

package/dist/cli/utils/stdinRef.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The SDK unrefs `process.stdin` on import (see externalServerManager.ts) so
+ * that a process which never reads stdin can still exit on its own instead
+ * of being kept alive forever by a handle it never uses. Any CLI code path
+ * that actually reads from stdin — piped generate/stream input, a readline
+ * confirmation prompt, the interactive loop's line reader — must ref it
+ * back first, or the process can exit (or simply never treat stdin as a
+ * reason to stay alive) before the read completes.
+ *
+ * Centralizing the call here means a new stdin consumer only has to
+ * remember to call this, not to rediscover and re-derive the reason why.
+ * Three call sites each doing this inline already produced one that forgot
+ * to (the memory-delete confirmation prompt) — a fourth is just as likely
+ * to repeat that.
+ */
+export declare function ensureStdinRef(): void;

package/dist/cli/utils/stdinRef.js

@@ -0,0 +1,21 @@
+/**
+ * The SDK unrefs `process.stdin` on import (see externalServerManager.ts) so
+ * that a process which never reads stdin can still exit on its own instead
+ * of being kept alive forever by a handle it never uses. Any CLI code path
+ * that actually reads from stdin — piped generate/stream input, a readline
+ * confirmation prompt, the interactive loop's line reader — must ref it
+ * back first, or the process can exit (or simply never treat stdin as a
+ * reason to stay alive) before the read completes.
+ *
+ * Centralizing the call here means a new stdin consumer only has to
+ * remember to call this, not to rediscover and re-derive the reason why.
+ * Three call sites each doing this inline already produced one that forgot
+ * to (the memory-delete confirmation prompt) — a fourth is just as likely
+ * to repeat that.
+ */
+export function ensureStdinRef() {
+    if (process.stdin && typeof process.stdin.ref === "function") {
+        process.stdin.ref();
+    }
+}
+//# sourceMappingURL=stdinRef.js.map

package/dist/mcp/externalServerManager.js

@@ -18,6 +18,45 @@ import { isObject, isNonNullObject } from "../utils/typeUtils.js";
 import { TelemetryService } from "../telemetry/telemetryService.js";
 import { tracers } from "../telemetry/tracers.js";
 import { SpanStatusCode } from "@opentelemetry/api";
+// `@modelcontextprotocol/sdk`'s stdio transport (imported above) does
+// `import process from "node:process"` at module scope. Node's ESM/CJS
+// interop builds a synthetic module facade for that import by walking every
+// property getter on the builtin `process` singleton — including the
+// lazily-initialized `stdin` getter — so merely importing this module
+// creates and permanently refs a stdin handle, whether or not an MCP stdio
+// client is ever constructed. A single ref'd handle is enough to keep the
+// event loop, and the whole process, alive forever. unref() does not close
+// stdin or stop it from being read (a consumer that later actually reads
+// from it — e.g. the CLI's piped-input path — calls `.ref()` again right
+// before it does), it only stops an otherwise-idle stdin from blocking exit.
+//
+// This unref runs at import time, before any consumer of THIS package —
+// this package's own CLI paths and an external SDK caller alike — has had a
+// chance to attach its own stdin listeners. A CLI code path knows to call
+// `ensureStdinRef()` first (see src/cli/utils/stdinRef.ts), but an external
+// script that just does `import { NeuroLink } from "@juspay/neurolink"` and
+// then reads `process.stdin` itself — an ordinary, previously-working
+// pattern — has no reason to know this package touched stdin at all, and
+// without a safety net the process can exit before the piped data ever
+// arrives: silently, with no error, because an unref'd handle simply stops
+// keeping the event loop alive on its own.
+//
+// So: re-ref stdin the first time anything registers a listener that
+// actually consumes it. "data" covers `.on("data", ...)` directly and
+// `.pipe()` (which attaches its own "data" listener internally); "readable"
+// covers paused-mode reads and the async iterator
+// (`for await (const chunk of process.stdin)`, which attaches a "readable"
+// listener under the hood). This restores stdin's normal, non-unref'd
+// behavior for any real consumer — internal or external — while a process
+// that never touches stdin still exits on its own.
+if (process.stdin && typeof process.stdin.unref === "function") {
+    process.stdin.unref();
+    process.stdin.prependListener("newListener", (event) => {
+        if (event === "data" || event === "readable") {
+            process.stdin.ref();
+        }
+    });
+}
 /**
  * Recursively substitute environment variables in strings
  * Replaces ${VAR_NAME} with the value from process.env.VAR_NAME
@@ -218,18 +257,127 @@ function isValidExternalMCPServerConfig(config) {
  */
 const liveManagers = new Set();
 let processCleanupInstalled = false;
-const shutdownLiveManagers = () => {
-    for (const manager of liveManagers) {
-        void manager.shutdown();
-    }
+const cleanupLiveManagers = async () => {
+    // Concurrent across managers, matching the pattern one level down: a
+    // single manager's own shutdown() already fans its servers out via
+    // Promise.all rather than awaiting them one at a time. A sequential
+    // for-await here would make total SIGTERM/beforeExit cleanup time scale
+    // with the number of concurrently-alive managers instead of being bounded
+    // by the slowest one — real for this codebase, since the shared handler
+    // set above exists specifically because multiple managers are commonly
+    // alive at once (one per worker an agent delegates to).
+    await Promise.all(Array.from(liveManagers).map((manager) => manager.shutdown().catch((error) => {
+        mcpLogger.error("[ExternalServerManager] Error during process-exit cleanup:", error);
+    })));
+};
+/**
+ * beforeExit fires when the event loop is about to go idle. The cleanup it
+ * kicks off does its own async I/O, so this cycle will not drain — Node
+ * fires beforeExit again once that work resolves and finds nothing left,
+ * which is how the process is meant to exit on its own here, without an
+ * explicit process.exit() call.
+ */
+const shutdownOnBeforeExit = () => {
+    void cleanupLiveManagers();
+};
+/**
+ * signal-exit@4 (reached at runtime through `ora` -> `cli-cursor` ->
+ * `restore-cursor`, a direct dependency this package's CLI spinners use)
+ * makes the mirror-image decision to the gate below: it skips its own
+ * post-cleanup re-raise whenever it sees another listener for the signal
+ * still registered. Counting signal-exit's listener as host-owned here means
+ * both sides defer to the other and neither ever re-raises — a live
+ * spinner's cursor-restore listener would silently reintroduce the exact
+ * defect this file exists to fix.
+ *
+ * There's no reference to signal-exit's own listener function to compare
+ * against (it's private state inside that package), so it's detected the
+ * same way signal-exit's v3/v4 majors detect each other: a shared marker
+ * signal-exit itself defines. Every signal-exit v4 instance is a
+ * `globalThis`-wide singleton keyed by `Symbol.for("signal-exit emitter")`
+ * — but that key is shared across ANY number of distinct resolved copies of
+ * the package, not just identical ones. If two transitive dependencies pin
+ * non-overlapping signal-exit@4 ranges, npm/pnpm will not dedupe them, and
+ * each loaded copy independently increments the shared emitter's `count` by
+ * one AND registers its own real, distinct listener per signal it covers
+ * (SIGINT and SIGTERM both are, in every signal-exit v4 release). So `count`
+ * is a faithful running total of real signal-exit-owned listeners on
+ * `process` — one per loaded copy — and has to be discounted in full,
+ * never clamped to at most one, or a second loaded copy's very real
+ * listener gets miscounted as a host's own and silently defeats the
+ * re-raise this file exists to perform.
+ */
+const SIGNAL_EXIT_EMITTER = Symbol.for("signal-exit emitter");
+const getSignalExitOwnedListenerCount = () => {
+    const globalWithSignalExit = globalThis;
+    const count = globalWithSignalExit[SIGNAL_EXIT_EMITTER]?.count;
+    return typeof count === "number" && count > 0 ? count : 0;
+};
+/**
+ * SIGINT/SIGTERM: registering a listener for either suppresses Node's
+ * default immediate-termination behavior for that signal. The previous
+ * handler ran cleanup fire-and-forget and never terminated the process
+ * afterward, so the process survived a signal it claimed to handle and
+ * needed SIGKILL to actually stop.
+ *
+ * This must NOT call process.exit() itself — this is library code that can
+ * run inside a host application, and unilaterally choosing the process's
+ * exit code/timing pre-empts whatever shutdown behavior the host installed
+ * for this same signal. Instead, once cleanup settles, remove our own
+ * listener and re-send the signal: if the host registered its own handler
+ * it now runs (we are no longer in front of it), and if nothing else is
+ * listening, Node's default terminate-on-signal behavior applies and the
+ * exit code is the correct signal-based one without us deciding it. Either
+ * way the process actually stops in response to the signal, which is the
+ * behavior this fixes — we just stop being the one that forces it down.
+ */
+const shutdownOnSignal = (signal) => {
+    // Whether anyone ELSE is listening has to be decided HERE, synchronously, at
+    // the top of the dispatch — not after cleanup resolves. Node removes a
+    // `process.once` listener as it dispatches to it, so a host using the very
+    // common one-shot shutdown shape leaves a listener count of zero behind
+    // while its own async drain is still running. Reading the count later would
+    // see that zero, conclude nobody was listening, re-raise, and kill the host
+    // mid-shutdown — the exact harm this gate exists to prevent, reached from
+    // the other side. Pairing this snapshot with `prependListener` at
+    // registration is what makes it correct: we run before any other listener,
+    // so nothing has been consumed yet and every host listener is still counted.
+    //
+    // signal-exit's own listener (if loaded) is subtracted out first: it is a
+    // cursor-restore helper, not a host that owns this process's shutdown
+    // decision, and counting it as one would defer to it forever (see above).
+    const hadOtherListeners = process.listenerCount(signal) - getSignalExitOwnedListenerCount() > 1;
+    void cleanupLiveManagers().finally(() => {
+        // With a host handler present, that handler already received this delivery
+        // and already made its own keep-alive/exit decision; re-sending would run
+        // it a second time it never asked for, and for the common "first signal
+        // drains, second one forces" shape that tears it down early.
+        //
+        // Note what is NOT done in that case: the listener stays registered. A
+        // host that owns the signal may well decide to keep running, and
+        // `processCleanupInstalled` is a one-shot latch — so a listener removed
+        // here is never reinstalled, and any manager constructed afterwards would
+        // silently lose signal cleanup for the rest of the process's life. The
+        // removal exists for exactly one purpose, to let the re-raise reach Node's
+        // default disposition instead of coming back to us, so it belongs with the
+        // re-raise and nowhere else.
+        if (!hadOtherListeners) {
+            process.removeListener(signal, shutdownOnSignal);
+            process.kill(process.pid, signal);
+        }
+    });
 };
 const registerManagerForProcessCleanup = (manager) => {
     liveManagers.add(manager);
     if (!processCleanupInstalled) {
         processCleanupInstalled = true;
-        process.on("SIGINT", shutdownLiveManagers);
-        process.on("SIGTERM", shutdownLiveManagers);
-        process.on("beforeExit", shutdownLiveManagers);
+        // prependListener, not on: the gate above counts listeners at dispatch, and
+        // that count is only trustworthy if nothing has been consumed yet. Running
+        // first guarantees that. It also costs a host nothing — our handler only
+        // starts async cleanup and never blocks the listeners behind it.
+        process.prependListener("SIGINT", shutdownOnSignal);
+        process.prependListener("SIGTERM", shutdownOnSignal);
+        process.on("beforeExit", shutdownOnBeforeExit);
     }
 };
 export class ExternalServerManager extends EventEmitter {
@@ -994,7 +1142,15 @@ export class ExternalServerManager extends EventEmitter {
         instance.client.onclose = undefined;
         instance.client.onerror = undefined;
         try {
-            await MCPClientFactory.closeClient(instance.client, instance.transportInstance);
+            // Forward the child handle so the factory's SIGKILL escalation can run
+            // when the transport's own close does not bring the process down.
+            // NOTE: `instance.process` is currently always null for stdio servers —
+            // MCPClientFactory.createStdioTransport returns only `{ transport }`, so
+            // `clientResult.process` is never populated and the escalation inside
+            // closeClient remains unreachable. Surfacing the spawned child from the
+            // transport is a separate change; this argument is wired so that it
+            // starts working the moment it is.
+            await MCPClientFactory.closeClient(instance.client, instance.transportInstance, instance.process ?? undefined);
         }
         catch (error) {
             mcpLogger.debug(`[ExternalServerManager] Error closing client for ${serverId}:`, error);
@@ -1256,6 +1412,15 @@ export class ExternalServerManager extends EventEmitter {
         instance.healthTimer = setInterval(async () => {
             await this.performHealthCheck(serverId);
         }, interval);
+        // Unref'd so a live health check on a connected server doesn't itself
+        // keep an otherwise-idle process alive — a caller that never calls
+        // shutdown()/stopServer() (e.g. a script that just uses the SDK and
+        // lets the process exit naturally) shouldn't be forced to wait out
+        // this interval. stopServer() still clearInterval()s it for explicit
+        // lifecycle management.
+        if (instance.healthTimer.unref) {
+            instance.healthTimer.unref();
+        }
     }
     /**
      * Perform a health check by pinging the server over its live transport.

package/dist/mcp/mcpCircuitBreaker.d.ts

@@ -58,9 +58,14 @@ export declare class MCPCircuitBreaker extends EventEmitter {
      */
     private changeState;
     /**
-     * Create a timeout promise
-     */
-    private timeoutPromise;
+     * Race an operation against a timeout, clearing the timer on either
+     * outcome. A bare `Promise.race([operation, timeoutPromise])` leaves the
+     * timeout's `setTimeout` handle ref'd and pending until it fires even
+     * after `operation` already won the race — on the (common) success path
+     * that stray timer holds the event loop open for the full timeout
+     * duration for no reason.
+     */
+    private raceWithTimeout;
     /**
      * Clean up old call records
      */

package/dist/mcp/mcpCircuitBreaker.js

@@ -42,8 +42,15 @@ export class MCPCircuitBreaker extends EventEmitter {
             minimumCallsBeforeCalculation: config.minimumCallsBeforeCalculation ?? 10,
             statisticsWindowSize: config.statisticsWindowSize ?? 300000, // 5 minutes
         };
-        // Clean up old call records periodically - now storing the timer reference
+        // Clean up old call records periodically - now storing the timer reference.
+        // Unref'd so a live breaker (the manager's Map is a module-level
+        // singleton, never torn down by a script that merely imports the SDK)
+        // doesn't block process exit on its own — destroy()/destroyAll() still
+        // clearInterval() it for callers that do explicit lifecycle management.
         this.cleanupTimer = setInterval(() => this.cleanupCallHistory(), 60000);
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
     }
     /**
      * Execute an operation with circuit breaker protection.
@@ -116,10 +123,7 @@ export class MCPCircuitBreaker extends EventEmitter {
                 resolvedFailureReason = reason || "Operation resolved a failure result";
             };
             // Execute operation with timeout
-            const result = await Promise.race([
-                operation(recordResolvedFailure),
-                this.timeoutPromise(this.config.operationTimeout),
-            ]);
+            const result = await this.raceWithTimeout(operation(recordResolvedFailure), this.config.operationTimeout);
             if (resolvedFailureReason !== undefined) {
                 // Same bookkeeping as a thrown error below, but the resolved value
                 // is still returned to the caller unchanged — no transport error is
@@ -257,14 +261,26 @@ export class MCPCircuitBreaker extends EventEmitter {
         });
     }
     /**
-     * Create a timeout promise
+     * Race an operation against a timeout, clearing the timer on either
+     * outcome. A bare `Promise.race([operation, timeoutPromise])` leaves the
+     * timeout's `setTimeout` handle ref'd and pending until it fires even
+     * after `operation` already won the race — on the (common) success path
+     * that stray timer holds the event loop open for the full timeout
+     * duration for no reason.
      */
-    timeoutPromise(timeout) {
-        return new Promise((_, reject) => {
-            setTimeout(() => {
+    async raceWithTimeout(operation, timeout) {
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
                 reject(new Error(`Operation timed out after ${timeout}ms`));
             }, timeout);
         });
+        try {
+            return await Promise.race([operation, timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     /**
      * Clean up old call records

package/dist/mcp/mcpClientFactory.d.ts

@@ -97,10 +97,15 @@ export declare class MCPClientFactory {
      */
     private static extractCapabilities;
     /**
-     * Create a timeout promise with AbortController support
-     * Provides consistent async timeout patterns across the factory
-     */
-    private static createTimeoutPromise;
+     * Race an operation against a timeout (with optional AbortController
+     * support), clearing the timer on every outcome. A bare
+     * `Promise.race([operation, timeoutPromise])` leaves the timeout's
+     * `setTimeout` handle ref'd and pending until it fires even after
+     * `operation` already won the race — on the (common) success path that
+     * stray timer holds the event loop open for the full timeout duration for
+     * no reason.
+     */
+    private static raceWithTimeout;
     /**
      * Close an MCP client and clean up resources
      */

package/dist/mcp/mcpClientFactory.js

@@ -213,10 +213,7 @@ export class MCPClientFactory {
                 capabilities: this.DEFAULT_CAPABILITIES,
             });
             // Connect with timeout
-            await Promise.race([
-                client.connect(transport),
-                this.createTimeoutPromise(timeout, `Client connection timeout for ${config.id}`),
-            ]);
+            await this.raceWithTimeout(client.connect(transport), timeout, `Client connection timeout for ${config.id}`);
             // Perform handshake to get server capabilities
             const serverCapabilities = await this.performHandshake(client, timeout);
             mcpLogger.debug(`[MCPClientFactory] Handshake completed for ${config.id}`, {
@@ -516,10 +513,7 @@ export class MCPClientFactory {
         try {
             // The MCP SDK handles the handshake automatically during connect()
             // We can request server info to verify the connection
-            const serverInfo = await Promise.race([
-                this.getServerInfo(client),
-                this.createTimeoutPromise(timeout, "Handshake timeout"),
-            ]);
+            const serverInfo = await this.raceWithTimeout(this.getServerInfo(client), timeout, "Handshake timeout");
             // Extract capabilities from server info
             return this.extractCapabilities(serverInfo);
         }
@@ -563,22 +557,39 @@ export class MCPClientFactory {
         };
     }
     /**
-     * Create a timeout promise with AbortController support
-     * Provides consistent async timeout patterns across the factory
+     * Race an operation against a timeout (with optional AbortController
+     * support), clearing the timer on every outcome. A bare
+     * `Promise.race([operation, timeoutPromise])` leaves the timeout's
+     * `setTimeout` handle ref'd and pending until it fires even after
+     * `operation` already won the race — on the (common) success path that
+     * stray timer holds the event loop open for the full timeout duration for
+     * no reason.
      */
-    static createTimeoutPromise(timeout, message, abortSignal) {
-        return new Promise((_, reject) => {
-            const timeoutId = setTimeout(() => {
+    static async raceWithTimeout(operation, timeout, message, abortSignal) {
+        let timeoutId;
+        let onAbort;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
                 reject(new Error(message));
             }, timeout);
             // Support abortion for better async cleanup
             if (abortSignal) {
-                abortSignal.addEventListener("abort", () => {
+                onAbort = () => {
                     clearTimeout(timeoutId);
                     reject(new Error(`Operation aborted: ${message}`));
-                });
+                };
+                abortSignal.addEventListener("abort", onAbort);
             }
         });
+        try {
+            return await Promise.race([operation, timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (abortSignal && onAbort) {
+                abortSignal.removeEventListener("abort", onAbort);
+            }
+        }
     }
     /**
      * Close an MCP client and clean up resources

package/dist/mcp/toolDiscoveryService.d.ts

@@ -103,9 +103,14 @@ export declare class ToolDiscoveryService extends EventEmitter {
      */
     private createToolKey;
     /**
-     * Create timeout promise
-     */
-    private createTimeoutPromise;
+     * Race an operation against a timeout, clearing the timer on either
+     * outcome. A bare `Promise.race([operation, timeoutPromise])` leaves the
+     * timeout's `setTimeout` handle ref'd and pending until it fires even
+     * after `operation` already won the race — on the (common) success path
+     * that stray timer holds the event loop open for the full timeout
+     * duration for no reason.
+     */
+    private raceWithTimeout;
     /**
      * Destroy the tool discovery service and clean up all resources
      * This method should be called when the service is no longer needed

package/dist/mcp/toolDiscoveryService.js

@@ -191,9 +191,7 @@ export class ToolDiscoveryService extends EventEmitter {
      */
     async performToolDiscovery(serverId, client, timeout) {
         // List tools from the MCP server
-        const listToolsPromise = client.listTools();
-        const timeoutPromise = this.createTimeoutPromise(timeout, "Tool discovery timeout");
-        const result = await Promise.race([listToolsPromise, timeoutPromise]);
+        const result = await this.raceWithTimeout(client.listTools(), timeout, "Tool discovery timeout");
         if (!result || !result.tools) {
             throw new Error("No tools returned from server");
         }
@@ -889,14 +887,26 @@ export class ToolDiscoveryService extends EventEmitter {
         return `${serverId}:${toolName}`;
     }
     /**
-     * Create timeout promise
+     * Race an operation against a timeout, clearing the timer on either
+     * outcome. A bare `Promise.race([operation, timeoutPromise])` leaves the
+     * timeout's `setTimeout` handle ref'd and pending until it fires even
+     * after `operation` already won the race — on the (common) success path
+     * that stray timer holds the event loop open for the full timeout
+     * duration for no reason.
      */
-    createTimeoutPromise(timeout, message) {
-        return new Promise((_, reject) => {
-            setTimeout(() => {
+    async raceWithTimeout(operation, timeout, message) {
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
                 reject(new Error(message));
             }, timeout);
         });
+        try {
+            return await Promise.race([operation, timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     /**
      * Destroy the tool discovery service and clean up all resources

package/dist/proxy/proxyTracer.d.ts

@@ -127,6 +127,15 @@ export declare function recordFallbackAttempt(attrs: {
     errorMessage?: string;
     durationMs: number;
 }): void;
+/** Reset leg-health state between tests. */
+export declare const __fallbackLegHealthTestHooks: {
+    threshold: number;
+    maxTrackedLegs: number;
+    trackedCount: () => number;
+    reset: () => void;
+    streakOf: (legKey: string) => number;
+    isReported: (legKey: string) => boolean;
+};
 export { ProxyTracer };
 /** Standard SERVER span covers every proxy door, including parsing and admission failures. */
 export declare function startProxyHttpTrace(metadata: RuntimeRequestMetadata, headers: Record<string, string>): {