toolnexus 0.26.0 → 0.27.0

package/dist/serve.js

@@ -18,7 +18,8 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+// The SDK server transport (and the @hono/node-server it pulls in) is loaded only when an MCP
+// profile is actually served, so importing toolnexus does not pay for it.
 import { sanitize } from "./types.js";
 import { buildMcpServer, exposedMcpTools } from "./mcpserve.js";
 /** Default in-memory store — Tasks live only for the lifetime of the process. */
@@ -136,6 +137,9 @@ export async function startA2AServer(opts) {
     const [host, portStr] = splitAddr(opts.addr);
     const store = a2a ? resolveStore(a2a.store) : undefined;
     const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : [];
+    const StreamableHTTPServerTransport = mcp
+        ? (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport
+        : undefined;
     const server = http.createServer((req, res) => {
         const rpcRes = (id, payload) => {
             res.writeHead(200, { "content-type": "application/json" });

package/dist/skill.d.ts

@@ -39,10 +39,22 @@ export interface SkillSkip {
      */
     detail?: string;
 }
+/** Why a KEPT skill carries a warning (SPEC.md §3, #84). The skill still loads unchanged. */
+export type SkillWarningReason = "oversized-description";
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export declare const SKILL_DESCRIPTION_MAX_CHARS = 1024;
+export interface SkillWarning {
+    location: string;
+    reason: SkillWarningReason;
+    /** Description length in Unicode CODE POINTS (not bytes, not UTF-16 units). */
+    chars: number;
+}
 /** Result of a list-only validate pass (SPEC.md §3, S3). */
 export interface SkillInventory {
     skills: SkillInfo[];
     skipped: SkillSkip[];
+    /** Kept skills that load but carry a warning (oversized description), in discovery order. */
+    warnings: SkillWarning[];
 }
 /** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
 export interface LoadSkillsOptions {
@@ -65,6 +77,8 @@ export interface SkillSource {
      * that stops being reported is indistinguishable from something that was finished.
      */
     skipped: SkillSkip[];
+    /** Exposed (post-allowlist) skills whose description is oversized; never modified (#84). */
+    warnings: SkillWarning[];
 }
 /**
  * Discover + validate skills from the same sources loadSkills accepts, returning

package/dist/skill.js

@@ -12,8 +12,16 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { parse as parseYaml } from "yaml";
+import { createRequire } from "node:module";
 import { compareCodePoints, compareDiscovery, sortEntriesByName } from "./order.js";
+// yaml is required on the first frontmatter parse, not at import, so a host with no skills never
+// loads it. `require` keeps the parse synchronous (listSkills/loadSkills are sync); yaml's Node
+// entry is CommonJS, so this is the same module instance an `import` would get.
+let yamlParse;
+function parseYaml(src) {
+    yamlParse ??= createRequire(import.meta.url)("yaml").parse;
+    return yamlParse(src);
+}
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
@@ -25,6 +33,8 @@ The skill name must match one of the skills listed in your system prompt.`;
  */
 export const SKILLS_PROMPT_PREAMBLE = "Skills provide specialized instructions and workflows for specific tasks.\n" +
     "Use the skill tool to load a skill when a task matches its description.";
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export const SKILL_DESCRIPTION_MAX_CHARS = 1024;
 /**
  * Parse YAML frontmatter (between the leading `---` fences) with a real YAML parser, so folded
  * (`>`)/literal (`|`) block scalars, quoting and multi-line values all resolve correctly.
@@ -304,6 +314,24 @@ function collectCandidates(opts) {
         cands.push(...candidatesFromDefs(opts.skills));
     return cands;
 }
+/**
+ * Warn — never modify — skills whose description exceeds SKILL_DESCRIPTION_MAX_CHARS code
+ * points (SPEC.md §3, #84). Each warning is also sent to the same channel as the
+ * duplicate-name warning. Order follows the given skills (discovery order).
+ */
+function describeWarnings(skills) {
+    const out = [];
+    for (const s of skills) {
+        if (s.description === undefined)
+            continue;
+        const chars = [...s.description].length;
+        if (chars > SKILL_DESCRIPTION_MAX_CHARS) {
+            console.warn(`[toolnexus] skill "${s.name}" (${s.location}) description is ${chars} chars, over ${SKILL_DESCRIPTION_MAX_CHARS} — kept unmodified`);
+            out.push({ location: s.location, reason: "oversized-description", chars });
+        }
+    }
+    return out;
+}
 /** Dedupe candidates by name (first-wins); later duplicates become skips. */
 function mergeCandidates(cands) {
     const skills = {};
@@ -355,7 +383,8 @@ function applySkillsFilter(skills, filter) {
 export function listSkills(input) {
     const opts = typeof input === "string" || Array.isArray(input) ? { dirs: input } : input;
     const merged = mergeCandidates(collectCandidates(opts));
-    return { skills: Object.values(merged.skills), skipped: merged.skipped };
+    const list = Object.values(merged.skills);
+    return { skills: list, skipped: merged.skipped, warnings: describeWarnings(list) };
 }
 /** Discover skills (dirs and/or data) and build the `skill` loader tool. */
 export function loadSkills(input) {
@@ -364,6 +393,7 @@ export function loadSkills(input) {
     const merged = mergeCandidates(collectCandidates(opts));
     const skills = applySkillsFilter(merged.skills, opts.filter);
     const skipped = merged.skipped;
+    const warnings = describeWarnings(Object.values(skills));
     const tool = {
         name: "skill",
         description: SKILL_TOOL_DESCRIPTION,
@@ -426,6 +456,7 @@ export function loadSkills(input) {
         skills,
         tool,
         skipped,
+        warnings,
         prompt() {
             const described = Object.values(skills)
                 .filter((s) => s.description !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/acp.ts

@@ -86,15 +86,28 @@ export interface ACPOptions {
 /** One warm ACP connection: one child process, one session, alive across many
  *  turns. `.generate` has exactly the shape {@link InProcessOptions.generate}
  *  wants, so it plugs straight into {@link createInProcessClient}. */
+/** Per-call options for {@link ACPClient.generate} / {@link ACPClient.generateStream}. */
+export interface ACPGenerateOptions {
+  /** Cancels the turn: when it aborts mid-turn the `session/cancel` notification is sent,
+   *  the turn's reply is awaited (bounded by `requestTimeoutMs`, default 30s) so the next
+   *  turn never lands on a busy session, and the call rejects with an `AbortError`. The
+   *  process and session stay warm. */
+  signal?: AbortSignal
+}
+
 export interface ACPClient {
-  generate: (request: InProcessRequest) => Promise<InProcessResponse>
+  generate: (request: InProcessRequest, opts?: ACPGenerateOptions) => Promise<InProcessResponse>
   /** {@link generate}, streaming: `emit` fires as each `session/update` arrives —
    *  agent_message_chunk → `text`, agent_thought_chunk → `thought` (via "acp"),
    *  tool_call → `tool_call` and a completed/failed tool_call_update → `tool_result`
    *  (both via "acp": the agent's own tools, reported, never executed by the loop).
    *  Shaped for {@link InProcessOptions.generateStream}. The returned content is the
    *  message text only. */
-  generateStream: (request: InProcessRequest, emit: (event: StreamEvent) => void) => Promise<InProcessResponse>
+  generateStream: (
+    request: InProcessRequest,
+    emit: (event: StreamEvent) => void,
+    opts?: ACPGenerateOptions,
+  ) => Promise<InProcessResponse>
   /** Terminates the agent's process group. Idempotent — a second call is a no-op. */
   close: () => Promise<void>
   /** The agent's raw `initialize` result. */
@@ -375,7 +388,12 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   // queue itself never rejects (a failed turn does not poison later ones).
   let turnQueue: Promise<unknown> = Promise.resolve()
 
-  async function promptOnce(request: InProcessRequest, emit?: (event: StreamEvent) => void): Promise<InProcessResponse> {
+  async function promptOnce(
+    request: InProcessRequest,
+    emit?: (event: StreamEvent) => void,
+    signal?: AbortSignal,
+  ): Promise<InProcessResponse> {
+    if (signal?.aborted) throw acpAbortError()
     const text = renderPrompt(request)
     const id = `c-${++nextId}`
 
@@ -440,21 +458,48 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
       )
     })
 
+    let onAbort: (() => void) | undefined
+    const cancelled = new Promise<"cancelled">((resolve) => {
+      if (!signal) return
+      onAbort = () => resolve("cancelled")
+      signal.addEventListener("abort", onAbort, { once: true })
+    })
+
     try {
-      const msg = await Promise.race([replyPromise, timeout])
+      const msg = await Promise.race([replyPromise, timeout, cancelled])
+      if (msg === "cancelled") {
+        // ACP: session/cancel is a notification (no id); the agent then ends the turn with
+        // stopReason "cancelled". Wait (bounded) for that reply so the session is idle again.
+        write({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } })
+        const waitMs = opts.requestTimeoutMs && opts.requestTimeoutMs > 0 ? opts.requestTimeoutMs : 30000
+        let wait: NodeJS.Timeout | undefined
+        await Promise.race([
+          replyPromise,
+          new Promise((r) => {
+            wait = setTimeout(r, waitMs)
+          }),
+        ])
+        clearTimeout(wait)
+        throw acpAbortError()
+      }
       if (msg.error && msg.error.code === 0) throw new Error(msg.error.message)
       if (msg.error) throw new Error(`toolnexus: ACP error ${msg.error.code}: ${msg.error.message}`)
       return { content }
     } finally {
       clearTimeout(timer)
+      if (onAbort) signal!.removeEventListener("abort", onAbort)
       pending.delete(id)
       updateSink = null
     }
   }
 
-  const generateStream = (request: InProcessRequest, emit?: (event: StreamEvent) => void): Promise<InProcessResponse> => {
+  const generateStream = (
+    request: InProcessRequest,
+    emit?: (event: StreamEvent) => void,
+    callOpts?: ACPGenerateOptions,
+  ): Promise<InProcessResponse> => {
     if (closed) return Promise.reject(new Error("toolnexus: ACP client is closed"))
-    const turn = turnQueue.then(() => promptOnce(request, emit))
+    const turn = turnQueue.then(() => promptOnce(request, emit, callOpts?.signal))
     turnQueue = turn.then(
       () => undefined,
       () => undefined,
@@ -478,7 +523,8 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
     if (t === "late") await Promise.race([childGone, new Promise((r) => setTimeout(r, 1000).unref())])
   }
 
-  const generate = (request: InProcessRequest): Promise<InProcessResponse> => generateStream(request)
+  const generate = (request: InProcessRequest, callOpts?: ACPGenerateOptions): Promise<InProcessResponse> =>
+    generateStream(request, undefined, callOpts)
 
   const client: ACPClient = { generate, generateStream, close, initializeResult }
   // Non-enumerable, undocumented — internal test hook only, so the public
@@ -487,6 +533,12 @@ export async function loadACP(opts: ACPOptions): Promise<ACPClient> {
   return client
 }
 
+function acpAbortError(): Error {
+  const e = new Error("toolnexus: ACP turn cancelled")
+  e.name = "AbortError"
+  return e
+}
+
 /** Signals the child's whole process group (POSIX), else the child itself. Never throws. */
 function killGroup(pid: number, signal: NodeJS.Signals): void {
   if (process.platform !== "win32") {

package/src/classifier.ts

@@ -104,12 +104,35 @@ export const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, Readonly<Cl
   custom: {
     baseUrl: "",
     model: DEFAULT_CLASSIFIER_MODEL,
-    apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV,
+    apiKeyEnv: "",
     wire: "systemone",
     imagesHeader: true,
   },
 })
 
+/**
+ * The env var whose key may be sent to `baseUrl` (already `${NAME}`-expanded): the backend's own
+ * variable, and only when `baseUrl` is that backend's own host over https (OpenRouter also its
+ * subdomains). `""` when none may — `custom` has no preset key at all. A key is never sent to a
+ * host the caller did not name (#155, SPEC §8B).
+ */
+export function classifierKeyEnv(backend: ClassifierBackend, baseUrl: string): string {
+  const p = Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, backend) ? CLASSIFIER_BACKENDS[backend] : undefined
+  if (!p || !p.apiKeyEnv || !p.baseUrl) return ""
+  const hostOf = (u: string): string => {
+    try {
+      const url = new URL(u)
+      return url.protocol === "https:" ? url.hostname.toLowerCase() : ""
+    } catch {
+      return ""
+    }
+  }
+  const h = hostOf(baseUrl)
+  const own = hostOf(p.baseUrl)
+  if (!h || !own) return ""
+  return h === own || (backend === "openrouter" && h.endsWith(".openrouter.ai")) ? p.apiKeyEnv : ""
+}
+
 /**
  * Raised BEFORE any network call when the backend table says the backend cannot take what the
  * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
@@ -650,6 +673,9 @@ export class Classifier {
   private readonly baseUrl: string
   private readonly model: string
   private readonly apiKeyEnv: string
+  /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+   * and only to its own host (classifierKeyEnv, #155). */
+  private readonly explicitKeyEnv: boolean
   private readonly timeoutMs: number
   private readonly backend: ClassifierBackend
   private readonly preset: Readonly<ClassifierBackendPreset>
@@ -675,6 +701,7 @@ export class Classifier {
     this.baseUrl = opts.baseUrl || preset.baseUrl
     this.model = opts.model ?? preset.model
     this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv
+    this.explicitKeyEnv = opts.apiKeyEnv !== undefined
     const mismatch = backendMismatch(this.baseUrl, this.model)
     if (mismatch) throw new Error(mismatch)
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS
@@ -1019,7 +1046,7 @@ export class Classifier {
       try {
         res = await doFetch(url, {
           method: "POST",
-          headers: this.requestHeaders(extraHeaders),
+          headers: this.requestHeaders(extraHeaders, url),
           body: payload,
           signal: timer.signal,
         })
@@ -1049,9 +1076,10 @@ export class Classifier {
   }
 
   /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
-  private requestHeaders(extra: Record<string, string> = {}): Record<string, string> {
+  private requestHeaders(extra: Record<string, string>, url: string): Record<string, string> {
     const headers: Record<string, string> = { "Content-Type": "application/json" }
-    const key = process.env[this.apiKeyEnv]
+    const keyEnv = this.explicitKeyEnv ? this.apiKeyEnv : classifierKeyEnv(this.backend, url)
+    const key = keyEnv ? process.env[keyEnv] : undefined
     if (key) headers["Authorization"] = `Bearer ${key}`
     // The image opt-in header goes BEFORE host headers, which win.
     for (const [k, v] of Object.entries(extra)) headers[k] = v
@@ -1341,10 +1369,27 @@ function imageSize(format: string, b: Uint8Array): [number, number] | undefined
   return undefined
 }
 
-/** The System One reply inside a Cloudflare `/ai/run` envelope. Its error list is never echoed. */
+/**
+ * `: <code> <message>` from errors[0] of a failed envelope (SPEC §8B), through the same redaction
+ * and cap as cause(). Cloudflare reports a missing balance, a bad model id and a malformed
+ * request alike as HTTP 200 + success:false, so this is the only thing that tells them apart.
+ * `""` when there is nothing to show.
+ */
+function cloudflareCause(env: unknown): string {
+  const errs = env !== null && typeof env === "object" ? (env as any).errors : undefined
+  const e0 = Array.isArray(errs) ? errs[0] : undefined
+  if (e0 === null || typeof e0 !== "object") return ""
+  const parts: string[] = []
+  if ((typeof e0.code === "number" || typeof e0.code === "string") && String(e0.code) !== "") parts.push(String(e0.code))
+  if (typeof e0.message === "string" && e0.message !== "") parts.push(e0.message)
+  const s = capErrorBody(redactErrorBody(parts.join(" ")))
+  return s ? ": " + s : ""
+}
+
+/** The System One reply inside a Cloudflare `/ai/run` envelope. Only errors[0] is ever echoed. */
 function unwrapCloudflare(env: unknown): unknown {
   if (env === null || typeof env !== "object" || Array.isArray(env) || (env as any).success !== true) {
-    throw new Error("classifier: cloudflare: envelope not successful")
+    throw new Error("classifier: cloudflare: envelope not successful" + cloudflareCause(env))
   }
   let result = (env as any).result
   if (result !== null && typeof result === "object" && !Array.isArray(result) && typeof result.state === "string") {

package/src/mcp.ts

@@ -6,18 +6,22 @@
 import { readFileSync } from "node:fs"
 import { Client } from "@modelcontextprotocol/sdk/client/index.js"
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
+import { AdoptedStdioTransport } from "./mcp2026/stdio.js"
 import type { Tool as McpToolDef, ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js"
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js"
 import { type JSONSchema, type Tool, type ToolContext, type ToolHints, type ToolResult, type McpStatus, type Request, type Answer, sanitize } from "./types.js"
 import { type ContentPart, summarizePart } from "./content.js"
 import type { SkillDef } from "./skill.js"
-import { probe, newOAuth, defaultTokenStore, type AuthConfig, type ModernServer, type Load2026Options } from "./mcp2026/source.js"
+import { type AuthConfig, type ModernServer, type Load2026Options } from "./mcp2026/source.js"
 import { PendingError, type OAuth, type TokenStore } from "./mcp2026/auth.js"
 export { Token, MemoryTokenStore, type TokenStore } from "./mcp2026/auth.js"
 export type { AuthConfig } from "./mcp2026/source.js"
 
+// Loaded on first use, not at import: the 2026 client is only needed once a config is loaded,
+// and the SDK's remote transports (streamable-HTTP, SSE) only when a remote server falls back.
+let mcp2026: Promise<typeof import("./mcp2026/source.js")> | undefined
+const loadMcp2026 = () => (mcp2026 ??= import("./mcp2026/source.js"))
+
 // ---------------------------------------------------------------------------
 // MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
 // (a reverse-request). We map it onto the one `waitFor`: form mode → kind:"input",
@@ -477,6 +481,10 @@ async function connectTransport(client: Client, cfg: ServerConfig, auth?: Fallba
     const expanded = expandEnvHeaders(cfg.headers)
     const requestInit = expanded ? { headers: expanded } : undefined
     const fetch = auth ? bearerFetch(cfg.url, auth) : undefined
+    const [{ StreamableHTTPClientTransport }, { SSEClientTransport }] = await Promise.all([
+      import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+      import("@modelcontextprotocol/sdk/client/sse.js"),
+    ])
     try {
       await client.connect(new StreamableHTTPClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }))
     } catch {
@@ -552,6 +560,7 @@ type Connected =
  * path, with the OAuth bearer attached for remote servers. Throws ⇒ the server failed.
  */
 async function connectServer(name: string, cfg: ServerConfig, timeout: number, opts: McpLoadOptions, store: TokenStore, sdkClient: () => Client, onSdk: (c: Client) => void): Promise<Connected> {
+  const { newOAuth, probe } = await loadMcp2026()
   const o: Load2026Options = { waitFor: opts.waitFor, tokenStore: store, openUrl: opts.openUrl, signal: opts.signal, disableTools: opts.disableTools }
   const remote = isRemote(cfg)
   const oauth = remote ? newOAuth(cfg.auth, o, store) : undefined
@@ -570,7 +579,10 @@ async function connectServer(name: string, cfg: ServerConfig, timeout: number, o
   if (p.kind === "modern") return p
   const client = sdkClient()
   onSdk(client)
-  await raceTimeout(connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined), timeout, opts.signal)
+  const connecting = p.reuse
+    ? client.connect(new AdoptedStdioTransport(p.reuse.child, p.reuse.leftover)) // §2.2a: same child, no respawn
+    : connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined)
+  await raceTimeout(connecting, timeout, opts.signal)
   const defs = await raceTimeout(paginateTools(client, timeout), timeout, opts.signal)
   return { kind: "sdk", client, defs }
 }
@@ -596,7 +608,7 @@ export async function loadMcp(
   const clients: { close(): Promise<void> }[] = []
   const servers = new Map<string, ServerConn>()
   const skills: SkillDef[] = []
-  const store = defaultTokenStore({ tokenStore: opts?.tokenStore })
+  const store = (await loadMcp2026()).defaultTokenStore({ tokenStore: opts?.tokenStore })
   const waitFor = opts?.waitFor
   const signal = opts?.signal
   const onServer = opts?.onServer
@@ -701,7 +713,7 @@ export async function listMcpTools(input: string | object, opts?: McpLoadOptions
   const toolsByServer: Record<string, ToolInfo[]> = {}
   const status: Record<string, McpStatus> = {}
   const signal = opts?.signal
-  const store = defaultTokenStore({ tokenStore: opts?.tokenStore })
+  const store = (await loadMcp2026()).defaultTokenStore({ tokenStore: opts?.tokenStore })
 
   await Promise.all(
     Object.entries(config).map(async ([name, cfg]) => {

package/src/mcp2026/source.ts

@@ -8,7 +8,8 @@ import { randomBytes } from "node:crypto"
 import { Mcp2026Client } from "./client.js"
 import { HttpStatusError, NotJsonRpcError, PROTOCOL_VERSION, RpcError, SKILLS_EXT, type Obj } from "./protocol.js"
 import { LoopbackAuthorizer, MemoryTokenStore, OAuth, PauseAuthorizer, PendingError, type TokenStore } from "./auth.js"
-import { spawnStdio, StdioClosedError } from "./stdio.js"
+import { spawnStdio, StdioClosedError, type StdioTransport } from "./stdio.js"
+import type { ChildProcess } from "node:child_process"
 import { rank } from "./toolsearch.js"
 import type { Answer, JSONSchema, Request, Tool, ToolContext, ToolResult } from "../types.js"
 import { sanitize } from "../types.js"
@@ -88,7 +89,9 @@ async function authed(oauth: OAuth | undefined, waitFor: WaitFor | undefined, f:
 }
 
 /** What the probe decided. `fallback` ⇒ take the frozen SDK path; anything thrown ⇒ status failed. */
-export type Probe = { kind: "modern"; server: ModernServer } | { kind: "fallback" }
+export type Probe =
+  | { kind: "modern"; server: ModernServer }
+  | { kind: "fallback"; reuse?: { child: ChildProcess; leftover: Buffer } }
 
 /** §2.2a: which discover failures mean "old server". */
 function isFallbackError(e: unknown): boolean {
@@ -115,11 +118,14 @@ export interface ProbeTarget {
 /** Discover first (§2.2). Resolves `modern` (tools listed) or `fallback`; throws on a load failure. */
 export async function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe> {
   let client: Mcp2026Client
+  let stdio: StdioTransport | undefined
   if (t.remote) {
     client = new Mcp2026Client(t.remote.url, { headers: t.remote.headers, auth: t.remote.oauth, timeoutMs: t.timeout })
   } else {
-    const tr = await spawnStdio(t.local!.argv, t.local!.env, t.local!.cwd)
-    client = new Mcp2026Client("", { transport: tr, timeoutMs: t.timeout })
+    stdio = await spawnStdio(t.local!.argv, t.local!.env, t.local!.cwd)
+    // Stop parsing right after the discover reply so an old server's child can be handed over.
+    stdio.holdAfterNextResponse()
+    client = new Mcp2026Client("", { transport: stdio, timeoutMs: t.timeout })
   }
   const oauth = t.remote?.oauth
   let disc: Obj
@@ -129,6 +135,8 @@ export async function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe>
     disc = await authed(oauth, o.waitFor, () => client.call("server/discover", {}, { timeoutMs, signal: o.signal }))
   } catch (e) {
     const stdioTimeout = !!t.local && e instanceof Error && e.message === "stdio request timed out"
+    // §2.2a: a fast JSON-RPC error over stdio ⇒ the SAME child continues into initialize.
+    if (stdio && e instanceof RpcError && !o.signal?.aborted) return { kind: "fallback", reuse: stdio.detach() }
     await client.close().catch(() => {})
     if (o.signal?.aborted) throw e
     if (e instanceof StdioClosedError) throw e
@@ -136,9 +144,11 @@ export async function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe>
     throw e
   }
   if (!supports2026(disc)) {
+    if (stdio) return { kind: "fallback", reuse: stdio.detach() }
     await client.close().catch(() => {})
     return { kind: "fallback" }
   }
+  stdio?.release()
   try {
     const server = new ModernServer(t, client, disc, o)
     await server.load()