@mcpmesh/sdk 2.4.0 → 2.5.0

package/dist/agent.d.ts

@@ -48,6 +48,13 @@ export declare function __getWorkerToolMap(): Map<string, (...args: unknown[]) =
  * - Dependency injection for tool functions
  */
 export declare class MeshAgent {
+    /**
+     * Hard cap on the signal-path shutdown sequence. Must exceed the
+     * dispatcher drain hard-cap (30s drain + 10s grace, see
+     * `stopDispatchers`) so a clean drain isn't cut short; the extra 5s
+     * covers pool/A2A teardown and the registry unregister.
+     */
+    private static readonly SIGNAL_SHUTDOWN_TIMEOUT_MS;
     private server;
     private config;
     private agentId;
@@ -63,6 +70,23 @@ export declare class MeshAgent {
     private started;
     private tracingEnabled;
     private shutdownRequested;
+    /**
+     * Memoized in-flight (or completed) teardown. `shutdown()` is
+     * idempotent: the first caller creates this promise and every later
+     * caller — user code, the signal handler, a second signal — awaits
+     * the SAME teardown instead of racing a concurrent one (double
+     * dispatcher drain, double napi `handle.shutdown()`).
+     */
+    private shutdownPromise;
+    /**
+     * This agent's own SIGINT/SIGTERM handler references, kept so
+     * shutdown() can `process.off` them. Without removal, sequential
+     * MeshAgent instances in one process (legal across async chunk
+     * boundaries) accumulate stale handlers whose memoized — already
+     * resolved — shutdown() would `process.exit(0)` immediately on the
+     * next signal, cutting short the LIVE agent's drain.
+     */
+    private signalHandlers;
     /**
      * Resolved dependencies: composite key -> proxy
      * Key format: "${toolName}:dep_${depIndex}" (e.g., "myTool:dep_0")
@@ -190,10 +214,15 @@ export declare class MeshAgent {
      * Install signal handlers for graceful shutdown.
      * Ensures agent unregisters from registry on SIGINT/SIGTERM.
      *
-     * Calls handle.shutdown() directly to trigger Rust core unregistration.
-     * This causes nextEvent() to return with a "shutdown" event, breaking
-     * the event loop cleanly. The shutdown is async but we don't await it
-     * in the signal handler - the event loop handles the exit.
+     * Runs the FULL `shutdown()` sequence (issue #1163 MED-2): claim
+     * dispatchers drain their in-flight jobs (concurrently, under one
+     * shared budget — see `stopDispatchers`), A2A clients / HTTP pool /
+     * tool-worker pool close, and `handle.shutdown()` unregisters from
+     * the registry (which also resolves the event loop's `nextEvent()`
+     * with a "shutdown" event, ending it cleanly).
+     *
+     * The whole sequence is bounded by a force-exit timer so a hang in
+     * any cleanup step cannot wedge the process past its SIGTERM grace.
      */
     private installSignalHandlers;
     /**
@@ -202,6 +231,15 @@ export declare class MeshAgent {
     private startHeartbeat;
     /**
      * Run the event loop to handle mesh events.
+     *
+     * Resilience (issue #1163 MED-1): the loop must outlive individual
+     * failures. A throw from an event handler (e.g. a malformed event
+     * hitting a non-null assertion) is logged and the loop continues; a
+     * `nextEvent()` rejection (e.g. a transient napi failure) backs off
+     * exponentially (capped) and retries. Only the "shutdown" event — or
+     * the handle being torn down — exits the loop. Previously a single
+     * throw broke the loop permanently, freezing dependency-topology
+     * updates for the process lifetime while the agent kept serving.
      */
     private runEventLoop;
     /**
@@ -237,6 +275,16 @@ export declare class MeshAgent {
      * Get all resolved dependencies.
      */
     getAllDependencies(): Map<string, McpMeshTool>;
+    /**
+     * Inject a mock/fake proxy for a capability (the documented mock
+     * contract — see `meshctl man testing --typescript`).
+     *
+     * Fills the dependency slot of every registered tool that declares the
+     * capability and marks those slots resolved with the settle state, so
+     * the settling-window grace (#1193) never waits on a caller-supplied
+     * dependency.
+     */
+    setMockDependency(capability: string, mock: McpMeshTool): void;
     /**
      * Get the agent handle for advanced operations.
      */
@@ -251,8 +299,20 @@ export declare class MeshAgent {
     getAgentId(): string;
     /**
      * Shutdown the agent gracefully.
+     *
+     * Idempotent and re-entrant: the first call runs the teardown; every
+     * later call (user code, the signal handler, a double signal) returns
+     * the SAME promise — later calls' `opts` are ignored. The memo is
+     * never cleared: shutdown is terminal, and re-running a half-torn-down
+     * cleanup after a failure would be worse than surfacing the original
+     * rejection to every caller.
      */
-    shutdown(): Promise<void>;
+    shutdown(opts?: {
+        /** Shared in-flight-handler drain window for claim dispatchers. */
+        drainTimeoutMs?: number;
+        /** Headroom on top of the drain window before drains are abandoned. */
+        drainGraceMs?: number;
+    }): Promise<void>;
 }
 /**
  * Create a MeshAgent wrapping a FastMCP server.

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,EAGL,KAAK,aAAa,EAInB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,WAAW,EAEX,WAAW,EAEX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AA6CpB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,eAAuC,CAAC;AAiBrE;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAEjF;AAqBD;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAoC;IACjD;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAAkC;IAC5D,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,UAAU,CAAC,CAA8B;IACjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,iBAAiB,CAAS;IAElC;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY,CAAuC;IAK3D,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa,CAMP;IACd;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAAyB;IAElD;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAqC;IAExD;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,aAAa,CAAK;gBAEd,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW;IAqChD;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI;IAomBvD;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAyC/C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,sBAAsB;IAQ9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAS9B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAyJjC;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IA4B/B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAiC7B;;OAEG;YACW,cAAc;IAgN5B;;OAEG;YACW,YAAY;IA6G1B;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;IA6CjC;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAiCnC;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAYrD;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAI1E;;OAEG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC;IAI9C;;OAEG;IACH,SAAS,IAAI,aAAa,GAAG,IAAI;IAIjC;;OAEG;IACH,SAAS,IAAI,mBAAmB;IAIhC;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA2ChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -11,12 +11,13 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { isMainThread } from "node:worker_threads";
 import { startAgent, } from "@mcpmesh/core";
-import { resolveConfig, generateAgentIdSuffix, findAvailablePort } from "./config.js";
+import { resolveConfig, generateAgentIdSuffix, findAvailablePort, resolveStartupBindPort, MAX_CONSECUTIVE_NEXT_EVENT_FAILURES, NEXT_EVENT_BACKOFF_CAP_MS, } from "./config.js";
 import { enrichSchemaWithMediaTypes } from "./media-param.js";
 import { createProxy, normalizeDependency, runWithTraceContext, runWithPropagatedHeaders, PROXY_DISPATCH_META } from "./proxy.js";
 import { readJobHeaders, runWithJobContext, makeJobController, spliceJobController, } from "./inbound-job-dispatch.js";
 import { MeshJobSubmitter } from "./mesh-job-submitter.js";
-import { ClaimDispatcher } from "./claim-dispatcher.js";
+import { getSettleState } from "./settle.js";
+import { ClaimDispatcher, stopDispatchers, } from "./claim-dispatcher.js";
 import { registerJobHelperTools } from "./jobs-helper-tools.js";
 import { registerCancelRoute } from "./jobs-cancel-route.js";
 import { clusterStrictEnabled, normalizeSchemaWithPolicy, } from "./schema-normalize.js";
@@ -68,17 +69,35 @@ const _workerToolMap = new Map();
 export function __getWorkerToolMap() {
     return _workerToolMap;
 }
-// Internal: pending agent for auto-start
+// Internal: pending agent for auto-start. The slot holds at most one
+// agent awaiting its auto-start tick; it is consumed (cleared) when the
+// scheduled nextTick fires.
 let pendingAgent = null;
 let autoStartScheduled = false;
+// Issue #1163 LOW-6 guard: name of the agent constructed in the CURRENT
+// synchronous chunk. Two constructions in one chunk meant the second
+// silently overwrote `pendingAgent` before the auto-start tick fired —
+// the first agent never started and nobody noticed. The constructor now
+// throws while this guard is set. The guard auto-releases on the first
+// microtask: in real Node the auto-start nextTick drains BEFORE any
+// microtask continuation, so the guard window fully covers the
+// pre-consumption danger zone, while sequential constructions across
+// async boundaries (e.g. one agent per test in a harness) stay allowed.
+let constructionGuardName = null;
 // Schedule auto-start after module loading completes
 function scheduleAutoStart() {
     if (autoStartScheduled)
         return;
     autoStartScheduled = true;
     process.nextTick(() => {
-        if (pendingAgent) {
-            pendingAgent._autoStart().catch((err) => {
+        // Consume the slot and re-arm the scheduler BEFORE starting, so a
+        // later (post-start) construction gets its own auto-start tick
+        // instead of being silently dropped.
+        const agent = pendingAgent;
+        pendingAgent = null;
+        autoStartScheduled = false;
+        if (agent) {
+            agent._autoStart().catch((err) => {
                 console.error("MCP Mesh auto-start failed:", err);
                 process.exit(1);
             });
@@ -95,6 +114,13 @@ function scheduleAutoStart() {
  * - Dependency injection for tool functions
  */
 export class MeshAgent {
+    /**
+     * Hard cap on the signal-path shutdown sequence. Must exceed the
+     * dispatcher drain hard-cap (30s drain + 10s grace, see
+     * `stopDispatchers`) so a clean drain isn't cut short; the extra 5s
+     * covers pool/A2A teardown and the registry unregister.
+     */
+    static SIGNAL_SHUTDOWN_TIMEOUT_MS = 45_000;
     server;
     config;
     agentId;
@@ -110,6 +136,23 @@ export class MeshAgent {
     started = false;
     tracingEnabled = false;
     shutdownRequested = false;
+    /**
+     * Memoized in-flight (or completed) teardown. `shutdown()` is
+     * idempotent: the first caller creates this promise and every later
+     * caller — user code, the signal handler, a second signal — awaits
+     * the SAME teardown instead of racing a concurrent one (double
+     * dispatcher drain, double napi `handle.shutdown()`).
+     */
+    shutdownPromise = null;
+    /**
+     * This agent's own SIGINT/SIGTERM handler references, kept so
+     * shutdown() can `process.off` them. Without removal, sequential
+     * MeshAgent instances in one process (legal across async chunk
+     * boundaries) accumulate stale handlers whose memoized — already
+     * resolved — shutdown() would `process.exit(0)` immediately on the
+     * next signal, cutting short the LIVE agent's drain.
+     */
+    signalHandlers = null;
     /**
      * Resolved dependencies: composite key -> proxy
      * Key format: "${toolName}:dep_${depIndex}" (e.g., "myTool:dep_0")
@@ -186,7 +229,22 @@ export class MeshAgent {
         this.config = resolveConfig(config);
         // Generate unique agent ID with suffix (e.g., "calculator-a1b2c3d4")
         this.agentId = `${this.config.name}-${generateAgentIdSuffix()}`;
-        // Register as pending agent for auto-start
+        // Register as pending agent for auto-start. Throw if another agent
+        // was already constructed in this synchronous chunk — the previous
+        // behavior overwrote the slot and the earlier agent silently never
+        // started (issue #1163 LOW-6). Only one MeshAgent per process is
+        // supported (it owns the FastMCP HTTP server, registry heartbeat,
+        // and process-wide signal handlers).
+        if (constructionGuardName !== null) {
+            throw new Error(`Only one MeshAgent may be constructed per process: agent ` +
+                `'${constructionGuardName}' is already pending auto-start. ` +
+                `Register all tools on a single MeshAgent instead of constructing ` +
+                `'${this.config.name}' as a second agent.`);
+        }
+        constructionGuardName = this.config.name;
+        queueMicrotask(() => {
+            constructionGuardName = null;
+        });
         pendingAgent = this;
         scheduleAutoStart();
     }
@@ -373,6 +431,16 @@ export class MeshAgent {
         // Normalize dependencies
         const normalizedDeps = (def.dependencies ?? []).map(normalizeDependency);
         const depEndpoints = normalizedDeps.map((d) => d.capability);
+        // Settling-window grace (#1193): declare this tool's proxy deps with the
+        // process-wide settle state so the agent-level "all declared deps
+        // resolved" latch can flip eagerly. The MeshJob slot is excluded — its
+        // submitter is constructed locally, not resolved by an event.
+        const settleState = getSettleState();
+        normalizedDeps.forEach((_dep, depIndex) => {
+            if (depIndex !== def.meshJobDepIndex) {
+                settleState.registerDeclared(`${toolName}:dep_${depIndex}`);
+            }
+        });
         // Capture for closures — these reads must be live at invocation
         // time (e.g. registryUrl/agentId aren't set yet at addTool time).
         const isTaskTool = def.task === true;
@@ -403,6 +471,24 @@ export class MeshAgent {
         }
         // Create wrapper that injects dependencies positionally and handles tracing
         const wrappedExecute = async (args) => {
+            // Settling-window grace (#1193): while the agent is still settling,
+            // wait — bounded by the remaining settle budget — for any declared
+            // dep this call would inject that is still unresolved. No-op (single
+            // latch check) once settled; the deps array below is built AFTER the
+            // wait so it re-reads the resolution state.
+            if (normalizedDeps.length > 0 && !settleState.isSettled()) {
+                const pendingSettle = [];
+                normalizedDeps.forEach((dep, depIndex) => {
+                    const depKey = `${toolName}:dep_${depIndex}`;
+                    if (depIndex !== meshJobDepIndex &&
+                        !this.resolvedDeps.has(depKey)) {
+                        pendingSettle.push({ depKey, capability: dep.capability });
+                    }
+                });
+                if (pendingSettle.length > 0) {
+                    await settleState.awaitPending(pendingSettle);
+                }
+            }
             // Build positional deps array using composite keys (toolName:dep_index)
             // Phase 1 MeshJob substrate (consumer-side): if meshJobDepIndex is
             // set, swap the McpMeshTool proxy at that slot for a
@@ -651,6 +737,22 @@ export class MeshAgent {
         if (isTaskTool) {
             const capability = def.capability ?? toolName;
             const handler = async (payload, controller) => {
+                // Settling-window grace (#1193): claim dispatch gets the same
+                // bounded wait as the inbound HTTP path — a claim arriving during
+                // the settling window would otherwise see null deps.
+                if (normalizedDeps.length > 0 && !settleState.isSettled()) {
+                    const pendingSettle = [];
+                    normalizedDeps.forEach((dep, depIndex) => {
+                        const depKey = `${toolName}:dep_${depIndex}`;
+                        if (depIndex !== meshJobDepIndex &&
+                            !this.resolvedDeps.has(depKey)) {
+                            pendingSettle.push({ depKey, capability: dep.capability });
+                        }
+                    });
+                    if (pendingSettle.length > 0) {
+                        await settleState.awaitPending(pendingSettle);
+                    }
+                }
                 const liveDeps = normalizedDeps.map((dep, depIndex) => {
                     if (depIndex === meshJobDepIndex) {
                         return new MeshJobSubmitter(dep.capability, this.agentId, this.config.registryUrl);
@@ -840,11 +942,17 @@ export class MeshAgent {
         // Auto-detect template base path from agent's package.json location
         // This ensures file:// templates resolve correctly regardless of cwd
         findAndSetBasePath();
-        // Handle httpPort=0: auto-assign an available port
-        if (this.config.httpPort === 0) {
-            const assignedPort = await findAvailablePort();
-            this.config = { ...this.config, httpPort: assignedPort };
-            console.log(`Auto-assigned port ${assignedPort} for agent`);
+        // Resolve the bind port BEFORE tracing/server/heartbeat so every
+        // downstream consumer sees the port we will actually bind (issue
+        // #1194: a conflict falls back to an OS-assigned port with a
+        // prominent warning — see resolveStartupBindPort). The heartbeat
+        // reads `this.config.httpPort`, so registration carries the ACTUAL
+        // port instead of a phantom endpoint.
+        {
+            const resolvedPort = await resolveStartupBindPort(this.config.httpPort, "agent");
+            if (resolvedPort !== this.config.httpPort) {
+                this.config = { ...this.config, httpPort: resolvedPort };
+            }
         }
         console.log(`Starting MCP Mesh agent: ${this.agentId}`);
         // Prepare TLS credentials (fetches from Vault if configured)
@@ -1035,38 +1143,59 @@ export class MeshAgent {
      * Install signal handlers for graceful shutdown.
      * Ensures agent unregisters from registry on SIGINT/SIGTERM.
      *
-     * Calls handle.shutdown() directly to trigger Rust core unregistration.
-     * This causes nextEvent() to return with a "shutdown" event, breaking
-     * the event loop cleanly. The shutdown is async but we don't await it
-     * in the signal handler - the event loop handles the exit.
+     * Runs the FULL `shutdown()` sequence (issue #1163 MED-2): claim
+     * dispatchers drain their in-flight jobs (concurrently, under one
+     * shared budget — see `stopDispatchers`), A2A clients / HTTP pool /
+     * tool-worker pool close, and `handle.shutdown()` unregisters from
+     * the registry (which also resolves the event loop's `nextEvent()`
+     * with a "shutdown" event, ending it cleanly).
+     *
+     * The whole sequence is bounded by a force-exit timer so a hang in
+     * any cleanup step cannot wedge the process past its SIGTERM grace.
      */
     installSignalHandlers() {
+        // Dedupe repeated signals locally. This must NOT key off
+        // `shutdownRequested` (set by shutdown() itself): a signal arriving
+        // while a user-initiated shutdown() is draining must still arm the
+        // force-exit timer and exit the process when that same (memoized)
+        // shutdown completes.
+        let signalHandled = false;
         const shutdownHandler = (signal) => {
-            if (this.shutdownRequested)
+            if (signalHandled)
                 return;
-            this.shutdownRequested = true;
+            signalHandled = true;
             console.log(`\nReceived ${signal}, shutting down agent ${this.agentId}...`);
-            // Close HTTPS proxy if it exists
-            if (this.httpsProxy) {
-                this.httpsProxy.close();
-            }
-            // Call shutdown directly - this triggers Rust core to unregister
-            // and send a shutdown event that breaks the event loop
-            if (this.handle) {
-                this.handle.shutdown().then(() => {
-                    console.log(`Agent ${this.agentId} unregistered from registry`);
-                    process.exit(0);
-                }).catch((err) => {
-                    console.error("Error during shutdown:", err);
-                    process.exit(1);
-                });
-            }
-            else {
+            // Bounded overall shutdown: the dispatcher drain phase is already
+            // hard-capped (30s drain + 10s grace shared across dispatchers);
+            // this timer covers everything else (pool/A2A close, registry
+            // unregister) so a hang anywhere cannot block exit forever.
+            //
+            // Deliberately ref'd (no unref): both completion paths below
+            // clearTimeout and process.exit synchronously, so the timer never
+            // delays a successful exit — but it must keep a wedged shutdown's
+            // otherwise-empty event loop alive long enough to emit the loud
+            // exit(1) diagnostic instead of silently exiting 0.
+            const forceExitTimer = setTimeout(() => {
+                console.error(`Shutdown did not complete within ${MeshAgent.SIGNAL_SHUTDOWN_TIMEOUT_MS}ms; forcing exit`);
+                process.exit(1);
+            }, MeshAgent.SIGNAL_SHUTDOWN_TIMEOUT_MS);
+            this.shutdown().then(() => {
+                clearTimeout(forceExitTimer);
+                console.log(`Agent ${this.agentId} shut down cleanly`);
                 process.exit(0);
-            }
+            }).catch((err) => {
+                clearTimeout(forceExitTimer);
+                console.error("Error during shutdown:", err);
+                process.exit(1);
+            });
         };
-        process.on("SIGINT", () => shutdownHandler("SIGINT"));
-        process.on("SIGTERM", () => shutdownHandler("SIGTERM"));
+        // Keep named references so shutdown() can remove exactly these
+        // listeners (anonymous arrows can't be process.off'd).
+        const sigint = () => shutdownHandler("SIGINT");
+        const sigterm = () => shutdownHandler("SIGTERM");
+        this.signalHandlers = { sigint, sigterm };
+        process.on("SIGINT", sigint);
+        process.on("SIGTERM", sigterm);
     }
     /**
      * Start the Rust core heartbeat loop.
@@ -1242,13 +1371,56 @@ export class MeshAgent {
     }
     /**
      * Run the event loop to handle mesh events.
+     *
+     * Resilience (issue #1163 MED-1): the loop must outlive individual
+     * failures. A throw from an event handler (e.g. a malformed event
+     * hitting a non-null assertion) is logged and the loop continues; a
+     * `nextEvent()` rejection (e.g. a transient napi failure) backs off
+     * exponentially (capped) and retries. Only the "shutdown" event — or
+     * the handle being torn down — exits the loop. Previously a single
+     * throw broke the loop permanently, freezing dependency-topology
+     * updates for the process lifetime while the agent kept serving.
      */
     async runEventLoop() {
         if (!this.handle)
             return;
+        let consecutiveNextEventFailures = 0;
         while (true) {
+            // Handle is nulled by shutdown(); exit cleanly instead of
+            // spinning on a dead reference.
+            if (!this.handle) {
+                console.log("Event loop: handle closed, exiting");
+                return;
+            }
+            let event;
+            try {
+                event = await this.handle.nextEvent();
+                consecutiveNextEventFailures = 0;
+            }
+            catch (err) {
+                // Explicit shutdown() racing a failing nextEvent(): exit
+                // promptly instead of burning more backoff cycles.
+                if (!this.handle || this.shutdownRequested) {
+                    console.log("Event loop: shutdown requested, exiting");
+                    return;
+                }
+                consecutiveNextEventFailures++;
+                // Ceiling (~60s of continuous failure — see the constant's doc
+                // in config.ts): a permanently broken handle must not retry
+                // forever, keeping the process alive via the backoff timer.
+                if (consecutiveNextEventFailures >= MAX_CONSECUTIVE_NEXT_EVENT_FAILURES) {
+                    console.error(`Event loop: terminating after ${consecutiveNextEventFailures} ` +
+                        `consecutive nextEvent() failures; dependency topology is ` +
+                        `frozen for the remainder of the process:`, err);
+                    return;
+                }
+                const backoffMs = Math.min(100 * 2 ** (consecutiveNextEventFailures - 1), NEXT_EVENT_BACKOFF_CAP_MS);
+                console.error(`Event loop: nextEvent() failed (consecutive=${consecutiveNextEventFailures}), ` +
+                    `retrying in ${backoffMs}ms:`, err);
+                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+                continue;
+            }
             try {
-                const event = await this.handle.nextEvent();
                 switch (event.eventType) {
                     case "agent_registered":
                         console.log(`Agent registered with ID: ${event.agentId}`);
@@ -1314,8 +1486,10 @@ export class MeshAgent {
                 }
             }
             catch (err) {
-                console.error("Event loop error:", err);
-                break;
+                // Per-event isolation: a bad event (or a bug in one handler)
+                // must not kill dependency-event processing for the process
+                // lifetime. Log and keep consuming events.
+                console.error(`Event loop: error handling event '${event.eventType}':`, err);
             }
         }
     }
@@ -1335,6 +1509,10 @@ export class MeshAgent {
             const depKey = `${requestingFunction}:dep_${depIndex}`;
             const proxy = createProxy(endpoint, capability, functionName, kwargs);
             this.resolvedDeps.set(depKey, proxy);
+            // Settling-window grace (#1193): wake any settling call waiting on
+            // this dependency AFTER the proxy is stored so the woken call
+            // re-reads a real proxy.
+            getSettleState().markResolved(depKey);
             console.log(`Dependency available: ${capability} at ${endpoint} (tool: ${requestingFunction}, index: ${depIndex}, agent: ${agentId})`);
             return;
         }
@@ -1350,6 +1528,7 @@ export class MeshAgent {
                     const depKey = `${toolName}:dep_${idx}`;
                     const proxy = createProxy(endpoint, capability, functionName, kwargs);
                     this.resolvedDeps.set(depKey, proxy);
+                    getSettleState().markResolved(depKey);
                     matchCount++;
                 }
             });
@@ -1417,6 +1596,30 @@ export class MeshAgent {
     getAllDependencies() {
         return new Map(this.resolvedDeps);
     }
+    /**
+     * Inject a mock/fake proxy for a capability (the documented mock
+     * contract — see `meshctl man testing --typescript`).
+     *
+     * Fills the dependency slot of every registered tool that declares the
+     * capability and marks those slots resolved with the settle state, so
+     * the settling-window grace (#1193) never waits on a caller-supplied
+     * dependency.
+     */
+    setMockDependency(capability, mock) {
+        for (const [toolName, meta] of this.tools.entries()) {
+            if (!meta.dependencies)
+                continue;
+            meta.dependencies.forEach((dep, depIndex) => {
+                if (dep.capability === capability) {
+                    const depKey = `${toolName}:dep_${depIndex}`;
+                    this.resolvedDeps.set(depKey, mock);
+                    // A caller-supplied slot needs no resolution event — count it
+                    // as resolved so settling calls never wait on it.
+                    getSettleState().markResolved(depKey);
+                }
+            });
+        }
+    }
     /**
      * Get the agent handle for advanced operations.
      */
@@ -1437,50 +1640,82 @@ export class MeshAgent {
     }
     /**
      * Shutdown the agent gracefully.
+     *
+     * Idempotent and re-entrant: the first call runs the teardown; every
+     * later call (user code, the signal handler, a double signal) returns
+     * the SAME promise — later calls' `opts` are ignored. The memo is
+     * never cleared: shutdown is terminal, and re-running a half-torn-down
+     * cleanup after a failure would be worse than surfacing the original
+     * rejection to every caller.
      */
-    async shutdown() {
-        // Phase 1 MeshJob substrate: stop claim dispatchers first so
-        // they don't pull a fresh job mid-shutdown.
-        for (const d of this._claimDispatchers) {
+    shutdown(opts) {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.shutdownRequested = true;
+        this.shutdownPromise = (async () => {
+            // Phase 1 MeshJob substrate: stop claim dispatchers first so they
+            // don't pull a fresh job mid-shutdown. Issue #1173: all dispatchers
+            // drain CONCURRENTLY under one shared, hard-capped budget — never
+            // N×30s sequential — and a hanging drain is abandoned with a
+            // warning so the registry unregister below always runs.
+            await stopDispatchers(this._claimDispatchers, opts?.drainTimeoutMs, opts?.drainGraceMs);
+            this._claimDispatchers = [];
+            // Issue #917: mark all cached A2AClients closed so any in-flight
+            // user code raises cleanly instead of reusing a torn-down instance.
+            // Close in parallel so one slow client doesn't block the others —
+            // the undici Agent pool is shared via closeHttpPool() below.
+            const closePromises = Array.from(this._a2aClients.values()).map((client) => client.close().catch((err) => {
+                console.warn("[mesh-a2a] Error closing A2AClient:", err);
+                return null;
+            }));
+            await Promise.allSettled(closePromises);
+            this._a2aClients.clear();
             try {
-                await d.stop();
+                await closeHttpPool();
             }
             catch (err) {
-                console.warn(`[mesh-jobs] error stopping claim dispatcher:`, err);
+                console.warn("Error closing HTTP pool:", err);
             }
-        }
-        this._claimDispatchers = [];
-        // Issue #917: mark all cached A2AClients closed so any in-flight
-        // user code raises cleanly instead of reusing a torn-down instance.
-        // Close in parallel so one slow client doesn't block the others —
-        // the undici Agent pool is shared via closeHttpPool() below.
-        const closePromises = Array.from(this._a2aClients.values()).map((client) => client.close().catch((err) => {
-            console.warn("[mesh-a2a] Error closing A2AClient:", err);
-            return null;
-        }));
-        await Promise.allSettled(closePromises);
-        this._a2aClients.clear();
-        try {
-            await closeHttpPool();
-        }
-        catch (err) {
-            console.warn("Error closing HTTP pool:", err);
-        }
-        try {
-            await closePool();
-        }
-        catch (err) {
-            console.warn("Error closing tool worker pool:", err);
-        }
-        if (this.httpsProxy) {
-            this.httpsProxy.close();
-            this.httpsProxy = undefined;
-        }
-        if (this.handle) {
-            await this.handle.shutdown();
-            this.handle = null;
-        }
-        cleanupTls();
+            try {
+                await closePool();
+            }
+            catch (err) {
+                console.warn("Error closing tool worker pool:", err);
+            }
+            if (this.httpsProxy) {
+                // Await the close callback so the TLS listener's port is
+                // actually released by the time shutdown() resolves (mirrors
+                // MeshExpress.shutdown()'s server.close handling).
+                const proxy = this.httpsProxy;
+                this.httpsProxy = undefined;
+                await new Promise((resolve) => {
+                    proxy.close((err) => {
+                        if (err)
+                            console.warn("Error closing HTTPS proxy:", err);
+                        resolve();
+                    });
+                });
+            }
+            // Registry unregister runs regardless of how the cleanup steps above
+            // fared — every prior step is guarded so a drain/close failure can't
+            // leave a stale registration behind.
+            if (this.handle) {
+                await this.handle.shutdown();
+                this.handle = null;
+            }
+            cleanupTls();
+            // Remove this agent's own signal listeners LAST: during the drain
+            // above a signal must still reach the handler (it arms the
+            // force-exit timer and exits when this memoized teardown settles).
+            // Leaving them installed would let a LATER agent's signal hit this
+            // already-resolved shutdown() and process.exit(0) prematurely.
+            if (this.signalHandlers) {
+                process.off("SIGINT", this.signalHandlers.sigint);
+                process.off("SIGTERM", this.signalHandlers.sigterm);
+                this.signalHandlers = null;
+            }
+        })();
+        return this.shutdownPromise;
     }
 }
 /**