@orkestrel/mcp 0.0.20 → 0.0.22

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

@@ -324,22 +324,28 @@ 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.
+ * id correlation. That write is bounded: a child that stays alive without ever reading
+ * its `stdin` fills the pipe, and `options.delivery` is how long the unconfirmed write
+ * waits before the `send` rejects. An omitted `delivery` selects {@link
+ * import('./constants.js').DEFAULT_MCP_DELIVERY}; an explicit `0` removes the bound.
  *
  * @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
+ *   optional `env`, and an optional `delivery` bound in milliseconds on an unconfirmed
+ *   `stdin` write; see {@link StdioClientTransportOptions}
+ * @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 +359,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
@@ -496,6 +502,19 @@ export declare function createWebSocketServer(mcp: MCPDispatcherInterface, optio
  */
 export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
 
+/**
+ * The default bound in milliseconds on one unconfirmed write to a stdio client transport's
+ * child `stdin` — the `delivery` a `createStdioClientTransport` caller who supplies none gets.
+ *
+ * @remarks
+ * Ten seconds. The load-bearing property is the ordering, not the magnitude: this bound stays
+ * BELOW {@link import('@orkestrel/mcp').DEFAULT_MCP_REQUEST_TIMEOUT}, so a write the child never
+ * reads fails as an undeliverable message while the request that carried it is still open,
+ * rather than being masked by that request's own deadline expiring first. Override per
+ * transport with `delivery`; an explicit `0` there removes the bound.
+ */
+export declare const DEFAULT_MCP_DELIVERY = 10000;
+
 /**
  * The default interval in milliseconds between SSE keepalive comments on held-open MCP
  * responses.
@@ -1242,7 +1261,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}.
@@ -1260,19 +1279,36 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
  *   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
  *   host reports the line handled rather than the moment the write is queued. The supervisor never
- *   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.
+ *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, for a write
+ *   that failed, or for one that remained unconfirmed through `delivery`. A call made without a
+ *   live child rejects as not connected; a `false` answer from a live child rejects as unable to
+ *   deliver. The supervisor does not disclose which cause produced that answer.
+ * - **`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 +1317,96 @@ 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>;
+    /**
+     * Sends one newline-delimited JSON-RPC message to the live child.
+     *
+     * @param message - The message to write to the child's `stdin`
+     * @returns Resolves when the supervisor confirms the write
+     * @throws Thrown with `stdio transport is not connected` when no live child is available before
+     *   the write
+     * @throws Thrown with `stdio transport could not deliver the message` when a live child's write
+     *   resolves `false`
+     */
     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`).
@@ -1304,11 +1419,34 @@ export declare class StdioClientTransport implements MCPClientTransportInterface
  *   OMITTED the child inherits the full `process.env`, when PROVIDED each named key overrides
  *   the inherited value while every unlisted key is still inherited. This transport cannot
  *   REPLACE the inherited environment entirely — the supervisor always merges over the parent.
+ * - `delivery` — the bound in milliseconds on one unconfirmed write to the child's `stdin`;
+ *   an explicit `0` opts out. Defaults to {@link import('./constants.js').DEFAULT_MCP_DELIVERY}.
  */
 export declare interface StdioClientTransportOptions {
     readonly command: string;
     readonly args?: readonly string[];
     readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Bounds the wait on one unconfirmed `send` write to the child's `stdin`, in milliseconds.
+     *
+     * @remarks
+     * A full pipe is the case this bounds: a live child that never reads its `stdin` leaves the
+     * kernel unable to confirm the write, and the supervisor holds that write open. When the
+     * window elapses the supervisor answers that write `false`, which this transport surfaces as
+     * a rejection, so the caller learns the message did not land instead of waiting on a peer
+     * that will never read it. Default: {@link import('./constants.js').DEFAULT_MCP_DELIVERY}.
+     *
+     * An explicit `0` opts out: the bound is off, and an unconfirmed write stays pending until
+     * the channel faults or teardown settles it. Omission does NOT opt out here, which is where
+     * this option diverges from the supervisor's own `delivery` on {@link
+     * import('@orkestrel/process').ProcessOptions} — omitted THERE disables the bound, omitted
+     * HERE selects the default.
+     *
+     * An out-of-range value surfaces at `start()` rather than at construction. This transport
+     * forwards the value verbatim and adds no validator of its own, so the supervisor's own timer
+     * range is what rejects it, at the moment it spawns the child.
+     */
+    readonly delivery?: number;
 }
 
 /**

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

@@ -324,22 +324,28 @@ 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.
+ * id correlation. That write is bounded: a child that stays alive without ever reading
+ * its `stdin` fills the pipe, and `options.delivery` is how long the unconfirmed write
+ * waits before the `send` rejects. An omitted `delivery` selects {@link
+ * import('./constants.js').DEFAULT_MCP_DELIVERY}; an explicit `0` removes the bound.
  *
  * @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
+ *   optional `env`, and an optional `delivery` bound in milliseconds on an unconfirmed
+ *   `stdin` write; see {@link StdioClientTransportOptions}
+ * @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 +359,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
@@ -496,6 +502,19 @@ export declare function createWebSocketServer(mcp: MCPDispatcherInterface, optio
  */
 export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
 
+/**
+ * The default bound in milliseconds on one unconfirmed write to a stdio client transport's
+ * child `stdin` — the `delivery` a `createStdioClientTransport` caller who supplies none gets.
+ *
+ * @remarks
+ * Ten seconds. The load-bearing property is the ordering, not the magnitude: this bound stays
+ * BELOW {@link import('@orkestrel/mcp').DEFAULT_MCP_REQUEST_TIMEOUT}, so a write the child never
+ * reads fails as an undeliverable message while the request that carried it is still open,
+ * rather than being masked by that request's own deadline expiring first. Override per
+ * transport with `delivery`; an explicit `0` there removes the bound.
+ */
+export declare const DEFAULT_MCP_DELIVERY = 10000;
+
 /**
  * The default interval in milliseconds between SSE keepalive comments on held-open MCP
  * responses.
@@ -1242,7 +1261,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}.
@@ -1260,19 +1279,36 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
  *   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
  *   host reports the line handled rather than the moment the write is queued. The supervisor never
- *   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.
+ *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, for a write
+ *   that failed, or for one that remained unconfirmed through `delivery`. A call made without a
+ *   live child rejects as not connected; a `false` answer from a live child rejects as unable to
+ *   deliver. The supervisor does not disclose which cause produced that answer.
+ * - **`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 +1317,96 @@ 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>;
+    /**
+     * Sends one newline-delimited JSON-RPC message to the live child.
+     *
+     * @param message - The message to write to the child's `stdin`
+     * @returns Resolves when the supervisor confirms the write
+     * @throws Thrown with `stdio transport is not connected` when no live child is available before
+     *   the write
+     * @throws Thrown with `stdio transport could not deliver the message` when a live child's write
+     *   resolves `false`
+     */
     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`).
@@ -1304,11 +1419,34 @@ export declare class StdioClientTransport implements MCPClientTransportInterface
  *   OMITTED the child inherits the full `process.env`, when PROVIDED each named key overrides
  *   the inherited value while every unlisted key is still inherited. This transport cannot
  *   REPLACE the inherited environment entirely — the supervisor always merges over the parent.
+ * - `delivery` — the bound in milliseconds on one unconfirmed write to the child's `stdin`;
+ *   an explicit `0` opts out. Defaults to {@link import('./constants.js').DEFAULT_MCP_DELIVERY}.
  */
 export declare interface StdioClientTransportOptions {
     readonly command: string;
     readonly args?: readonly string[];
     readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Bounds the wait on one unconfirmed `send` write to the child's `stdin`, in milliseconds.
+     *
+     * @remarks
+     * A full pipe is the case this bounds: a live child that never reads its `stdin` leaves the
+     * kernel unable to confirm the write, and the supervisor holds that write open. When the
+     * window elapses the supervisor answers that write `false`, which this transport surfaces as
+     * a rejection, so the caller learns the message did not land instead of waiting on a peer
+     * that will never read it. Default: {@link import('./constants.js').DEFAULT_MCP_DELIVERY}.
+     *
+     * An explicit `0` opts out: the bound is off, and an unconfirmed write stays pending until
+     * the channel faults or teardown settles it. Omission does NOT opt out here, which is where
+     * this option diverges from the supervisor's own `delivery` on {@link
+     * import('@orkestrel/process').ProcessOptions} — omitted THERE disables the bound, omitted
+     * HERE selects the default.
+     *
+     * An out-of-range value surfaces at `start()` rather than at construction. This transport
+     * forwards the value verbatim and adds no validator of its own, so the supervisor's own timer
+     * range is what rejects it, at the moment it spawns the child.
+     */
+    readonly delivery?: number;
 }
 
 /**