@orkestrel/mcp 0.0.18 → 0.0.20

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

@@ -55,17 +55,17 @@ export declare function acceptsEventStream(request: Request): boolean;
 export declare function allowsOrigin(request: Request, options?: MCPOriginOptions): boolean;
 
 /**
- * Bridge a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
+ * Bridges a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
  * WebSocket SERVER transports already implement) into the environment-agnostic
- * {@link import('@src/core').MCPTransportInterface} port — the adapter
+ * {@link import('@orkestrel/mcp').MCPTransportInterface} port — the adapter
  * {@link import('./factories.js').createStdioServer} and {@link
  * import('./factories.js').createWebSocketServer} pipe through `bindServer`, so the
- * request/reply/error pump those two factories used to hand-roll identically now
+ * request/reply/error pump those factories used to hand-roll identically now
  * lives ONCE in the core binder.
  *
  * @remarks
  * `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
- * and writes it via `transport.send` (the SAME `JSON.stringify` the underlying
+ * and writes it through `transport.send` (the same `JSON.stringify` the underlying
  * transport already performs, so the wire bytes are unchanged). `listen` filters
  * `transport`'s `message` event to INVOCATIONS ONLY — requests and notifications, never a
  * stray response, exactly as the prior hand-rolled pumps did — and re-serializes each one
@@ -83,24 +83,24 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  * decode rather than after it. Removing the cost means giving `MCPTransportInterface` a
  * message-shaped face beside its string one, which every transport would then carry.
  *
- * @remarks Per {@link import('@src/core').MCPTransportInterface}, `listen`/`closed`
+ * @remarks Per {@link import('@orkestrel/mcp').MCPTransportInterface}, `listen`/`closed`
  * each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
- * Since the underlying `transport.emitter` is ADD-based (`on` subscribes, never
+ * Because the underlying `transport.emitter` is ADD-based (`on` subscribes, never
  * replaces), this bridge installs ONE stable emitter listener per event on first use
- * and re-routes it to whichever handler is CURRENTLY registered (`undefined` while
+ * and re-routes it to whichever handler is active (`undefined` while
  * none is), so rebinding never double-dispatches.
  *
- * @remarks A response whose `result` serializes away (e.g. `undefined`) is dropped by
+ * @remarks A response whose `result` serializes away (for example, `undefined`) is dropped by
  * the message validators on the wire's decode side — an asymmetry the stdio/WS carrier
- * shares with the streamable-HTTP face, since both round-trip through `JSON.stringify`
+ * shares with the streamable-HTTP face, because both round-trip through `JSON.stringify`
  * / `JSON.parse` before re-validation.
  *
  * @param transport - The message-channel transport to bridge (stdio or WebSocket)
- * @returns An {@link import('@src/core').MCPTransportInterface} `bindServer` can drive
+ * @returns An {@link import('@orkestrel/mcp').MCPTransportInterface} `bindServer` can drive
  *
  * @example
  * ```ts
- * import { bindServer } from '@src/core'
+ * import { bindServer } from '@orkestrel/mcp'
  *
  * const transport = new StdioServerTransport(process.stdin, process.stdout)
  * bindServer(mcp, bridgeMessageTransport(transport))
@@ -109,7 +109,7 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
 export declare function bridgeMessageTransport(transport: MCPClientTransportInterface): MCPTransportInterface;
 
 /**
- * Create the HTTP CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+ * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
  * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
  * over `fetch`. The egress mirror of {@link createMCPRoutes}.
  *
@@ -117,9 +117,9 @@ export declare function bridgeMessageTransport(transport: MCPClientTransportInte
  * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client sends is
  * `POST`ed to `options.url` with `content-type: application/json` and an `Accept` of
  * both `application/json` and `text/event-stream` (the server answers with EITHER — a
- * plain JSON envelope or a Streamable-HTTP SSE `data:` event, decoded via `@orkestrel/sse`),
+ * plain JSON envelope or a Streamable-HTTP SSE `data:` event, decoded with `@orkestrel/sse`),
  * and the reply is surfaced on the transport's `message` event for the client's id
- * correlation. Add `options.headers` (e.g. an `Authorization` bearer) to reach a guarded
+ * correlation. Add `options.headers` (for example, an `Authorization` bearer) to reach a guarded
  * server. `start` / `close` hold no connection; against a STATEFUL server it captures the
  * `mcp-session-id` from `initialize` and echoes it on later requests. It also captures
  * the initialize result's `protocolVersion` and sends `mcp-protocol-version` alone on each
@@ -128,13 +128,13 @@ export declare function bridgeMessageTransport(transport: MCPClientTransportInte
  *
  * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
  *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
- *   (ms, applied via `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
+ *   (ms, applied with `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
  * @returns A working {@link MCPClientTransportInterface} over `fetch`
  *
  * @example
  * ```ts
- * import { createMCPClient } from '@src/core'
- * import { createHTTPClientTransport } from '@src/server'
+ * import { createMCPClient } from '@orkestrel/mcp'
+ * import { createHTTPClientTransport } from '@orkestrel/mcp/server'
  *
  * const client = createMCPClient({
  * 	transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
@@ -146,7 +146,7 @@ export declare function bridgeMessageTransport(transport: MCPClientTransportInte
 export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPClientTransportInterface;
 
 /**
- * Adapt the installed server token primitives to the host-neutral MCP continuation port.
+ * Adapts the installed server token primitives to the host-neutral MCP continuation port.
  *
  * @param secret - Current signing secret or `[current, ...older]` rotation list
  * @returns A continuation port that seals and opens opaque canonical state strings
@@ -154,7 +154,7 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
 export declare function createMCPContinuation(secret: TokenSecret): MCPContinuationInterface;
 
 /**
- * Create the Streamable-HTTP POST handler used by `createMCPRoutes`.
+ * Creates the Streamable-HTTP POST handler used by `createMCPRoutes`.
  *
  * @remarks
  * Modern requests require matching protocol/method headers and a matching name header only
@@ -180,7 +180,7 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
  * import { createToolManager } from '@orkestrel/tool'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * const handler = createMCPPostHandler(createMCPLegacy(mcp), { streaming: true })
+ * const handler = createMCPPostHandler(createMCPLegacy(mcp), { streaming: true }) // answers `initialize` too; pass `mcp` alone for modern-only
  * await handler(new Request('http://localhost/mcp', {
  * 	method: 'POST',
  * 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
@@ -190,8 +190,8 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
 export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPHandlerOptions<TState>): (request: Request, context?: RouteContext<string, TState>) => Promise<Response>;
 
 /**
- * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
- * {@link MCPDispatcherInterface} (the `@src/core` dispatch boundary) on the fetch-standard router
+ * Creates the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
+ * {@link MCPDispatcherInterface} (the `@orkestrel/mcp` dispatch boundary) on the fetch-standard router
  * spine, pumping each `POST` body through `mcp.dispatch`. Returns the {@link RouteInput}s to
  * hand to `router.add(...)`.
  *
@@ -214,7 +214,7 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  *
  * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
  * the `200` reply is framed as a Streamable-HTTP SSE response (one `data:` event carrying
- * the JSON-RPC envelope, then the stream ends) via `@orkestrel/server`'s generic
+ * the JSON-RPC envelope, then the stream ends) through `@orkestrel/server`'s generic
  * {@link import('@orkestrel/server').openStream} seam; otherwise it is a plain JSON body.
  *
  * **Sessions are a SEPARATE, plug-and-play middleware.** `createMCPRoutes` mints / reads no
@@ -236,19 +236,20 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  *
  * @example
  * ```ts
- * import { createMCPLegacy, createMCPServer, createToolManager } from '@src/core'
- * import { createMCPRoutes } from '@src/server'
+ * import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+ * import { createMCPRoutes } from '@orkestrel/mcp/server'
+ * import { createToolManager } from '@orkestrel/tool'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * const routes = createMCPRoutes(createMCPLegacy(mcp)) // both eras; pass `mcp` for modern only
+ * const routes = createMCPRoutes(createMCPLegacy(mcp)) // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
 export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInterface, options?: HTTPTransportOptions<TState>): ReadonlyArray<RouteInput<string, TState>>;
 
 /**
- * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
+ * Creates the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
  * that fronts a session-agnostic {@link import('./factories.js').createMCPRoutes}. Compose it
- * via `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
+ * with `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
  * other closure-scoped stateful middleware. Has NO dependency on `@orkestrel/middleware` — the
  * session store, mint-on-`initialize`, and resumable stream are all native to this package.
  *
@@ -257,11 +258,11 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  * `path` (default {@link DEFAULT_MCP_PATH}); a request to any other path passes straight
  * through (`next()`).
  *
- * A modern-shaped POST also passes straight through via `next()`, ignoring any session id.
+ * A modern-shaped POST also passes straight through with `next()`, ignoring any session id.
  * The remaining behavior is the legacy session layer:
  *
  * - **`POST {path}`.** Buffers `const text = await request.text()` (so the downstream route
- *   can re-read it via a freshly-built forwarded `Request`). Resolves a session via {@link
+ *   can re-read it from a freshly-built forwarded `Request`). Resolves a session through {@link
  *   readSessionHeader}: a VALID id touches the entry and sets `context.state.session`; an
  *   ABSENT / unknown id whose (guarded) body parses to an `initialize` request ({@link
  *   isInitializeRequest}) MINTS a fresh {@link MCPSession} (`crypto.randomUUID()`, `capacity`)
@@ -276,7 +277,7 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  *   a `DELETE` arriving while the request was suspended is not undone.
  * - **`GET {path}`.** Resolves the session the same way (no mint — only `initialize` mints);
  *   an invalid / unknown id is the same `404`. A valid session opens the resumable
- *   server→client stream via `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
+ *   server→client stream through `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
  *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
  *   attaching the stream for live pushes, then attaches; cancellation of the streamed response
  *   body composes with `request.signal` and detaches it. Long-lived — never `end()`ed here.
@@ -300,18 +301,20 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  *
  * @example
  * ```ts
- * import { createMCPServer, createToolManager } from '@src/core'
- * import { createMCPRoutes, createMCPSession } from '@src/server'
+ * import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+ * import { createMCPRoutes, createMCPSession } from '@orkestrel/mcp/server'
+ * import { createToolManager } from '@orkestrel/tool'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
  * router.use(createMCPSession({ ttl: 60_000 })) // stateful: mint + validate + resumable GET / DELETE
- * router.add(createMCPRoutes(mcp)) // the route stays session-agnostic
+ * // The route stays session-agnostic:
+ * router.add(createMCPRoutes(createMCPLegacy(mcp))) // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
 export declare function createMCPSession<TState extends MCPSessionState>(options?: MCPSessionOptions): MiddlewareHandler<TState>;
 
 /**
- * Create a readable stream from its pull and cancellation behaviours.
+ * Creates a readable stream from its pull and cancellation behaviours.
  *
  * @param pull - The behaviour that supplies the stream's next chunk
  * @param cancel - The behaviour that releases the stream after consumer cancellation
@@ -320,7 +323,7 @@ export declare function createMCPSession<TState extends MCPSessionState>(options
 export declare function createReadableStream<T>(pull: (controller: ReadableStreamDefaultController<T>) => void | PromiseLike<void>, cancel: (reason?: unknown) => void | PromiseLike<void>): ReadableStream<T>;
 
 /**
- * Create the stdio CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+ * Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
  * — a {@link MCPClientTransportInterface} 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}.
@@ -340,8 +343,8 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
  *
  * @example
  * ```ts
- * import { createMCPClient } from '@src/core'
- * import { createStdioClientTransport } from '@src/server'
+ * import { createMCPClient } from '@orkestrel/mcp'
+ * import { createStdioClientTransport } from '@orkestrel/mcp/server'
  *
  * const client = createMCPClient({
  * 	transport: createStdioClientTransport({ command: 'node', args: ['./server.js'] }),
@@ -353,16 +356,16 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
 export declare function createStdioClientTransport(options: StdioClientTransportOptions): MCPClientTransportInterface;
 
 /**
- * Create the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
+ * Creates the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
  * MCPDispatcherInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
  * injected stream pair), the stdio mirror of {@link createWebSocketServer}.
  *
  * @remarks
  * Wraps `options.input` (default `process.stdin`) / `options.output` (default
  * `process.stdout`) in a {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
- * and pipes it through the core {@link import('@src/core').MCPTransportInterface} port
- * via {@link import('./helpers.js').bridgeMessageTransport} + {@link
- * import('@src/core').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
+ * and pipes it through the core {@link import('@orkestrel/mcp').MCPTransportInterface} port
+ * through {@link import('./helpers.js').bridgeMessageTransport} + {@link
+ * import('@orkestrel/mcp').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
  * a defined response is written back as a newline-terminated line — a NOTIFICATION
  * writes nothing, and a non-request message is ignored. A `dispatch` / `send` fault
  * surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
@@ -375,11 +378,13 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  *
  * @example
  * ```ts
- * import { createMCPServer, createToolManager } from '@src/core'
- * import { createStdioServer } from '@src/server'
+ * import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+ * import { createStdioServer } from '@orkestrel/mcp/server'
+ * import { createToolManager } from '@orkestrel/tool'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * createStdioServer(mcp).start() // an MCP client now connects over this process's stdio
+ * // An MCP client now connects over this process's stdio:
+ * createStdioServer(createMCPLegacy(mcp)).start() // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
 export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): {
@@ -388,7 +393,7 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
 };
 
 /**
- * Create the WebSocket CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+ * Creates the WebSocket CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
  * — a {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
  * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
  * createHTTPClientTransport}.
@@ -397,11 +402,11 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
  * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`) performs
  * the RFC 6455 client handshake against `options.url` (accepting a `ws://` / `wss://` or an
  * `http://` / `https://` URL — a `ws(s)` scheme is converted to `http(s)` for the underlying
- * upgrade request), validates the `Sec-WebSocket-Accept` (via `@orkestrel/websocket`'s
+ * upgrade request), validates the `Sec-WebSocket-Accept` (with `@orkestrel/websocket`'s
  * `computeWebSocketAccept`), and opens a persistent bidirectional frame channel; each JSON-RPC
  * message the client `send`s is written as one masked text frame, and each decoded reply is
  * surfaced on the transport's `message` event for the client's id correlation. Add
- * `options.headers` (e.g. an `Authorization` bearer) to reach a guarded server.
+ * `options.headers` (for example, an `Authorization` bearer) to reach a guarded server.
  *
  * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
  *   merged onto the upgrade request; see {@link WebSocketClientTransportOptions}
@@ -409,8 +414,8 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
  *
  * @example
  * ```ts
- * import { createMCPClient } from '@src/core'
- * import { createWebSocketClientTransport } from '@src/server'
+ * import { createMCPClient } from '@orkestrel/mcp'
+ * import { createWebSocketClientTransport } from '@orkestrel/mcp/server'
  *
  * const client = createMCPClient({
  * 	transport: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
@@ -422,7 +427,7 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
 export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPClientTransportInterface;
 
 /**
- * Create the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
+ * Creates the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
  * transport-agnostic {@link MCPDispatcherInterface} over a WebSocket, the WebSocket mirror of
  * {@link createMCPRoutes}. Register it on the spine's upgrade seam.
  *
@@ -437,11 +442,11 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *   A decline NEVER writes to the socket (it is not yet ours) — the spine owns the unclaimed
  *   outcome.
  * - **Claims (returns `true`)** otherwise: it builds `createNodeWebSocket({ socket, key, head,
- *   protocol })` (SERVER mode → writes the `101` handshake, echoing the `subprotocol`, default
- *   {@link MCP_WEBSOCKET_SUBPROTOCOL} `'mcp'`, and sends UNMASKED frames), wraps it in a
+ *   protocol })` (SERVER mode → writes the `101` handshake, selects the configured subprotocol
+ *   only when the client's offer contains it, and sends UNMASKED frames), wraps it in a
  *   {@link WebSocketServerTransport}, and pipes it through the core {@link
- *   import('@src/core').MCPTransportInterface} port via {@link
- *   import('./helpers.js').bridgeMessageTransport} + {@link import('@src/core').bindServer}:
+ *   import('@orkestrel/mcp').MCPTransportInterface} port through {@link
+ *   import('./helpers.js').bridgeMessageTransport} + {@link import('@orkestrel/mcp').bindServer}:
  *   each inbound REQUEST runs through `mcp.dispatch`, and a defined response is written back
  *   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
  *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
@@ -466,23 +471,25 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *
  * @example
  * ```ts
- * import { createMCPServer, createToolManager } from '@src/core'
- * import { createWebSocketServer } from '@src/server'
+ * import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
+ * import { createWebSocketServer } from '@orkestrel/mcp/server'
+ * import { createToolManager } from '@orkestrel/tool'
  *
  * const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
- * server.upgrade(createWebSocketServer(mcp, { emitter: server.emitter })) // ws://…/mcp
+ * // Claims the MCP upgrade at ws://…/mcp:
+ * server.upgrade(createWebSocketServer(createMCPLegacy(mcp), { emitter: server.emitter })) // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
 export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options: WebSocketServerOptions): UpgradeHandler;
 
 /**
- * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
+ * Decodes one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
  * when it is not one — the per-event step {@link readEventStream} folds over.
  *
  * @remarks
  * `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the event's
  * `data`) inside a try/catch and narrows the parsed value with `parseJSONRPCMessage`.
- * Total (§14): malformed JSON or a non-message value yields `undefined`, never throws.
+ * Total: malformed JSON or a non-message value yields `undefined`, never throws.
  *
  * @param data - One SSE event's `data` payload
  * @returns The decoded {@link JSONRPCMessage}, or `undefined`
@@ -528,19 +535,20 @@ export declare const DEFAULT_MCP_SESSION_CAPACITY = 1024;
 export declare const DEFAULT_MCP_SESSION_TTL = 300000;
 
 /**
- * Decode and deliver each complete newline-framed line onto a {@link
+ * Decodes and delivers each complete newline-framed line onto a {@link
  * MCPClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
- * transports (client and server) run their {@link extractLines} output through.
+ * transports run their framed lines through: the server transport frames with {@link
+ * extractLines}, the client transport takes its lines from the process supervisor.
  *
  * @remarks
  * A blank line is skipped (a stray trailing newline). Every other line is decoded
  * with {@link decodeEvent} (`JSON.parse` + `parseJSONRPCMessage`, guarded); a
  * well-formed {@link JSONRPCMessage} emits `message`, a malformed / non-message line
- * emits `error` (§14 — total, never throws). Pure w.r.t. its own state — the emit is
+ * emits `error` (total, never throws). Pure w.r.t. its own state — the emit is
  * the caller-owned side effect.
  *
  * @param emitter - The transport's {@link EmitterInterface} to emit `message` / `error` onto
- * @param lines - The complete lines (from {@link extractLines}) to decode and deliver
+ * @param lines - The complete lines to decode and deliver
  */
 export declare function dispatchLines(emitter: EmitterInterface<MCPClientTransportEventMap>, lines: readonly string[]): void;
 
@@ -555,7 +563,7 @@ export declare function dispatchLines(emitter: EmitterInterface<MCPClientTranspo
  * - `message` — the server→client {@link JSONRPCMessage} that was pushed.
  * - `timestamp` — the epoch-ms instant the entry was appended, read by the TTL eviction.
  *
- * A plain value record (no behavior, §4.5) — the unit {@link MCPSessionInterface.replay}
+ * A plain value record (no behavior) — the unit {@link MCPSessionInterface.replay}
  * returns.
  */
 export declare interface EventStoreEntry {
@@ -565,7 +573,7 @@ export declare interface EventStoreEntry {
 }
 
 /**
- * Fold one more chunk of raw stdio bytes into a newline-framed buffer — the shared
+ * Folds one more chunk of raw stdio bytes into a newline-framed buffer — the shared
  * line-framing step both stdio transports (client and server) read their inbound
  * newline-delimited JSON-RPC messages through.
  *
@@ -592,12 +600,12 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
  *   message to `options.url` with `content-type: application/json` and an
  *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
- *   answer with either framing) — plus any `options.headers` (e.g. an `Authorization`
+ *   answer with either framing) — plus any `options.headers` (for example, an `Authorization`
  *   bearer). It then decodes the reply and emits each decoded {@link JSONRPCMessage} on
- *   the `message` event the {@link import('@src/core').MCPClientInterface} subscribes
+ *   the `message` event the {@link import('@orkestrel/mcp').MCPClientInterface} subscribes
  *   to.
  * - **Both reply framings.** A `200` with an `application/json` body is parsed with
- *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded via the
+ *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded with the
  *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} ({@link
  *   readEventStream}) — the inverse of the server's `openStream` seam, so the wire
  *   round-trips. A `202`
@@ -615,10 +623,15 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   Before initialize returns, neither captured legacy header is sent.
  *   `close()` clears the captured protocol so a reconnect's `initialize`
  *   POST is headerless; the captured `session` persists across `close()`.
- * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
+ * - **`close()` releases what is in flight.** Every `fetch` this transport still has open is
+ *   ABORTED, which cancels the response body a `send` is reading — an SSE reply the server
+ *   never ends would otherwise outlive the transport, with nothing left able to reach it. The
+ *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
+ *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
+ * - **Total at the boundary.** Every reply is narrowed (`parseJSONRPCMessage`,
  *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /
  *   decode failure surfaces on the `error` event rather than escaping `send`.
- * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
+ * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
  *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
  *
  * @example
@@ -645,9 +658,9 @@ export declare class HTTPClientTransport implements MCPClientTransportInterface_
  *
  * @remarks
  * - `url` — the absolute URL of the remote server's Streamable-HTTP endpoint (the
- *   `POST` target every JSON-RPC message is written to, e.g.
+ *   `POST` target every JSON-RPC message is written to, for example,
  *   `http://localhost:3000/mcp`). REQUIRED.
- * - `headers` — extra request headers merged onto every `POST` (e.g. an
+ * - `headers` — extra request headers merged onto every `POST` (for example, an
  *   `Authorization` bearer for a guarded server). The transport always sets
  *   `content-type: application/json` and an `Accept` of both `application/json` and
  *   `text/event-stream` (so the server may answer with either framing); a key supplied
@@ -655,8 +668,10 @@ export declare class HTTPClientTransport implements MCPClientTransportInterface_
  * - `fetch` — the `fetch` implementation to issue each `POST` with; defaults to
  *   `globalThis.fetch`. Injectable for a test double or a non-global `fetch`.
  * - `timeout` — an optional per-request timeout in milliseconds; when set, each
- *   `fetch` call is issued with `signal: AbortSignal.timeout(timeout)`. Omit for no
- *   transport-level deadline.
+ *   `fetch` call composes that deadline with the transport's own close through
+ *   `AbortSignal.any([close, AbortSignal.timeout(timeout)])`, so whichever fires first
+ *   ends the request. Omit for no transport-level deadline; the close signal is passed
+ *   either way.
  */
 export declare interface HTTPClientTransportOptions {
     readonly url: string;
@@ -666,7 +681,7 @@ export declare interface HTTPClientTransportOptions {
 }
 
 /**
- * Compose one incoming HTTP request lifetime with one MCP-owned SSE response lifetime.
+ * Composes one incoming HTTP request lifetime with one MCP-owned SSE response lifetime.
  *
  * @remarks
  * The composed {@link signal} observes request abort and EVERY way this response can end
@@ -680,7 +695,8 @@ export declare interface HTTPClientTransportOptions {
  *
  * {@link bridge} preserves the source response status and headers, forwards its body bytes, and
  * owns keepalive comments plus listener/timer cleanup until upstream completion, request abort,
- * or consumer cancellation. This is a single-response lifecycle object, not a reusable bridge.
+ * or consumer cancellation. This is a single-response lifecycle object, not a reusable bridge:
+ * a second {@link bridge} call THROWS rather than arming a second keepalive over one lifecycle.
  * It supplies no handler or session policy.
  *
  * The keepalive interval is a BUDGET, sanitized like every other numeric knob in this package:
@@ -702,7 +718,7 @@ export declare interface HTTPClientTransportOptions {
 export declare class HTTPDisconnect {
     #private;
     /**
-     * Create the lifecycle composition for one request and its future SSE response.
+     * Creates the lifecycle composition for one request and its future SSE response.
      *
      * @param signal - The incoming request signal
      * @param options - Optional keepalive `interval` in milliseconds; an invalid value falls back
@@ -717,7 +733,7 @@ export declare class HTTPDisconnect {
      */
     get signal(): AbortSignal;
     /**
-     * Bridge one open SSE response through cancellation-aware byte forwarding and keepalives.
+     * Bridges one open SSE response through cancellation-aware byte forwarding and keepalives.
      *
      * Consumer cancellation, a read failure while forwarding, and a keepalive tick that finds the
      * SSE stream already closed each abort {@link signal}; consumer cancellation also cancels the
@@ -726,7 +742,8 @@ export declare class HTTPDisconnect {
      *
      * @param stream - The open SSE stream whose response will be consumed by the HTTP writer
      * @returns A one-use response preserving status, status text, headers, and SSE body bytes
-     * @throws When the supplied SSE response has no body
+     * @throws When this disconnect has already bridged a stream, or the supplied SSE response
+     *   has no body
      */
     bridge(stream: StreamInterface): Response;
 }
@@ -765,7 +782,7 @@ export declare interface HTTPHandlerOptions<TState = unknown> {
 /**
  * Options for `createMCPRoutes` — the mount path plus the shared POST-handler options.
  * `createMCPRoutes` is STATELESS; sessions are a separate middleware ({@link
- * import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ * import('./middlewares.js').createMCPSession}), composed with `server.use`.
  *
  * @remarks
  * `path` is the request path the single `POST` route answers; it defaults to {@link
@@ -779,7 +796,7 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
 }
 
 /**
- * Infer the first required MCP HTTP header that is missing or mismatched.
+ * Infers the first required MCP HTTP header that is missing or mismatched.
  *
  * @remarks
  * A modern request derives its protocol, method, and tools/call-only name expectations from
@@ -800,7 +817,7 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
 export declare function inferHeaderIssue(request: Request, reference: JSONRPCInvocation | MCPVersion): MCPHeaderIssue | undefined;
 
 /**
- * Infer the legacy revision an `initialize` request negotiates.
+ * Infers the legacy revision an `initialize` request negotiates.
  *
  * @remarks
  * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
@@ -812,7 +829,7 @@ export declare function inferHeaderIssue(request: Request, reference: JSONRPCInv
 export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPVersion;
 
 /**
- * Infer the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
+ * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
  *
  * @remarks
  * Notifications are accepted with `202`. Legacy response envelopes retain uniform `200`
@@ -832,7 +849,7 @@ export declare function inferStatus(response: JSONRPCResponse | undefined, era:
  * the trailing partial line carried forward as the new `remainder`.
  *
  * @remarks
- * A plain value record (no behavior, §4.5) {@link import('./helpers.js').extractLines}
+ * A plain value record (no behavior) {@link import('./helpers.js').extractLines}
  * returns; the caller threads `remainder` back in as the next call's `buffer`.
  */
 export declare interface LineExtraction {
@@ -879,7 +896,7 @@ export declare const MCP_SESSION_HEADER = "mcp-session-id";
 export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 
 /**
- * Synchronously extract consumer-asserted caller context from an HTTP request after the
+ * Extracts consumer-asserted caller context synchronously from an HTTP request after the
  * transport has validated it for dispatch.
  *
  * @remarks
@@ -948,8 +965,8 @@ export declare interface MCPOriginOptions {
  * The single session entity (the old `SessionState` + `EventStore` merged): it holds the
  * session `id`, its OWN bounded, replayable log of pushed server→client messages (the
  * resumable GET-SSE channel — a private `#events` `Map` + a monotone `#counter`, with
- * `capacity` / `ttl` eviction, NOT a separate store), and the set of currently OPEN
- * server→client SSE streams (a resumable `GET {path}` registers via `attach`, unregisters via
+ * `capacity` / `ttl` eviction, not a separate store), and the set of open
+ * server→client SSE streams (a resumable `GET {path}` registers through `attach`, unregisters through
  * `detach` on disconnect). Still a small entity (not a record), built minimal + extensible.
  *
  * - **`push` is the server-initiated primitive.** It APPENDS the message to the log (assigning
@@ -969,7 +986,7 @@ export declare interface MCPOriginOptions {
  *   lost (its cursor is OLDER than everything retained); returning `[]` lets the handler then
  *   stream only the fresh pushes that follow `attach` — the spec-sane resume.
  *
- * - **Bounded, append-ordered, plain `Map` (§21).** The log lives in ONE insertion-ordered
+ * - **Bounded, append-ordered, plain `Map`.** The log lives in ONE insertion-ordered
  *   `Map<id, entry>` — insertion order IS append order IS id order, so `replay` and capacity
  *   eviction both walk the map directly. NO database mirror — the log is process-local
  *   transport mechanics, not durable state. `push` first drops every entry older than `ttl`
@@ -983,8 +1000,8 @@ export declare interface MCPOriginOptions {
  *   serializes a message onto the already-open streams.
  *
  * - **Injected clock.** `push` / `replay` accept an optional `now` (epoch ms), defaulting to
- *   `Date.now()` — so a test drives TTL eviction with an elapsed clock rather than a real timer
- *   (AGENTS §16).
+ *   `Date.now()` — so a test drives TTL eviction with an elapsed clock rather than a real
+ *   timer.
  *
  * @example
  * ```ts
@@ -1074,7 +1091,7 @@ export declare interface MCPSessionInterface {
  * - `clock` — the `() => number` epoch-ms clock {@link import('./middlewares.js').createMCPSession}
  *   uses directly for its own session-touch / TTL-sweep bookkeeping; defaults to `Date.now`. The
  *   deterministic clock a TTL test advances explicitly instead of racing a real idle window
- *   against wall-clock (AGENTS §16). Production never sets it.
+ *   against wall-clock. Production never sets it.
  * - `origin` — the same shared origin-validation options supplied to `createMCPRoutes`.
  *   Validation is enabled by default, accepts canonical loopback-literal origins, and rejects
  *   every other present origin outside its exact list before any session is minted. Set
@@ -1110,16 +1127,16 @@ export declare interface MCPSessionState {
 }
 
 /**
- * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+ * Decodes a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
  * carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
  *
  * @remarks
  * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
  * stream: true })` (handling a multi-byte char split across reads) and `@orkestrel/sse`'s
  * {@link SSEParserInterface} (handling a partial line / in-progress event split across
- * reads), then narrows each dispatched event's `data` to a {@link JSONRPCMessage} via
+ * reads), then narrows each dispatched event's `data` to a {@link JSONRPCMessage} with
  * `parseJSONRPCMessage` (so a non-message / non-JSON `data:` event is DROPPED, never
- * thrown — total, §14). It reuses the SAME `SSEParser` the server's `openStream` seam
+ * thrown — total). It reuses the SAME `SSEParser` the server's `openStream` seam
  * serializes against, so the wire round-trips. A `null` body (no stream) yields no
  * messages; the {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
  * reads a request/response SSE reply (the server sends one `data:` event then ends), so
@@ -1131,7 +1148,7 @@ export declare interface MCPSessionState {
 export declare function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]>;
 
 /**
- * Read the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it
+ * Reads the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it
  * reconnects to the resumable `GET {path}` stream, or `undefined` when absent.
  *
  * @remarks
@@ -1147,7 +1164,7 @@ export declare function readEventStream(response: Response): Promise<readonly JS
 export declare function readLastEventId(request: Request): string | undefined;
 
 /**
- * Read the request's `mcp-session-id` header — the session id a stateful transport
+ * Reads the request's `mcp-session-id` header — the session id a stateful transport
  * validates, or `undefined` when absent.
  *
  * @remarks
@@ -1163,7 +1180,7 @@ export declare function readLastEventId(request: Request): string | undefined;
 export declare function readSessionHeader(request: Request): string | undefined;
 
 /**
- * Build the stateful transport's "unknown session" rejection — an HTTP `404` carrying a
+ * Builds the stateful transport's "unknown session" rejection — an HTTP `404` carrying a
  * JSON-RPC error body.
  *
  * @remarks
@@ -1180,12 +1197,12 @@ export declare function readSessionHeader(request: Request): string | undefined;
 export declare function rejectUnknownSession(): Response;
 
 /**
- * Pump a controlled held-open exchange onto an open SSE stream — one `data:` event per
+ * Pumps a controlled held-open exchange onto an open SSE stream — one `data:` event per
  * notification in order, then the terminating response — and END the exchange however the
  * pump leaves.
  *
  * @remarks
- * The Streamable-HTTP twin of {@link import('@src/core').sendStream}, and it owns exactly what
+ * The Streamable-HTTP twin of {@link import('@orkestrel/mcp').sendStream}, and it owns exactly what
  * that owns. The `finally` releases the exchange on EVERY exit — the normal terminal, a
  * producer that threw, a `write` that threw, and an abort alike — because nothing else will:
  * a request whose client vanished cancels nothing by itself, so an exchange this pump walks
@@ -1193,7 +1210,7 @@ export declare function rejectUnknownSession(): Response;
  * The exchange is released BEFORE the body ends, so the slot is already back when the response
  * completes.
  *
- * Total (§14) — never throws and never rejects. A held-open SSE response has already sent its
+ * Total — never throws and never rejects. A held-open SSE response has already sent its
  * headers and part of its body, so there is no failure the transport could still convert into
  * a different answer; the honest end of a broken stream is a closed one, and the fault itself
  * is already legible on `server.emitter`'s `error` event, which is where a contained fault
@@ -1231,22 +1248,31 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
  *
  * @remarks
- * - **Spawns the server.** `start()` runs `node:child_process`'s `spawn(options.command,
- *   options.args, { env: options.env, stdio: ['pipe', 'pipe', 'inherit'] })` — the
- *   child's `stdin`/`stdout` are piped for the JSON-RPC channel, its `stderr` inherits
- *   the parent's (diagnostics pass through, never parsed as protocol).
- * - **Inbound (`message`).** Each `stdout` chunk is folded through the shared
- *   {@link extractLines} line-framing helper (buffering a partial trailing line
- *   across reads); every complete line is decoded and delivered via the shared
- *   {@link dispatchLines} helper — a well-formed {@link JSONRPCMessage} emits
- *   `message`, a malformed line emits `error` (§14, never throws). The child's
- *   `close` bridges to this transport's `close`.
- * - **Outbound (`send`).** `send(message)` writes one newline-terminated
- *   `JSON.stringify`d line to the child's `stdin`.
- * - **`close()`** kills the child process and fires `close` (idempotent).
- * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
+ * - **Composes `@orkestrel/process`.** `start()` builds one supervised
+ *   {@link import('@orkestrel/process/server').Process} with `writable: true`, so the child's
+ *   `stdin`/`stdout` are the JSON-RPC channel and its `stderr` is retained as bounded evidence
+ *   rather than parsed as protocol. The supervisor owns spawn, framing, and termination.
+ * - **Inbound (`message`).** Standard output is drained eagerly through the supervisor's
+ *   `readline`-framed `lines` iterable, so a multi-byte UTF-8 sequence split across two reads is
+ *   decoded whole and a final line written without a trailing newline still arrives. Each framed
+ *   line is decoded and delivered through the shared {@link dispatchLines} helper — a well-formed
+ *   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (never throws).
+ * - **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.
+ * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
- *   fault), distinct from the emitter's own listener-error channel.
+ *   fault, including the child spawn cause the supervisor surfaces), distinct from the emitter's
+ *   own listener-error channel.
  *
  * @example
  * ```ts
@@ -1271,13 +1297,13 @@ export declare class StdioClientTransport implements MCPClientTransportInterface
  * stdio-framed MCP server (newline-delimited JSON-RPC over `stdin`/`stdout`).
  *
  * @remarks
- * - `command` — the executable to spawn (e.g. `'node'`, `'./my-mcp-server'`). REQUIRED.
+ * - `command` — the executable to spawn (for example, `'node'`, `'./my-mcp-server'`). REQUIRED.
  * - `args` — the command-line arguments passed to `command`; defaults to none.
- * - `env` — the environment variables for the spawned child, passed straight to
- *   `node:child_process`'s `spawn`; when OMITTED the child inherits the full
- *   `process.env` (the `spawn` default), when PROVIDED it REPLACES the inherited
- *   environment entirely (`spawn` semantics) — a caller wanting to extend rather
- *   than replace spreads `process.env` into `env` themselves.
+ * - `env` — environment variable overrides MERGED over the parent `process.env` for the
+ *   spawned child (the composed `@orkestrel/process` supervisor's merge semantics): when
+ *   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.
  */
 export declare interface StdioClientTransportOptions {
     readonly command: string;
@@ -1309,22 +1335,31 @@ export declare interface StdioServerOptions {
  * import('./WebSocketServerTransport.js').WebSocketServerTransport}.
  *
  * @remarks
- * - **Reuses `MCPClientTransportInterface` (§21).** The same generic carrier the HTTP
+ * - **Reuses `MCPClientTransportInterface`.** The same generic carrier the HTTP
  *   and WebSocket server transports implement — `emitter` (`message` / `close` /
  *   `error`), `start`, `send`, `close`. `session` is `undefined` (the stateless v1).
  * - **Inbound (`message`).** `start()` subscribes to `input`'s `data` event; each
  *   chunk is folded through the shared {@link extractLines} line-framing helper
  *   (buffering a partial trailing line across reads), and every complete line is
- *   decoded and delivered via the shared {@link dispatchLines} helper — a
+ *   decoded and delivered through the shared {@link dispatchLines} helper — a
  *   well-formed {@link JSONRPCMessage} re-emits on `message`, a malformed line
- *   emits `error` (§14, never throws). `input`'s `close` bridges to this
+ *   emits `error` (never throws). `input`'s `close` bridges to this
  *   transport's `close`.
  * - **Outbound (`send`).** `send(message)` writes one newline-terminated
  *   `JSON.stringify`d line to `output`.
- * - **`close()`** fires this transport's `close` (idempotent) — the injected streams
- *   are owned by the caller (typically `process.stdin`/`process.stdout`, which must
- *   never be closed out from under the process) and are not torn down here.
- * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
+ * - **`close()`** removes this transport's input subscriptions and fires its `close`
+ *   event (idempotent). It pauses the input only when the caller was not already reading
+ *   it at `start` (`readableFlowing !== true`) AND no `data` listener remains once this
+ *   transport's own is removed — so a process holding `process.stdin` can exit, and a
+ *   caller's own flow is never stopped underneath it. The transport preserves flowing versus
+ *   non-flowing state and restores every caller-owned listener. A Node stream that had never been
+ *   read starts with `readableFlowing === null` and is left non-flowing (`false`), because Node
+ *   exposes no public operation that restores `null` after data consumption starts. Attaching a
+ *   later `data` listener does not resume that stream; the caller must call `resume()` before the
+ *   listener receives data. The injected streams are owned by the caller (typically
+ *   `process.stdin`/`process.stdout`), so the transport never destroys, ends, or blanket-clears
+ *   them.
+ * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
  *   fault), distinct from the emitter's own listener-error channel.
  */
@@ -1340,13 +1375,13 @@ export declare class StdioServerTransport implements MCPClientTransportInterface
 }
 
 /**
- * Read the path (without the query string) of a raw `node:http` protocol-upgrade request —
+ * Reads the path (without the query string) of a raw `node:http` protocol-upgrade request —
  * the `createWebSocketServer` upgrade-path match.
  *
  * @remarks
  * A `node:http` {@link import('node:http').IncomingMessage}'s `url` is the request TARGET
- * (`'/mcp?x=1'`), narrowed with `isString` (§14, never `as`) and defaulting to `'/'` for an
- * absent target; it is parsed against a dummy base (only the pathname matters for the upgrade
+ * (`'/mcp?x=1'`), narrowed with `isString` (never `as`) and defaulting to `'/'` for an
+ * absent target; it is parsed against a placeholder base (only the pathname matters for the upgrade
  * decision) and the `pathname` returned. The upgrade handler compares this against its
  * configured `path` to decide whether to claim the socket. Total — never throws on an
  * adversarial / absent target.
@@ -1370,7 +1405,8 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   event, and VALIDATES `Sec-WebSocket-Accept === computeWebSocketAccept(key)` (the D2 helper)
  *   — a mismatch (or a non-`101` response, or a request error) REJECTS `start()` and the socket
  *   is destroyed. On success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
- *   head })` (CLIENT mode — no key → frames are MASKED per §5.3) and bridges its `message`.
+ *   head })` (CLIENT mode — no key → frames are MASKED per RFC 6455 §5.3) and bridges its
+ *   `message`.
  * - **The arriving socket is RE-ASKED for, never assumed.** `start()` suspends across that
  *   connect and upgrade, so it re-checks the transport's state before installing anything: a
  *   concurrent `start()` that already installed a socket, or a {@link close} that ended the
@@ -1379,15 +1415,18 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   `start()` calls still resolve; exactly one socket is ever bound.
  * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and narrowed
  *   with `parseJSONRPCMessage` — a {@link JSONRPCMessage} re-emits on this transport's `message`
- *   event (the reply the {@link import('@src/core').MCPClientInterface} correlates by `id`); a
- *   non-JSON / non-message frame surfaces on `error` and is dropped (§14). The socket's `close`
+ *   event (the reply the {@link import('@orkestrel/mcp').MCPClientInterface} correlates by `id`); a
+ *   non-JSON / non-message frame surfaces on `error` and is dropped. The socket's `close`
  *   / `error` bridge to this transport's events.
  * - **Outbound (`send`).** `send(message)` writes one masked text frame.
- * - **`close()`** closes the underlying socket and fires `close` (idempotent).
+ * - **`close()`** unsubscribes from the socket, closes it, and fires `close` (idempotent). An
+ *   upgrade still on the wire is DESTROYED, so a `close()` during the handshake ends the
+ *   transport at once instead of waiting for a peer that may never answer — the suspended
+ *   `start()` resolves, because the close is the outcome its caller asked for.
  * - **URL scheme.** `options.url` accepts a `ws://` / `wss://` URL or an `http://` / `https://`
  *   one; a `ws(s)` scheme is converted to `http(s)` for the underlying upgrade request (`wss`
- *   → TLS via `node:https`). Either reaches the same endpoint.
- * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
+ *   → TLS through `node:https`). Either reaches the same endpoint.
+ * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
  *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
  *   `error` is a DOMAIN event (a transport-level fault).
  *
@@ -1418,7 +1457,7 @@ export declare class WebSocketClientTransport implements MCPClientTransportInter
  *   `wss://` URL OR an `http://` / `https://` one (a `ws(s)` scheme is converted to `http(s)`
  *   for the underlying `node:http(s)` upgrade request; either reaches the same endpoint).
  *   REQUIRED.
- * - `headers` — extra request headers merged onto the upgrade `GET` (e.g. an `Authorization`
+ * - `headers` — extra request headers merged onto the upgrade `GET` (for example, an `Authorization`
  *   bearer for a guarded server). The transport always sets `Connection: Upgrade`,
  *   `Upgrade: websocket`, a random `Sec-WebSocket-Key`, `Sec-WebSocket-Version: 13`, and
  *   `Sec-WebSocket-Protocol: mcp`; a header supplied here is merged on top.
@@ -1428,7 +1467,7 @@ export declare class WebSocketClientTransport implements MCPClientTransportInter
  * This face owns its own `node:http(s)` upgrade request, so it can set any header on it. A
  * page cannot — the native `WebSocket` constructor takes a URL and subprotocols and nothing
  * else — so a `headers` key over there would be an option that silently did nothing. Do not
- * "harmonize" the two shapes.
+ * "harmonize" the option shapes.
  */
 export declare interface WebSocketClientTransportOptions {
     readonly url: string;
@@ -1450,10 +1489,9 @@ export declare interface WebSocketClientTransportOptions {
  *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`, the same path the HTTP
  *   transport mounts at). A protocol-upgrade request to any OTHER path is DECLINED
  *   (the handler returns `false`, so the spine fans it to the next handler or destroys it).
- * - `subprotocol` — the WebSocket subprotocol echoed in the `101` handshake's
+ * - `subprotocol` — the WebSocket subprotocol selected in the `101` handshake's
  *   `Sec-WebSocket-Protocol`; defaults to {@link import('./constants.js').MCP_WEBSOCKET_SUBPROTOCOL}
- *   (`'mcp'`). It is echoed unconditionally (the client requests it), so an MCP WebSocket
- *   endpoint is distinguishable from another WebSocket on the same path.
+ *   (`'mcp'`). It is sent only when the client's offer contains that token.
  *
  * Auth / origin policy is deliberately ABSENT: like the HTTP transport, the WebSocket
  * transport is MECHANISM — compose a guard IN FRONT (a `Server.upgrade` handler registered
@@ -1473,7 +1511,7 @@ export declare interface WebSocketServerOptions {
  * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
  *
  * @remarks
- * - **Reuses `MCPClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
+ * - **Reuses `MCPClientTransportInterface`.** It IS the same generic carrier the HTTP
  *   client transport implements — `emitter` (`message` / `close` / `error`), `start`,
  *   `send`, `close` — so the WebSocket server and client both speak ONE transport contract,
  *   no near-duplicate sibling interface. `session` is `undefined` (the stateless v1; a
@@ -1482,16 +1520,18 @@ export declare interface WebSocketServerOptions {
  * - **Inbound (`message`).** `start()` subscribes to the socket's `message` event; each text
  *   frame is `JSON.parse`d inside a try/catch and narrowed with `parseJSONRPCMessage` — a
  *   well-formed {@link JSONRPCMessage} is re-emitted on this transport's `message` event (the
- *   parsed envelope the {@link import('@src/core').MCPServerInterface} pump dispatches), while
- *   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown (§14). It
+ *   parsed envelope the {@link import('@orkestrel/mcp').MCPServerInterface} pump dispatches), while
+ *   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown. It
  *   also bridges the socket's `close` → this transport's `close`, and the socket's `error`.
  * - **Outbound (`send`).** `send(message)` writes one text frame
  *   (`nodeWs.send(JSON.stringify(message))`); the underlying wrapper no-ops a write on a
  *   non-open socket, so a closed connection drops silently rather than throwing.
- * - **`close()`** closes the underlying socket (the RFC 6455 close handshake) and fires the
- *   transport's `close` event (idempotent — a second `close`, or a socket-driven close, emits
- *   once).
- * - **Observable (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
+ * - **`close()`** removes the subscriptions `start()` installed on the socket, closes the
+ *   underlying socket (the RFC 6455 close handshake), and fires the transport's `close` event
+ *   (idempotent — a second `close`, or a socket-driven close, emits once). A frame that arrives
+ *   between that release and the peer's close echo reaches nothing: the socket-driven close path
+ *   releases the same way, so a closed transport is never subscribed to a live socket.
+ * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
  *   isolates a listener throw (a buggy observer never corrupts the bridge). `error` is a
  *   DOMAIN event (a transport-level fault), distinct from the emitter's listener-error channel.
  */