toolfunnel 0.7.1 → 0.8.0

package/src/mcp/http-transport.js

@@ -72,7 +72,7 @@ const SSE_KEEPALIVE_MS = 25000;
 // Hard cap on a POSTed JSON-RPC body so a pathological/huge request can't exhaust memory. A
 // JSON-RPC tools/call payload is tiny; 4 MiB is generous headroom. Over the cap -> -32700.
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
-// Hard cap on JSON-RPC batch members (0.7.0). MAX_BODY_BYTES alone is no bound on WORK: a
+// Hard cap on JSON-RPC batch members. MAX_BODY_BYTES alone is no bound on WORK: a
 // tools/call member is ~100 bytes, so 4 MiB buys tens of thousands of gated invocations - each
 // spawning hook children and a tool child - executed serially while the socket is held. 64 is well
 // past any real client's batching and far short of a denial of service.
@@ -137,6 +137,12 @@ function defaultBuildFactory() {
   return require('./server').buildProtocol();
 }
 
+/** A host as it appears in a URL: a literal IPv6 address is bracketed (`[::1]`), anything else verbatim. */
+function urlHost(h) {
+  const v = String(h == null ? '' : h);
+  return v.includes(':') && !v.startsWith('[') ? '[' + v + ']' : v;
+}
+
 /**
  * Is the Host header loopback? We bind 127.0.0.1 only, but a forwarded/rebound request could still
  * arrive with a non-loopback Host. Defence-in-depth: reject anything whose host part is not a
@@ -393,7 +399,7 @@ function createHttpMcpServer(opts = {}) {
 
   /** The advertised base URL once bound (null before start / after stop). */
   function currentUrl() {
-    return boundPort == null ? null : `http://${host}:${boundPort}`;
+    return boundPort == null ? null : `http://${urlHost(host)}:${boundPort}`;
   }
 
   // ── SSE plumbing ──────────────────────────────────────────────────────────────────────────
@@ -405,6 +411,13 @@ function createHttpMcpServer(opts = {}) {
    * server stop) the client is deregistered and its timer cleared.
    */
   function openSse(req, res) {
+    // Same ceiling as the modern listen streams: every open stream is a registered response plus
+    // a keep-alive timer for the life of the socket, and nothing bounded the legacy channel - a
+    // client opening streams it never closed grew the host without limit. A GET has no JSON-RPC
+    // id, so the refusal is a plain JSON body, not an error envelope.
+    if (sseClients.size >= MODERN_LISTENERS_MAX) {
+      return sendJson(res, 503, { error: 'sse stream limit reached (' + MODERN_LISTENERS_MAX + ') - close an existing stream first' });
+    }
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-store',
@@ -487,9 +500,9 @@ function createHttpMcpServer(opts = {}) {
     // At capacity -> refuse the NEW stream with a clear error BEFORE any SSE bytes are written;
     // existing streams are never evicted (they may carry subscriptions the client relies on).
     //
-    // ORDER MATTERS (0.7.0): this check used to sit AFTER subscribeResources below, and the 503
-    // return path registers no cleanup - so a refused listen took refcounts it never released.
-    // Each leaked ref pinned its URI above zero (no resources/unsubscribe ever sent) and kept it
+    // ORDER MATTERS: this check must sit BEFORE subscribeResources below, because the 503
+    // return path registers no cleanup - a refused listen would take refcounts it never releases.
+    // Each leaked ref would pin its URI above zero (no resources/unsubscribe ever sent) and keep it
     // in the replay set, re-subscribed on every future upstream reconnect, unboundedly.
     if (modernListeners.size >= MODERN_LISTENERS_MAX) {
       return sendJson(res, 503, makeErrorWithId(subId, ERR.INTERNAL,
@@ -539,7 +552,7 @@ function createHttpMcpServer(opts = {}) {
       clearInterval(keepAlive);
       modernListeners.delete(entry);
       // 5.4: the stream WAS the subscription - closing it releases the listen-owned resource
-      // URIs (this cleanup previously released nothing: leak site #2). _released guards the
+      // URIs. _released guards the
       // up-to-four close/error events that all route here.
       if (entry._released !== true && entry.agreed && Array.isArray(entry.agreed.resourceSubscriptions)) {
         entry._released = true;
@@ -739,7 +752,7 @@ function createHttpMcpServer(opts = {}) {
       raw = await readBody(req);
     } catch (err) {
       // Oversized / aborted body -> the SAME flush-then-close -32700 as the Content-Length pre-check
-      // (readBody no longer destroys the request, so the reply can actually reach the client; a
+      // (readBody does not destroy the request, so the reply can actually reach the client; a
       // genuinely-dead socket is fine too - sendJsonAndClose's writes are defensively wrapped).
       log('POST /mcp body read failed:', (err && err.message) || String(err));
       return sendJsonAndClose(req, res, 200, makeError(ERR.PARSE, 'Parse error: ' + ((err && err.message) || 'bad body')));
@@ -765,16 +778,16 @@ function createHttpMcpServer(opts = {}) {
       if (hv === undefined || hv === '2025-03-26') {
         // A MODERN-shaped member cannot legally travel in a batch: batching exists ONLY in
         // 2025-03-26, which predates the modern era entirely. Refusing here closes an era-mixing
-        // hole (0.7.0): this branch runs BEFORE bodyIsModern below, so a modern body wrapped in a
-        // one-element array used to skip validateModernHeaders, the Mcp-Param cross-check and the
-        // disconnect-cancel accounting, and still be SERVED with full modern semantics because
+        // hole: this branch runs BEFORE bodyIsModern below, so a modern body wrapped in a
+        // one-element array would otherwise skip validateModernHeaders, the Mcp-Param cross-check and
+        // the disconnect-cancel accounting, and still be SERVED with full modern semantics because
         // handleMessage re-detects the era from the body.
         if (msg.some((m) => modern.isModernRequest(m))) {
           return sendJson(res, 400, makeError(ERR.INVALID_REQUEST,
             'modern-era messages cannot be batched - JSON-RPC batching is 2025-03-26 only; send each modern request as its own POST'));
         }
         // A batch is executed member-by-member with a gated tool call possible in every slot, so an
-        // uncapped array is one POST buying unbounded sequential execution (0.7.0).
+        // uncapped array is one POST buying unbounded sequential execution.
         if (msg.length > MAX_BATCH_MEMBERS) {
           return sendJson(res, 400, makeError(ERR.INVALID_REQUEST,
             `batch too large (${msg.length} members, max ${MAX_BATCH_MEMBERS}) - split it`));
@@ -889,13 +902,43 @@ function createHttpMcpServer(opts = {}) {
       });
     }
 
+    // Per-request progress. A single request that carries a progressToken and accepts
+    // text/event-stream gets an SSE answer the moment its FIRST beat arrives: its own progress (its
+    // own token - the aggregator scopes tokens per call), then its result, then the end. Streamable
+    // HTTP allows exactly this ("MAY send ... notifications before sending the JSON-RPC response.
+    // These messages SHOULD relate to the originating client request"), and it is the only place
+    // progress may go: the shared GET stream would hand one caller's beats to every listener. No beat
+    // arrives -> the same JSON answer (status mapping included) as before.
+    const ptok = msg && msg.params && msg.params._meta && msg.params._meta.progressToken;
+    const wantsStream = !!(msg && !Array.isArray(msg) && msg.id !== undefined && msg.id !== null &&
+      ((typeof ptok === 'string' && ptok.length) || Number.isInteger(ptok)) &&
+      /text\/event-stream/i.test(String(req.headers.accept || '')));
+    let streaming = false;
+    const progress = wantsStream ? (params) => {
+      if (modernDisconnected || res.writableEnded || res.destroyed) return;
+      try {
+        if (!streaming) {
+          streaming = true;
+          res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+        }
+        res.write('data: ' + JSON.stringify({ jsonrpc: JSONRPC, method: 'notifications/progress', params }) + '\n\n');
+      } catch (_e) { /* a dead socket: the result path below meets it too */ }
+    } : undefined;
+
     let response;
     try {
-      response = await handleMessage(build, msg);
+      response = await handleMessage(build, msg, undefined, { progress });
     } catch (err) {
       // handleMessage is contracted never to throw, but the transport must survive even if a
       // wiring bug breaks that contract - a single bad request can never crash the host.
       log('handleMessage threw (should not):', (err && err.stack) || String(err));
+      if (streaming) {
+        try {
+          res.write('data: ' + JSON.stringify(makeError(ERR.INTERNAL, 'Internal error', (err && err.message) || String(err))) + '\n\n');
+          res.end();
+        } catch (_e) { /* ignore */ }
+        return;
+      }
       return sendJson(res, 200, makeError(ERR.INTERNAL, 'Internal error', (err && err.message) || String(err)));
     }
 
@@ -903,6 +946,15 @@ function createHttpMcpServer(opts = {}) {
     // returning here keeps the contract explicit and the counter honest.
     if (modernDisconnected) return;
 
+    if (streaming) {
+      // Streaming began (status 200 already sent): the result - or the JSON-RPC error - is the
+      // stream's last event, then the stream ends ("After the JSON-RPC response has been sent, the
+      // server SHOULD terminate the SSE stream").
+      try { if (response != null) res.write('data: ' + JSON.stringify(response) + '\n\n'); } catch (_e) { /* ignore */ }
+      try { res.end(); } catch (_e) { /* ignore */ }
+      return;
+    }
+
     // A notification (no reply) -> 202 Accepted, no body. A request -> 200 with the JSON-RPC result.
     if (response == null) {
       res.writeHead(202, { 'Content-Length': 0, 'Cache-Control': 'no-store' });
@@ -1058,10 +1110,9 @@ function createHttpMcpServer(opts = {}) {
       // alias (the older HTTP+SSE shape, deprecated but still supported). Both routes
       // hand off to the same openSse() - the loopback/auth guard above already gated the request.
       if (method === 'GET' && (pathName === '/mcp' || pathName === '/mcp/sse')) {
-        // MODERN-ONLY POLICY (0.7.0): the GET-SSE stream is a LEGACY-era channel (modern uses
+        // MODERN-ONLY POLICY: the GET-SSE stream is a LEGACY-era channel (modern uses
         // subscriptions/listen on POST) - answer the spec's own compatibility shape, 405 Method
         // Not Allowed + Allow: POST (the Streamable HTTP spec's rule; a MUST across three revisions).
-        // Replaces the old 400/-32020 - HeaderMismatch was an allocation-policy misuse here too.
         if (build && build.serveLegacy === false) {
           res.writeHead(405, { Allow: 'POST', 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
           return res.end(JSON.stringify(makeError(ERR.INVALID_REQUEST,
@@ -1112,6 +1163,42 @@ function createHttpMcpServer(opts = {}) {
    *             upstreamsConnected:number, upstreams:number, toolsExposed:number,
    *             connected:string[], failed:Array<{id:string, error:string}> }}
    */
+  /** The aggregator's stopped upstreams, defensively (a degraded or older build reports none). */
+  function stoppedNow() {
+    try {
+      const agg = build && build.aggregator;
+      const s = agg && typeof agg.stoppedUpstreams === 'function' ? agg.stoppedUpstreams() : [];
+      return Array.isArray(s) ? s.map((x) => ({ id: x.id, error: x.error, attempts: x.attempts })) : [];
+    } catch (_e) {
+      return [];
+    }
+  }
+
+  /** Tools the aggregator dropped for a broken descriptor, defensively (none on a degraded build). */
+  function invalidToolsNow() {
+    try {
+      const agg = build && build.aggregator;
+      const v = agg && typeof agg.invalidTools === 'function' ? agg.invalidTools() : [];
+      return Array.isArray(v) ? v : [];
+    } catch (_e) {
+      return [];
+    }
+  }
+
+  /** The aggregator's tool descriptor changes, defensively (a degraded or older build: none). */
+  function toolChangesNow() {
+    try {
+      const agg = build && build.aggregator;
+      const c = agg && typeof agg.toolChanges === 'function' ? agg.toolChanges() : null;
+      return {
+        pending: c && Array.isArray(c.pending) ? c.pending : [],
+        upgraded: c && Array.isArray(c.upgraded) ? c.upgraded : [],
+      };
+    } catch (_e) {
+      return { pending: [], upgraded: [] };
+    }
+  }
+
   function health() {
     let toolsExposed = 0;
     let upstreamsConnected = 0;
@@ -1184,6 +1271,13 @@ function createHttpMcpServer(opts = {}) {
       // visible. Fresh copies so the caller can never mutate the internal snapshot.
       connected: lastConnect.connected.slice(),
       failed: lastConnect.failed.map((f) => ({ id: f.id, error: f.error })),
+      // LIVE (not the startup snapshot): upstreams that hit the permanent-failure ceiling and
+      // stopped retrying - they stay here until a config reload or a reconnect.
+      stopped: stoppedNow(),
+      // Tool descriptor approval: changes waiting for acceptance + recent upgrades, live.
+      toolChanges: toolChangesNow(),
+      // Tools dropped because their descriptor is structurally broken, live.
+      invalidTools: invalidToolsNow(),
       // OAuth resource-server status (no secrets - issuer/audience live in the well-known doc):
       // whether auth is enabled, whether the optional jose dependency is installed, and whether the
       // current config is coherent enough to enforce (misconfigured: configError() reason present).
@@ -1497,9 +1591,9 @@ function createHttpMcpServer(opts = {}) {
         prevAggForSubs._subscribedUris instanceof Set && prevAggForSubs._subscribedUris.size) {
       next.aggregator._subscribedUris = new Set(prevAggForSubs._subscribedUris);
       // Carry the REFCOUNTS too, exactly as reloadExpose does (server.js). Without them the new
-      // aggregator held the URIs with an empty refs Map, and releaseResources treats refcount 0 as
-      // "last holder" - so the first listener to close unsubscribed upstream and killed the
-      // channel for every other listener still holding that URI (0.7.0).
+      // aggregator holds the URIs with an empty refs Map, and releaseResources treats refcount 0 as
+      // "last holder" - so the first listener to close would unsubscribe upstream and kill the
+      // channel for every other listener still holding that URI.
       if (prevAggForSubs._subscribedRefs instanceof Map) {
         next.aggregator._subscribedRefs = new Map(prevAggForSubs._subscribedRefs);
       }

package/src/mcp/mcp-client.js

@@ -35,6 +35,7 @@
  */
 
 const childProcess = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
 
 const JSONRPC = '2.0';
@@ -42,8 +43,8 @@ const PROTOCOL_VERSION = '2024-11-05';
 // The 2026-07-28 ("modern") protocol version this client can SPEAK to a modern upstream. Over
 // stdio the modern era needs only per-request `_meta` - the Mcp-Method/Mcp-Name/MCP-Protocol-Version
 // headers are HTTP-transport-only, so a stdio client is modern by adding `_meta` + skipping the
-// initialize handshake. Built to the RC spec (locked 2026-05-21); reconcile minor final deltas 28 July.
-const MODERN_PROTOCOL_VERSION = '2026-07-28';
+// initialize handshake.
+const { MODERN_PROTOCOL_VERSION } = require('./modern'); // the ONE definition (version-literal.test.js pins it)
 const CLIENT_INFO = Object.freeze({ name: 'toolfunnel', version: '3.0.0-client' });
 
 /**
@@ -72,11 +73,65 @@ const CLIENT_INFO = Object.freeze({ name: 'toolfunnel', version: '3.0.0-client'
 function winLaunch(command, args) {
   const argv = Array.isArray(args) ? args : [];
   if (process.platform !== 'win32') return { command, args: argv };
-  // A concrete executable can be spawned directly - no shim resolution needed.
-  if (path.isAbsolute(command) && /\.(exe|com)$/i.test(command)) return { command, args: argv };
-  // Otherwise hand it to cmd.exe, which resolves the .cmd/.bat shim via PATHEXT.
+  // A concrete executable can be spawned directly - no shim resolution needed. A relative one
+  // (`../../x/node.exe`, the drive-independent config) resolves against the spawn's cwd.
+  const pathShaped = path.isAbsolute(command) || /[\\/]/.test(command);
+  if (pathShaped && /\.(exe|com)$/i.test(command)) return { command, args: argv };
+  // Otherwise hand it to cmd.exe, which resolves the .cmd/.bat shim via PATHEXT. cmd reads a '/'
+  // as a switch, so a path reaches it with backslashes.
   const comspec = process.env.ComSpec || 'cmd.exe';
-  return { command: comspec, args: ['/c', command, ...argv] };
+  return { command: comspec, args: ['/c', pathShaped ? command.replace(/\//g, '\\') : command, ...argv] };
+}
+
+/**
+ * Windows only: is `command` definitely absent from everywhere cmd.exe would look - the working
+ * directory, then each PATH directory, trying each PATHEXT extension?
+ *
+ * winLaunch routes every non-.exe command through cmd.exe, so a missing command never fails the
+ * spawn with ENOENT: cmd prints a LOCALISED "is not recognized" line and exits 1, exactly like a
+ * server that crashed on start. The owner classifies permanent failures by error code (the
+ * aggregator's reconnect ceiling), so connect() asks this AFTER a failed connect and stamps ENOENT.
+ * It never blocks a spawn. Conservative by construction - it answers true only when every
+ * candidate is definitely absent: a stat error other than ENOENT/ENOTDIR (an App Execution Alias
+ * can refuse stat) counts as found. A PATH entry is split quote-aware (cmd.exe accepts
+ * "C:\a;b" as one directory), and a %VAR% the env cannot expand stays literal, as it does for cmd.exe.
+ *
+ * @param {string} command
+ * @param {string} [cwd]  the child's working directory
+ * @param {object} [env]  the child's merged environment
+ * @returns {boolean}
+ */
+function commandMissing(command, cwd, env) {
+  if (process.platform !== 'win32' || typeof command !== 'string' || command.length === 0) return false;
+  const e = env || process.env;
+  // Env names are case-insensitive on Windows and a merged env can hold both `Path` and `PATH`:
+  // take every spelling (more candidates can only make the answer more conservative).
+  const all = (name) => Object.keys(e).filter((k) => k.toUpperCase() === name).map((k) => String(e[k] || ''));
+  const exts = all('PATHEXT').join(';').split(';').filter(Boolean);
+  const candidates = [command, ...(exts.length ? exts : ['.COM', '.EXE', '.BAT', '.CMD']).map((x) => command + x)];
+  const base = typeof cwd === 'string' && cwd.length ? path.resolve(cwd) : process.cwd();
+  const isPath = /[\\/]/.test(command) || path.isAbsolute(command);
+  const dirs = [base];
+  if (!isPath) {
+    for (const d of all('PATH').join(';').match(/(?:"[^"]*"|[^;])+/g) || []) {
+      const dir = d.replace(/"/g, '').trim();
+      if (!dir) continue;
+      // Expand %VAR% from the child's env where we can; an unknown one stays literal. Either way the
+      // extra candidate can only turn up a match (the safe direction), never hide one.
+      dirs.push(dir.replace(/%([^%]+)%/g, (m, v) => { const hit = all(v.toUpperCase())[0]; return hit !== undefined ? hit : m; }));
+    }
+  }
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      try {
+        fs.statSync(path.resolve(dir, name));
+        return false;
+      } catch (err) {
+        if (!err || (err.code !== 'ENOENT' && err.code !== 'ENOTDIR')) return false;
+      }
+    }
+  }
+  return true;
 }
 
 /**
@@ -161,7 +216,7 @@ class McpClient {
     this._forceLegacy = forceLegacy === true;
     // modernOnly: the MIRROR of legacyPin - refuse the legacy fallback entirely. A modernOnly
     // upstream that does not answer server/discover with the modern protocol FAILS the connect
-    // with a clear error instead of silently negotiating down (era-policy switches, 2026-07-18).
+    // with a clear error instead of silently negotiating down.
     this._modernOnly = modernOnly === true;
     // eraHint ('legacy' is the only meaningful value): the OWNER's memo of the era this upstream
     // negotiated LAST time - an observation, not a policy. It skips the server/discover probe the
@@ -413,6 +468,9 @@ class McpClient {
     // with an error that names the policy - never a silent downgrade.
     if (!discovered && this._modernOnly) {
       this.close();
+      // A command that was never found cannot answer discover either - say THAT, not the policy.
+      const missing = this._missingCommandError('McpClient: upstream could not start');
+      if (missing) throw missing;
       throw new Error(`McpClient: upstream "${this.id}" is modernOnly but did not answer server/discover with the 2026-07-28 protocol - refusing the legacy fallback`);
     }
 
@@ -428,10 +486,10 @@ class McpClient {
           protocolVersion: PROTOCOL_VERSION,
           clientInfo: this._clientInfo,
           // elicitation: real SDK-based servers GATE ctx.elicit() on the client declaring this
-          // capability - without it they answer "Method not found" and never elicit at all
-          // (found testing against real published elicitation servers, 2026-07-17). We honestly handle every elicitation now: the
-          // elicitation bridge's MRTR path for modern callers, a clean decline otherwise.
-          // BOTH modes declared (0.7.0): the 2025-11-25 back-compat rule reads a bare
+          // capability - without it they answer "Method not found" and never elicit at all.
+          // Every elicitation is handled: the elicitation bridge's MRTR path for modern callers,
+          // a clean decline otherwise.
+          // BOTH modes declared: the 2025-11-25 back-compat rule reads a bare
           // `{}` as FORM ONLY, and "Servers MUST NOT send elicitation requests with modes that
           // are not supported by the client" - so without `url` here a conformant upstream is
           // FORBIDDEN from url mode and the relay is structurally dead. Every elicit of either
@@ -441,7 +499,14 @@ class McpClient {
         this._initializeResult = result;
       } catch (err) {
         this.close();
-        throw new Error(`McpClient: initialize failed: ${(err && err.message) || String(err)}`);
+        const message = `McpClient: initialize failed: ${(err && err.message) || String(err)}`;
+        // Name a missing working directory or command first (a spawn ENOENT names only the
+        // executable, and the Windows launch shim hides a missing command behind "exited (code=1)"),
+        // else keep the cause's code - the owner classifies by it.
+        const missing = this._missingCommandError(message);
+        if (missing) throw missing;
+        if (err && typeof err.code === 'string') throw Object.assign(new Error(message), { code: err.code });
+        throw new Error(message);
       }
       // Tell the server the handshake is complete (notification - no id, no reply).
       this._notify('notifications/initialized', {});
@@ -480,7 +545,7 @@ class McpClient {
   }
 
   /**
-   * Era-keyed logLevel handling (0.7.0). A caller's per-request
+   * Era-keyed logLevel handling. A caller's per-request
    * `io.modelcontextprotocol/logLevel` must reach the upstream in the upstream's own vocabulary:
    * MODERN upstream -> left in `_meta` (the trio merge in request()/callTool() preserves it - the
    * trio does not define logLevel), because the modern severity clause obliges the upstream to
@@ -506,7 +571,10 @@ class McpClient {
     const caps = this._initializeResult && this._initializeResult.capabilities;
     if (typeof level === 'string' && caps && caps.logging && level !== this._lastSetLogLevel) {
       this._lastSetLogLevel = level;
-      this._request('logging/setLevel', { level }).catch(() => {}); // fire-and-forget, ordered by the pipe
+      // Fire-and-forget, ordered by the pipe (issued BEFORE the main request). A refusal or timeout
+      // reverts the memo so the next call at this level asks again - memoising it as done left the
+      // upstream at whatever level it had for the rest of the session.
+      this._request('logging/setLevel', { level }).catch(() => { if (this._lastSetLogLevel === level) this._lastSetLogLevel = undefined; });
     }
     return out;
   }
@@ -539,6 +607,15 @@ class McpClient {
    * caught and rethrown clean. Extracted from connect() so probeDiscover() can share it.
    */
   _spawnChild() {
+    // Per-child read state starts CLEAN. On an in-place respawn (connect/probeDiscover after the
+    // previous child died) a half-arrived frame, a refused over-cap skip count, or the old child's
+    // stderr would otherwise be prepended to the new child's first bytes: the drain then swallows
+    // its first reply as the rest of a dead body, and every error quotes the wrong stderr. Same
+    // values as the constructor. The log-level memo goes too - a new process knows no level.
+    this._buf = Buffer.alloc(0);
+    this._skipRemaining = 0;
+    this._stderr = '';
+    this._lastSetLogLevel = undefined;
     try {
       // Cross-platform: POSIX passes through; Windows routes a .cmd/.bat shim through cmd.exe.
       const launch = winLaunch(this._command, this._args);
@@ -550,7 +627,9 @@ class McpClient {
       });
     } catch (err) {
       this._child = null;
-      throw new Error(`McpClient: failed to spawn "${this._command}": ${(err && err.message) || String(err)}`);
+      const failed = new Error(`McpClient: failed to spawn "${this._command}": ${(err && err.message) || String(err)}`);
+      if (err && typeof err.code === 'string') failed.code = err.code; // the owner classifies by code
+      throw failed;
     }
 
     if (!this._child || !this._child.stdin || !this._child.stdout) {
@@ -562,6 +641,21 @@ class McpClient {
     this._wireChild();
   }
 
+  /** A connect-failure Error carrying code ENOENT when the working directory or the command is
+   *  definitely absent (commandMissing - Windows, where the launch shim hides it), else null. */
+  _missingCommandError(message) {
+    if (typeof this._cwd === 'string' && this._cwd.length && !fs.existsSync(this._cwd)) {
+      return Object.assign(new Error(`McpClient: working directory "${this._cwd}" does not exist - ${message}`), { code: 'ENOENT' });
+    }
+    if (!commandMissing(this._command, this._cwd, Object.assign({}, process.env, this._env))) return null;
+    // The cause goes FIRST: the message continues with the upstream's stderr, which a reader
+    // (or the aggregator's bounded stop line) may cut short.
+    return Object.assign(
+      new Error(`McpClient: command "${this._command}" was not found (looked in the working directory and on PATH) - ${message}`),
+      { code: 'ENOENT' }
+    );
+  }
+
   /**
    * Era probe - the 2026-07-28 spec's dual-era client rule for stdio: try `server/discover`
    * BEFORE any legacy `initialize`. A modern or dual-era server answers with its
@@ -578,7 +672,7 @@ class McpClient {
     try {
       return await this._request('server/discover', {
         _meta: {
-          'io.modelcontextprotocol/protocolVersion': '2026-07-28',
+          'io.modelcontextprotocol/protocolVersion': MODERN_PROTOCOL_VERSION,
           'io.modelcontextprotocol/clientCapabilities': {},
           'io.modelcontextprotocol/clientInfo': this._clientInfo,
         },
@@ -593,8 +687,8 @@ class McpClient {
 
   /**
    * tools/list -> the upstream's COMPLETE tool definitions, following `nextCursor` pagination
-   * (0.7.0 - the single-shot version silently truncated a paginating upstream to page 1,
-   * leaving its later tools undiscoverable AND unrunnable). Returns the raw concatenated array
+   * (a single-shot list would silently truncate a paginating upstream to page 1, leaving its
+   * later tools undiscoverable AND unrunnable). Returns the raw concatenated array
    * [{name, description, inputSchema, ...}] from every page (empty array if the server returned
    * no tools). Rejects on timeout / transport failure of ANY page.
    *
@@ -736,11 +830,16 @@ class McpClient {
   _wireChild() {
     const child = this._child;
 
-    child.stdout.on('data', (chunk) => this._onData(chunk));
+    // Every handler below answers only while `child` is STILL this._child. A child that has
+    // exited (or been replaced by an in-place respawn) can still drain buffered stdout/stderr and
+    // fire 'exit'/'error' afterwards - Node emits 'exit' before the stdio streams are done - and
+    // those late events would otherwise land in the NEW child's read state or reject its waiters.
+    child.stdout.on('data', (chunk) => { if (this._child === child) this._onData(chunk); });
     child.stdout.on('error', (err) => this._logErr('stdout error:', (err && err.message) || String(err)));
 
     if (child.stderr) {
       child.stderr.on('data', (d) => {
+        if (this._child !== child) return;
         this._stderr += d.toString('utf8');
         // Keep the captured stderr bounded so a chatty child can't grow memory unbounded.
         if (this._stderr.length > 64 * 1024) {
@@ -756,8 +855,9 @@ class McpClient {
     // server that dies on the unknown method would otherwise corrupt a follow-up connect()). Only
     // null it if it is still THIS child (a fresh respawn may have replaced it).
     child.on('exit', (code, signal) => {
+      if (this._child !== child) return; // a stale child's exit: already handled or superseded
       this._connected = false;
-      if (this._child === child) this._child = null;
+      this._child = null;
       this._rejectAllWaiters(
         new Error(`McpClient: upstream exited (code=${code}, signal=${signal}). stderr:\n${this._stderr}`)
       );
@@ -765,11 +865,14 @@ class McpClient {
     });
     child.on('error', (err) => {
       // Spawn-level failure (e.g. ENOENT) - surfaces here, not as a throw from spawn().
+      if (this._child !== child) return; // a stale child's error: already handled or superseded
       this._connected = false;
-      if (this._child === child) this._child = null;
-      this._rejectAllWaiters(
-        new Error(`McpClient: child process error: ${(err && err.message) || String(err)}`)
-      );
+      this._child = null;
+      const failed = new Error(`McpClient: child process error: ${(err && err.message) || String(err)}`);
+      // Keep the code: the aggregator's reconnect ceiling classifies permanent failures by it
+      // (a re-wrap without it made a missing command look like any other death).
+      if (err && typeof err.code === 'string') failed.code = err.code;
+      this._rejectAllWaiters(failed);
       this._fireOnClose(`error: ${(err && err.message) || String(err)}`);
     });
   }
@@ -1014,8 +1117,8 @@ class McpClient {
 
     if (typeof msg.method === 'string') {
       // SERVER->CLIENT REQUEST (id + method): the upstream is asking ITS client something -
-      // elicitation/create, sampling/createMessage, roots/list. Previously dropped, which left
-      // a conformant upstream holding an open request forever (the elicitation bridge). Surface to the owner;
+      // elicitation/create, sampling/createMessage, roots/list. Dropping one would leave a
+      // conformant upstream holding an open request forever. Surface to the owner;
       // unhandled -> answer -32601 (the honest "this client cannot do that").
       if (typeof this.onServerRequest === 'function') {
         try { this.onServerRequest(msg); return; } catch (_e) { this._logErr('onServerRequest threw (ignored)'); }
@@ -1065,6 +1168,7 @@ module.exports = {
   // exported for unit tests / reuse
   frameRequest,
   winLaunch,
+  commandMissing,
   PROTOCOL_VERSION,
   CLIENT_INFO,
 };

package/src/mcp/modern.js

@@ -17,7 +17,7 @@
  * `server/discover`, the `subscriptions/listen` message shapes and the modern error codes - and
  * executes nothing. `server.js` (stdio) and `http-transport.js` bind it to their wires.
  *
- * Spec sources (RC, locked 2026-05-21; re-verify against the FINAL spec before release):
+ * Spec sources:
  *   - modelcontextprotocol.io/specification/draft/changelog
  *   - .../draft/basic/transports/streamable-http   (headers, validation, error examples)
  *   - .../draft/basic/versioning                   (era model, compatibility matrix)
@@ -64,12 +64,15 @@ const CACHE_HINTS = Object.freeze({
   discover: Object.freeze({ ttlMs: 3600000, cacheScope: 'private' }),
 });
 
-/** The methods whose Mcp-Name header must mirror params.name / params.uri. */
-const NAMED_METHODS = Object.freeze({
+/** The methods whose Mcp-Name header must mirror params.name / params.uri. Null-prototype: the
+ *  lookup is keyed by the CLIENT's method string, and a plain literal answered 'toString' /
+ *  'constructor' / 'valueOf' with an inherited function (truthy), demanding an Mcp-Name header for
+ *  a method the table does not name. */
+const NAMED_METHODS = Object.freeze(Object.assign(Object.create(null), {
   'tools/call': 'name',
   'resources/read': 'uri',
   'prompts/get': 'name',
-});
+}));
 
 /** Safely pull params._meta from a parsed JSON-RPC message. Returns null when absent/malformed. */
 function getMeta(msg) {
@@ -216,8 +219,8 @@ function validateModernHeaders(headers, msg) {
 
 /** The protocol versions this dual-era server speaks (modern first; legacy negotiated via
  *  initialize). Kept as a function so the legacy set is injected once by the server, not
- *  duplicated here. server.js seeds it via setLegacyVersion() - a LIST since 0.7.0
- *  (a single string is still accepted for compatibility). */
+ *  duplicated here. server.js seeds it via setLegacyVersion() with a LIST
+ *  (a single string is also accepted). */
 let _legacyVersions = [];
 function setLegacyVersion(v) {
   if (typeof v === 'string' && v.length > 0) _legacyVersions = [v];

package/src/mcp/protocol.js

@@ -160,7 +160,8 @@ function makeProtocol(deps) {
     try {
       const docs = await registry.instructions(name);
       if (docs === undefined || docs === null) {
-        return errorResult(`toolfunnel_tool_instructions: no tool named "${name}"`);
+        return errorResult(`toolfunnel_tool_instructions: no tool named "${name}" - call toolfunnel_list_tools ` +
+          '(a filter narrows it) to find the right name.');
       }
       return okResult(docs);
     } catch (err) {
@@ -173,7 +174,7 @@ function makeProtocol(deps) {
   // ONLY through gatedRun (PreToolUse gate -> execute -> PostToolUse). This function
   // must NEVER call `execute` itself - that would bypass the gate and break the entire
   // safety case.
-  async function runTool(args) {
+  async function runTool(args, callOpts) {
     const a = args || {};
     const name = a.name;
     if (typeof name !== 'string' || name.length === 0) {
@@ -193,7 +194,9 @@ function makeProtocol(deps) {
     //    executor. A null/undefined resolution means "no such tool" - a clean error, not a throw.
     let resolution;
     try {
-      resolution = await registry.resolveExecution(name, toolArgs);
+      // callOpts { meta, progress } reach an upstream tool's forward; a local register
+      // tool ignores them (a script has no progress channel).
+      resolution = await registry.resolveExecution(name, toolArgs, callOpts);
     } catch (err) {
       return errorResult(`toolfunnel_run_tool: could not resolve "${name}": ${(err && err.message) || err}`);
     }
@@ -262,7 +265,8 @@ function makeProtocol(deps) {
 
     if (!resolution || typeof resolution.execute !== 'function') {
       return errorResult(
-        `toolfunnel_run_tool: tool "${name}" is not runnable (no executable resolution from the register)`
+        `toolfunnel_run_tool: tool "${name}" is not runnable (no executable resolution from the register) - ` +
+          'check the name with toolfunnel_list_tools; an upstream tool is missing while its server is disconnected or disabled.'
       );
     }
 
@@ -343,7 +347,7 @@ function makeProtocol(deps) {
   // ---- dispatch -----------------------------------------------------------
   // The server's single entry point. Pure routing; never throws - an unknown tool or any
   // internal failure becomes a clear error result (defensive by construction).
-  async function dispatch(toolName, args) {
+  async function dispatch(toolName, args, callOpts) {
     try {
       switch (toolName) {
         case META_TOOLS.LIST:
@@ -351,13 +355,14 @@ function makeProtocol(deps) {
         case META_TOOLS.INSTRUCTIONS:
           return await toolInstructions(args);
         case META_TOOLS.RUN:
-          return await runTool(args);
+          return await runTool(args, callOpts);
         case META_TOOLS.HOWTO:
           return await howtoTool(args);
         default: {
           const known = Object.values(META_TOOLS).join(', ');
           return errorResult(
-            `Unknown meta-tool "${toolName}". This MCP exposes only: ${known}.`
+            `Unknown tool "${toolName}". This MCP's own tools are: ${known}. Register and upstream tools are ` +
+              'listed by toolfunnel_list_tools and run with toolfunnel_run_tool.'
           );
         }
       }