@orkestrel/mcp 0.0.20 → 0.0.21

package/dist/src/server/index.d.cts

@@ -324,22 +324,24 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
 
 /**
  * Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link MCPClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+ * — a {@link StdioClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
  * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
  *
  * @remarks
  * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
  * spawns `options.command` with `options.args` and `options.env`, piping its
- * `stdin`/`stdout` for the JSON-RPC channel (its `stderr` inherits the parent's for
- * diagnostics). Each JSON-RPC message the client `send`s is written as one
+ * `stdin`/`stdout` for the JSON-RPC channel. The child's `stderr` is piped too, and
+ * retained as a bounded tail this transport reports as `evidence` — the parent never
+ * inherits it. Each JSON-RPC message the client `send`s is written as one
  * newline-terminated line to the child's `stdin`; each decoded reply line from the
  * child's `stdout` is surfaced on the transport's `message` event for the client's
  * id correlation.
  *
  * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
  *   and optional `env`; see {@link StdioClientTransportOptions}
- * @returns A working {@link MCPClientTransportInterface} over a child process's stdio
+ * @returns A working {@link StdioClientTransportInterface} over a child process's stdio,
+ *   whose `evidence` carries the supervised child's bounded stderr tail
  *
  * @example
  * ```ts
@@ -353,7 +355,7 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
  * const tools = await client.tools()
  * ```
  */
-export declare function createStdioClientTransport(options: StdioClientTransportOptions): MCPClientTransportInterface;
+export declare function createStdioClientTransport(options: StdioClientTransportOptions): StdioClientTransportInterface;
 
 /**
  * Creates the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
@@ -1242,7 +1244,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 
 /**
  * The stdio CLIENT transport for the Model Context Protocol — a
- * {@link MCPClientTransportInterface} that drives a CHILD PROCESS MCP server over
+ * {@link StdioClientTransportInterface} that drives a CHILD PROCESS MCP server over
  * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
@@ -1263,16 +1265,32 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
  *   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
  *   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
- * - **`close()`** releases this transport's line pump without waiting for the child's stdout
- *   iterator, then runs the supervisor's bounded `SIGTERM` → grace → `SIGKILL` group-kill and
- *   teardown before firing `close` once (idempotent). A descendant can retain an inherited stdout
- *   pipe after the child exits; the pump's release barrier keeps that substrate limit from keeping
- *   this transport's `close()` pending. On a POSIX host the child leads its own process group, so
- *   the group-kill reaches its grandchildren rather than orphaning them.
+ * - **`close()`** runs the supervisor's bounded termination and teardown, then fires `close` once
+ *   (idempotent). That teardown reaches the child's TERMINAL MOMENT, where the supervisor freezes
+ *   `evidence`, ends `lines`, and settles `exit` together, so this transport needs no release of
+ *   its own to get its line pump back: the stream ends under the pump rather than throwing at it.
+ *   A line the supervisor had already framed behind the one being delivered is dropped rather than
+ *   emitted onto a transport whose teardown has begun. A `close()` issued while that teardown runs
+ *   joins it rather than opening a second one, so it resolves only after `close` has fired, and a
+ *   `start()` issued while it runs waits behind the same barrier, so lifetimes never overlap. A
+ *   descendant can retain an inherited stdout pipe after the child exits; the supervisor's `drain`
+ *   bound cuts that wait off, so this transport's `close()` settles within that bound rather than
+ *   on the descendant. The termination itself belongs to the host: a POSIX host signals the
+ *   child's own process group `SIGTERM`, waits the grace window, then `SIGKILL`s through the same
+ *   route, so the kill reaches grandchildren rather than orphaning them, while Windows ends the
+ *   tree with `taskkill /F /T`, which nothing in the child can intercept.
+ * - **Evidence.** `evidence` reports that retained stderr tail off the HELD child — its live tail
+ *   while the child runs, and the value the supervisor froze at that child's terminal moment
+ *   afterwards. The reference is held past that moment and replaced only by the next `start()`,
+ *   which is what keeps a post-`close()` read stable without a private copy: the frozen value
+ *   never moves again, so a detached descendant writing to the inherited stderr after the cutoff
+ *   cannot grow it. See {@link StdioClientTransportInterface.evidence} for the readings and the
+ *   byte bound.
  * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
- *   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
- *   own listener-error channel.
+ *   fault, including the child spawn cause the supervisor surfaces and the notice that this
+ *   lifetime's `evidence` was cut off at the `drain` bound), distinct from the emitter's own
+ *   listener-error channel.
  *
  * @example
  * ```ts
@@ -1281,17 +1299,86 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
  * ```
  */
-export declare class StdioClientTransport implements MCPClientTransportInterface_2 {
+export declare class StdioClientTransport implements StdioClientTransportInterface {
     #private;
     constructor(options: StdioClientTransportOptions);
     get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
     get duplex(): boolean;
+    get evidence(): string | undefined;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }
 
+/**
+ * The contract `createStdioClientTransport` returns — a {@link MCPClientTransportInterface}
+ * that also reports the supervised child's stderr tail, the diagnostic a child that dies at
+ * startup leaves behind.
+ *
+ * @remarks
+ * This contract adds `evidence` and changes nothing else: `emitter`, `session`, `duplex`,
+ * `start`, `send`, and `close` are the shared client-transport surface, unchanged. It sits here
+ * rather than on {@link MCPClientTransportInterface} because a transport that supervises no child —
+ * Streamable HTTP, WebSocket, a `MessagePort` pair — has no such tail, and a member every one
+ * of them answers `undefined` to forever is a stdio detail rather than a shared contract. A
+ * consumer that widens this value back to {@link MCPClientTransportInterface}, including by
+ * reading `client.transport`, loses the reader and must keep the original reference.
+ */
+export declare interface StdioClientTransportInterface extends MCPClientTransportInterface {
+    /**
+     * The supervised child's decoded stderr tail — live while a child is held, and the value
+     * captured at that child's end afterwards.
+     *
+     * @remarks
+     * - **Readings.** `undefined` while no child has run and none has been captured — before the
+     *   first `start()`. The live tail while a child is held, which reads `''` from the moment
+     *   that child is spawned until it writes. The captured tail after the child ended, whether
+     *   it exited on its own or `close()` terminated it, and `''` there for a child that ran and
+     *   wrote nothing — an empty tail is a real reading of a silent child, distinct from the
+     *   absent one.
+     * - **Lifetime.** The tail follows the child that produced it. The supervisor FREEZES it at
+     *   that child's terminal moment — the moment `close()`'s teardown resolves past, and the
+     *   moment the exit that fires this transport's `close` settles at — and this transport keeps
+     *   reading that same child afterwards. The frozen value never moves again, which is what
+     *   makes a late read stable: a detached descendant holding the child's inherited stderr can
+     *   still write bytes after `close()` resolves, and those bytes reach no reading this
+     *   transport reports. The next `start()` replaces the held child, so a replacement never
+     *   reports its predecessor's stderr as current. Lifetimes never overlap: a `start()` issued
+     *   while a `close()` is still tearing down waits for that teardown to report `close` before
+     *   it opens the next one, so an older tail cannot arrive over a newer one however the calls
+     *   interleave. Read the tail before you open a replacement, and read how far it reaches
+     *   inside one `close` emit off the way the lifetime ended. An explicit `close()` still holds
+     *   its teardown barrier while those listeners run, so a `start()` one of them calls parks
+     *   behind it and every later listener reads the ended child's frozen tail. A natural exit
+     *   holds that barrier only across the `error` it reports at that end, so a restart begun
+     *   THERE parks until `close` has been delivered, while a `close` listener that calls
+     *   `start()` opens the next lifetime itself and replaces the value every listener after it
+     *   would have read.
+     * - **What the close path carries.** The frozen value is what the supervisor had received by
+     *   that terminal moment, not the child's complete output.
+     *   Windows ends the tree with `taskkill /F /T`, which nothing in the child can intercept: a
+     *   `SIGTERM` handler never runs there, so the bytes it would have written never exist. A
+     *   child that ends on its own closes its stderr first, and THAT tail is complete.
+     *   Where that moment arrived at the supervisor's `drain` bound rather than at the child's
+     *   own stream close, the tail stops at the cutoff and later diagnostics may have existed;
+     *   the transport emits an `error` naming that lifetime, so a partial tail reads as partial.
+     * - **Bound.** The supervisor keeps the END of the child's raw stderr bytes, at most
+     *   `@orkestrel/process`'s {@link import('@orkestrel/process').PROCESS_EVIDENCE} (2048
+     *   bytes under 0.0.6). A child that writes more than the bound loses its earliest output
+     *   and keeps its last, which is the half that names why it died. The bound counts raw
+     *   bytes before decoding rather than characters, so multibyte output yields fewer
+     *   characters than an ASCII run over the same byte window. The kept bytes never begin
+     *   inside a multibyte sequence: where the cut lands mid-character the start retreats to
+     *   that character's first byte, so the tail decodes without a replacement character and
+     *   can hold a few bytes fewer than the bound.
+     * - **A spawn fault leaves no tail.** A spawn that produced no child wrote no stderr, so
+     *   `evidence` reads `''` for that lifetime. Its cause — the host's `ENOENT` for a command
+     *   that does not resolve — arrives on the `error` event instead.
+     */
+    readonly evidence: string | undefined;
+}
+
 /**
  * Options for `createStdioClientTransport` — the child process to spawn as a
  * stdio-framed MCP server (newline-delimited JSON-RPC over `stdin`/`stdout`).

package/dist/src/server/index.d.ts

@@ -324,22 +324,24 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
 
 /**
  * Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link MCPClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+ * — a {@link StdioClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
  * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
  *
  * @remarks
  * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
  * spawns `options.command` with `options.args` and `options.env`, piping its
- * `stdin`/`stdout` for the JSON-RPC channel (its `stderr` inherits the parent's for
- * diagnostics). Each JSON-RPC message the client `send`s is written as one
+ * `stdin`/`stdout` for the JSON-RPC channel. The child's `stderr` is piped too, and
+ * retained as a bounded tail this transport reports as `evidence` — the parent never
+ * inherits it. Each JSON-RPC message the client `send`s is written as one
  * newline-terminated line to the child's `stdin`; each decoded reply line from the
  * child's `stdout` is surfaced on the transport's `message` event for the client's
  * id correlation.
  *
  * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
  *   and optional `env`; see {@link StdioClientTransportOptions}
- * @returns A working {@link MCPClientTransportInterface} over a child process's stdio
+ * @returns A working {@link StdioClientTransportInterface} over a child process's stdio,
+ *   whose `evidence` carries the supervised child's bounded stderr tail
  *
  * @example
  * ```ts
@@ -353,7 +355,7 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
  * const tools = await client.tools()
  * ```
  */
-export declare function createStdioClientTransport(options: StdioClientTransportOptions): MCPClientTransportInterface;
+export declare function createStdioClientTransport(options: StdioClientTransportOptions): StdioClientTransportInterface;
 
 /**
  * Creates the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
@@ -1242,7 +1244,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 
 /**
  * The stdio CLIENT transport for the Model Context Protocol — a
- * {@link MCPClientTransportInterface} that drives a CHILD PROCESS MCP server over
+ * {@link StdioClientTransportInterface} that drives a CHILD PROCESS MCP server over
  * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
@@ -1263,16 +1265,32 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
  *   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
  *   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
- * - **`close()`** releases this transport's line pump without waiting for the child's stdout
- *   iterator, then runs the supervisor's bounded `SIGTERM` → grace → `SIGKILL` group-kill and
- *   teardown before firing `close` once (idempotent). A descendant can retain an inherited stdout
- *   pipe after the child exits; the pump's release barrier keeps that substrate limit from keeping
- *   this transport's `close()` pending. On a POSIX host the child leads its own process group, so
- *   the group-kill reaches its grandchildren rather than orphaning them.
+ * - **`close()`** runs the supervisor's bounded termination and teardown, then fires `close` once
+ *   (idempotent). That teardown reaches the child's TERMINAL MOMENT, where the supervisor freezes
+ *   `evidence`, ends `lines`, and settles `exit` together, so this transport needs no release of
+ *   its own to get its line pump back: the stream ends under the pump rather than throwing at it.
+ *   A line the supervisor had already framed behind the one being delivered is dropped rather than
+ *   emitted onto a transport whose teardown has begun. A `close()` issued while that teardown runs
+ *   joins it rather than opening a second one, so it resolves only after `close` has fired, and a
+ *   `start()` issued while it runs waits behind the same barrier, so lifetimes never overlap. A
+ *   descendant can retain an inherited stdout pipe after the child exits; the supervisor's `drain`
+ *   bound cuts that wait off, so this transport's `close()` settles within that bound rather than
+ *   on the descendant. The termination itself belongs to the host: a POSIX host signals the
+ *   child's own process group `SIGTERM`, waits the grace window, then `SIGKILL`s through the same
+ *   route, so the kill reaches grandchildren rather than orphaning them, while Windows ends the
+ *   tree with `taskkill /F /T`, which nothing in the child can intercept.
+ * - **Evidence.** `evidence` reports that retained stderr tail off the HELD child — its live tail
+ *   while the child runs, and the value the supervisor froze at that child's terminal moment
+ *   afterwards. The reference is held past that moment and replaced only by the next `start()`,
+ *   which is what keeps a post-`close()` read stable without a private copy: the frozen value
+ *   never moves again, so a detached descendant writing to the inherited stderr after the cutoff
+ *   cannot grow it. See {@link StdioClientTransportInterface.evidence} for the readings and the
+ *   byte bound.
  * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
- *   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
- *   own listener-error channel.
+ *   fault, including the child spawn cause the supervisor surfaces and the notice that this
+ *   lifetime's `evidence` was cut off at the `drain` bound), distinct from the emitter's own
+ *   listener-error channel.
  *
  * @example
  * ```ts
@@ -1281,17 +1299,86 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
  * ```
  */
-export declare class StdioClientTransport implements MCPClientTransportInterface_2 {
+export declare class StdioClientTransport implements StdioClientTransportInterface {
     #private;
     constructor(options: StdioClientTransportOptions);
     get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
     get session(): string | undefined;
     get duplex(): boolean;
+    get evidence(): string | undefined;
     start(): Promise<void>;
     send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }
 
+/**
+ * The contract `createStdioClientTransport` returns — a {@link MCPClientTransportInterface}
+ * that also reports the supervised child's stderr tail, the diagnostic a child that dies at
+ * startup leaves behind.
+ *
+ * @remarks
+ * This contract adds `evidence` and changes nothing else: `emitter`, `session`, `duplex`,
+ * `start`, `send`, and `close` are the shared client-transport surface, unchanged. It sits here
+ * rather than on {@link MCPClientTransportInterface} because a transport that supervises no child —
+ * Streamable HTTP, WebSocket, a `MessagePort` pair — has no such tail, and a member every one
+ * of them answers `undefined` to forever is a stdio detail rather than a shared contract. A
+ * consumer that widens this value back to {@link MCPClientTransportInterface}, including by
+ * reading `client.transport`, loses the reader and must keep the original reference.
+ */
+export declare interface StdioClientTransportInterface extends MCPClientTransportInterface {
+    /**
+     * The supervised child's decoded stderr tail — live while a child is held, and the value
+     * captured at that child's end afterwards.
+     *
+     * @remarks
+     * - **Readings.** `undefined` while no child has run and none has been captured — before the
+     *   first `start()`. The live tail while a child is held, which reads `''` from the moment
+     *   that child is spawned until it writes. The captured tail after the child ended, whether
+     *   it exited on its own or `close()` terminated it, and `''` there for a child that ran and
+     *   wrote nothing — an empty tail is a real reading of a silent child, distinct from the
+     *   absent one.
+     * - **Lifetime.** The tail follows the child that produced it. The supervisor FREEZES it at
+     *   that child's terminal moment — the moment `close()`'s teardown resolves past, and the
+     *   moment the exit that fires this transport's `close` settles at — and this transport keeps
+     *   reading that same child afterwards. The frozen value never moves again, which is what
+     *   makes a late read stable: a detached descendant holding the child's inherited stderr can
+     *   still write bytes after `close()` resolves, and those bytes reach no reading this
+     *   transport reports. The next `start()` replaces the held child, so a replacement never
+     *   reports its predecessor's stderr as current. Lifetimes never overlap: a `start()` issued
+     *   while a `close()` is still tearing down waits for that teardown to report `close` before
+     *   it opens the next one, so an older tail cannot arrive over a newer one however the calls
+     *   interleave. Read the tail before you open a replacement, and read how far it reaches
+     *   inside one `close` emit off the way the lifetime ended. An explicit `close()` still holds
+     *   its teardown barrier while those listeners run, so a `start()` one of them calls parks
+     *   behind it and every later listener reads the ended child's frozen tail. A natural exit
+     *   holds that barrier only across the `error` it reports at that end, so a restart begun
+     *   THERE parks until `close` has been delivered, while a `close` listener that calls
+     *   `start()` opens the next lifetime itself and replaces the value every listener after it
+     *   would have read.
+     * - **What the close path carries.** The frozen value is what the supervisor had received by
+     *   that terminal moment, not the child's complete output.
+     *   Windows ends the tree with `taskkill /F /T`, which nothing in the child can intercept: a
+     *   `SIGTERM` handler never runs there, so the bytes it would have written never exist. A
+     *   child that ends on its own closes its stderr first, and THAT tail is complete.
+     *   Where that moment arrived at the supervisor's `drain` bound rather than at the child's
+     *   own stream close, the tail stops at the cutoff and later diagnostics may have existed;
+     *   the transport emits an `error` naming that lifetime, so a partial tail reads as partial.
+     * - **Bound.** The supervisor keeps the END of the child's raw stderr bytes, at most
+     *   `@orkestrel/process`'s {@link import('@orkestrel/process').PROCESS_EVIDENCE} (2048
+     *   bytes under 0.0.6). A child that writes more than the bound loses its earliest output
+     *   and keeps its last, which is the half that names why it died. The bound counts raw
+     *   bytes before decoding rather than characters, so multibyte output yields fewer
+     *   characters than an ASCII run over the same byte window. The kept bytes never begin
+     *   inside a multibyte sequence: where the cut lands mid-character the start retreats to
+     *   that character's first byte, so the tail decodes without a replacement character and
+     *   can hold a few bytes fewer than the bound.
+     * - **A spawn fault leaves no tail.** A spawn that produced no child wrote no stderr, so
+     *   `evidence` reads `''` for that lifetime. Its cause — the host's `ENOENT` for a command
+     *   that does not resolve — arrives on the `error` event instead.
+     */
+    readonly evidence: string | undefined;
+}
+
 /**
  * Options for `createStdioClientTransport` — the child process to spawn as a
  * stdio-framed MCP server (newline-delimited JSON-RPC over `stdin`/`stdout`).

package/dist/src/server/index.js

@@ -1362,7 +1362,7 @@ var WebSocketClientTransport = class {
 //#region src/server/transports/StdioClientTransport.ts
 /**
 * The stdio CLIENT transport for the Model Context Protocol — a
-* {@link MCPClientTransportInterface} that drives a CHILD PROCESS MCP server over
+* {@link StdioClientTransportInterface} that drives a CHILD PROCESS MCP server over
 * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
 * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
 * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
@@ -1383,16 +1383,32 @@ var WebSocketClientTransport = class {
 *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, and for a write
 *   that failed — so a `false` answer REJECTS here with the same not-connected error a transport
 *   that was never started raises. A dead peer surfaces at the caller instead of vanishing.
-* - **`close()`** releases this transport's line pump without waiting for the child's stdout
-*   iterator, then runs the supervisor's bounded `SIGTERM` → grace → `SIGKILL` group-kill and
-*   teardown before firing `close` once (idempotent). A descendant can retain an inherited stdout
-*   pipe after the child exits; the pump's release barrier keeps that substrate limit from keeping
-*   this transport's `close()` pending. On a POSIX host the child leads its own process group, so
-*   the group-kill reaches its grandchildren rather than orphaning them.
+* - **`close()`** runs the supervisor's bounded termination and teardown, then fires `close` once
+*   (idempotent). That teardown reaches the child's TERMINAL MOMENT, where the supervisor freezes
+*   `evidence`, ends `lines`, and settles `exit` together, so this transport needs no release of
+*   its own to get its line pump back: the stream ends under the pump rather than throwing at it.
+*   A line the supervisor had already framed behind the one being delivered is dropped rather than
+*   emitted onto a transport whose teardown has begun. A `close()` issued while that teardown runs
+*   joins it rather than opening a second one, so it resolves only after `close` has fired, and a
+*   `start()` issued while it runs waits behind the same barrier, so lifetimes never overlap. A
+*   descendant can retain an inherited stdout pipe after the child exits; the supervisor's `drain`
+*   bound cuts that wait off, so this transport's `close()` settles within that bound rather than
+*   on the descendant. The termination itself belongs to the host: a POSIX host signals the
+*   child's own process group `SIGTERM`, waits the grace window, then `SIGKILL`s through the same
+*   route, so the kill reaches grandchildren rather than orphaning them, while Windows ends the
+*   tree with `taskkill /F /T`, which nothing in the child can intercept.
+* - **Evidence.** `evidence` reports that retained stderr tail off the HELD child — its live tail
+*   while the child runs, and the value the supervisor froze at that child's terminal moment
+*   afterwards. The reference is held past that moment and replaced only by the next `start()`,
+*   which is what keeps a post-`close()` read stable without a private copy: the frozen value
+*   never moves again, so a detached descendant writing to the inherited stderr after the cutoff
+*   cannot grow it. See {@link StdioClientTransportInterface.evidence} for the readings and the
+*   byte bound.
 * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
 *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
-*   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
-*   own listener-error channel.
+*   fault, including the child spawn cause the supervisor surfaces and the notice that this
+*   lifetime's `evidence` was cut off at the `drain` bound), distinct from the emitter's own
+*   listener-error channel.
 *
 * @example
 * ```ts
@@ -1407,8 +1423,7 @@ var StdioClientTransport = class {
 	#args;
 	#env;
 	#process = void 0;
-	#release = Promise.withResolvers();
-	#pumping = Promise.resolve();
+	#closing = void 0;
 	#closed = false;
 	constructor(options) {
 		this.#emitter = new Emitter();
@@ -1423,10 +1438,21 @@ var StdioClientTransport = class {
 	get duplex() {
 		return true;
 	}
+	get evidence() {
+		return this.#process?.evidence;
+	}
 	async start() {
-		if (this.#process !== void 0) return;
+		let closing = this.#closing;
+		while (closing !== void 0) {
+			await closing;
+			if (this.#closing === closing) {
+				this.#closing = void 0;
+				break;
+			}
+			closing = this.#closing;
+		}
+		if (this.#process !== void 0 && !this.#closed) return;
 		this.#closed = false;
-		this.#release = Promise.withResolvers();
 		const child = new Process({
 			command: {
 				file: this.#command,
@@ -1439,39 +1465,49 @@ var StdioClientTransport = class {
 		});
 		this.#process = child;
 		child.emitter.on("error", (cause) => this.#emitter.emit("error", cause));
-		child.exit.then(() => this.#onExit(child));
-		this.#pumping = this.#pump(child, this.#release.promise);
+		child.exit.then((exit) => this.#onExit(child, exit));
+		this.#pump(child);
 	}
 	async send(message) {
-		const child = this.#process;
+		const child = this.#closed ? void 0 : this.#process;
 		if (!(child === void 0 ? false : await child.send(JSON.stringify(message)))) throw new Error("stdio transport is not connected");
 	}
 	async close() {
+		if (this.#closed && this.#closing === void 0) return;
+		this.#closing ??= this.#teardown();
+		await this.#closing;
+	}
+	async #teardown() {
 		if (this.#closed) return;
 		this.#closed = true;
 		const child = this.#process;
-		const pumping = this.#pumping;
-		this.#release.resolve();
-		this.#process = void 0;
-		if (child !== void 0) await child.destroy();
-		await pumping;
+		if (child !== void 0) {
+			await child.destroy();
+			this.#report(await child.exit);
+		}
 		this.#emitter.emit("close");
 	}
-	async #pump(child, release) {
-		const iterator = child.lines[Symbol.asyncIterator]();
-		while (true) {
-			const next = await Promise.race([iterator.next(), release]);
-			if (next === void 0 || next.done) return;
-			if (this.#process !== child) return;
-			dispatchLines(this.#emitter, [next.value]);
+	async #pump(child) {
+		for await (const line of child.lines) {
+			if (this.#closed || this.#process !== child) return;
+			dispatchLines(this.#emitter, [line]);
 		}
 	}
-	#onExit(child) {
-		if (this.#closed || this.#process !== child) return;
+	#onExit(child, exit) {
+		if (this.#process !== child) return;
+		if (this.#closed) return;
 		this.#closed = true;
-		this.#process = void 0;
+		const barrier = Promise.withResolvers();
+		this.#closing ??= barrier.promise;
+		this.#report(exit);
+		barrier.resolve();
+		if (this.#closing === barrier.promise) this.#closing = void 0;
 		this.#emitter.emit("close");
 	}
+	#report(exit) {
+		if (exit.drained) return;
+		this.#emitter.emit("error", /* @__PURE__ */ new Error("stdio transport evidence may be incomplete: the child streams stayed open past the supervisor drain bound"));
+	}
 };
 //#endregion
 //#region src/server/transports/StdioServerTransport.ts
@@ -1816,22 +1852,24 @@ function createWebSocketClientTransport(options) {
 }
 /**
 * Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
-* — a {@link MCPClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+* — a {@link StdioClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
 * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
 * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
 *
 * @remarks
 * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
 * spawns `options.command` with `options.args` and `options.env`, piping its
-* `stdin`/`stdout` for the JSON-RPC channel (its `stderr` inherits the parent's for
-* diagnostics). Each JSON-RPC message the client `send`s is written as one
+* `stdin`/`stdout` for the JSON-RPC channel. The child's `stderr` is piped too, and
+* retained as a bounded tail this transport reports as `evidence` — the parent never
+* inherits it. Each JSON-RPC message the client `send`s is written as one
 * newline-terminated line to the child's `stdin`; each decoded reply line from the
 * child's `stdout` is surfaced on the transport's `message` event for the client's
 * id correlation.
 *
 * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
 *   and optional `env`; see {@link StdioClientTransportOptions}
-* @returns A working {@link MCPClientTransportInterface} over a child process's stdio
+* @returns A working {@link StdioClientTransportInterface} over a child process's stdio,
+*   whose `evidence` carries the supervised child's bounded stderr tail
 *
 * @example
 * ```ts