@gajae-code/coding-agent 0.16.1 → 0.16.4

package/src/runtime-mcp/pool.ts

@@ -5,7 +5,7 @@
  * multiple leases and roots/resource subscriptions are connection-global unions.
  */
 import { logger } from "@gajae-code/utils";
-import { connectToServer, subscribeToResources, unsubscribeFromResources } from "./client";
+import { connectToServer, MCPConnectionCleanupFailure, subscribeToResources, unsubscribeFromResources } from "./client";
 import {
 	buildMCPPoolKeyIdentity,
 	computeMCPPoolKey,
@@ -60,9 +60,16 @@ export class MCPPoolAcquireAbortError extends Error {
 	readonly code = "MCP_POOL_ACQUIRE_ABORTED" as const;
 	readonly serverName: string;
 	readonly poolKey: string;
-	cleanup?: Promise<unknown>;
-
-	constructor(serverName: string, poolKey: string, cause: unknown, cleanup?: Promise<unknown>) {
+	readonly cleanup?: Promise<void>;
+	readonly cleanupGeneration?: number;
+
+	constructor(
+		serverName: string,
+		poolKey: string,
+		cause: unknown,
+		cleanup?: Promise<void>,
+		cleanupGeneration?: number,
+	) {
 		super(
 			`MCP connection acquisition aborted for ${serverName} (${poolKey}): ${
 				cause instanceof Error ? cause.message : String(cause)
@@ -73,6 +80,7 @@ export class MCPPoolAcquireAbortError extends Error {
 		this.serverName = serverName;
 		this.poolKey = poolKey;
 		this.cleanup = cleanup;
+		this.cleanupGeneration = cleanupGeneration;
 	}
 }
 
@@ -121,6 +129,8 @@ export interface MCPPoolAcquireOptions extends MCPPoolKeyOptions {
 	advertiseRoots?: boolean;
 	onNotification?: (method: string, params: unknown) => void;
 	onRequest?: (method: string, params: unknown) => Promise<unknown>;
+	/** @internal Synchronous handoff for a pool-owned abandoned-acquire cleanup flight. */
+	onCleanupPending?: (error: MCPPoolAcquireAbortError) => void;
 }
 
 export interface MCPConnectionPoolOptions {
@@ -172,6 +182,7 @@ type PendingWaiter = {
 	settled: boolean;
 	claimed: boolean;
 	removeAbortListener?: () => void;
+	onCleanupPending?: (error: MCPPoolAcquireAbortError) => void;
 };
 
 type PendingEntry = {
@@ -186,7 +197,17 @@ type PendingEntry = {
 	cancellationReason?: unknown;
 	openAbortController: AbortController;
 	openSignal?: AbortSignal;
-	settlement?: Promise<unknown>;
+	settlement?: Promise<void>;
+};
+
+type RetiredAcquisitionCleanup = {
+	key: string;
+	serverName: string;
+	generation: number;
+	completion: Promise<void>;
+	error: MCPPoolAcquireAbortError;
+	failure?: MCPConnectionCleanupFailure;
+	retry?: Promise<void>;
 };
 
 function errorMessage(error: unknown): string {
@@ -386,6 +407,7 @@ export class MCPConnectionPool {
 	readonly #pending = new Map<string, PendingEntry>();
 	readonly #allLeases = new Set<MCPPoolLeaseImpl>();
 	readonly #retiredEntries = new Set<PoolEntry>();
+	readonly #retiredAcquisitionCleanups = new Map<string, RetiredAcquisitionCleanup>();
 	readonly #restartOwners = new Set<string>();
 	readonly #restartWaiters = new Map<string, { promise: Promise<boolean>; resolve: (value: boolean) => void }>();
 	readonly #healthListeners = new Set<HealthListener>();
@@ -458,22 +480,160 @@ export class MCPConnectionPool {
 		this.#restartWaiters.delete(key);
 	}
 
+	private retainCancelledAcquireCleanup(
+		key: string,
+		name: string,
+		pending: PendingEntry,
+		cause: unknown,
+	): RetiredAcquisitionCleanup {
+		const current = this.#retiredAcquisitionCleanups.get(key);
+		if (current) return current;
+		const completion = pending.settlement;
+		const generation = pending.entry?.generation;
+		if (!completion || generation === undefined) {
+			throw new Error(`MCP cancelled acquisition cleanup is missing its flight identity: ${key}`);
+		}
+		const error = new MCPPoolAcquireAbortError(name, key, cause, completion, generation);
+		const owner: RetiredAcquisitionCleanup = { key, serverName: name, generation, completion, error };
+		this.#retiredAcquisitionCleanups.set(key, owner);
+		void completion.then(
+			() => {
+				if (this.#retiredAcquisitionCleanups.get(key) === owner && !owner.retry) {
+					this.#retiredAcquisitionCleanups.delete(key);
+				}
+			},
+			error => {
+				if (error instanceof MCPConnectionCleanupFailure) {
+					owner.failure = error;
+					return;
+				}
+				if (this.#retiredAcquisitionCleanups.get(key) === owner && !owner.retry) {
+					this.#retiredAcquisitionCleanups.delete(key);
+				}
+			},
+		);
+		return owner;
+	}
+
+	private notifyPendingAcquireCleanup(
+		listener: MCPPoolAcquireOptions["onCleanupPending"],
+		owner: RetiredAcquisitionCleanup,
+	): void {
+		try {
+			listener?.(owner.error);
+		} catch (error) {
+			logger.debug("MCP cancelled acquire cleanup handoff failed", {
+				path: `mcp:${owner.serverName}`,
+				poolKey: owner.key,
+				error,
+			});
+		}
+	}
+
+	/** @internal Whether this pool still owns the notified abandoned-acquire flight. */
+	hasPendingAcquireCleanup(error: MCPPoolAcquireAbortError): boolean {
+		const owner = this.#retiredAcquisitionCleanups.get(error.poolKey);
+		return owner?.generation === error.cleanupGeneration;
+	}
+
+	/** @internal Current retained failure for one notified abandoned-acquire generation. */
+	getPendingAcquireCleanupFailure(error: MCPPoolAcquireAbortError): MCPConnectionCleanupFailure | undefined {
+		const owner = this.#retiredAcquisitionCleanups.get(error.poolKey);
+		return owner && owner.generation === error.cleanupGeneration ? owner.failure : undefined;
+	}
+
+	/** @internal Prevent manager-level duplication of the pool's retained cleanup owner. */
+	ownsPendingAcquireCleanupFailure(error: unknown): boolean {
+		if (!(error instanceof MCPConnectionCleanupFailure)) return false;
+		for (const owner of this.#retiredAcquisitionCleanups.values()) {
+			if (owner.failure === error) return true;
+		}
+		return false;
+	}
+
+	/** Read-only test seam for abandoned-acquire cleanup owners. */
+	get pendingAcquireCleanupCountForTests(): number {
+		return this.#retiredAcquisitionCleanups.size;
+	}
+
+	/** Read-only test seam for the current retained abandoned-acquire cleanup failure. */
+	getPendingAcquireCleanupFailureForTests(name: string): MCPConnectionCleanupFailure | undefined {
+		for (const owner of this.#retiredAcquisitionCleanups.values()) {
+			if (owner.serverName === name && owner.failure) return owner.failure;
+		}
+		return undefined;
+	}
+
+	/** @internal Join and retry one generation of abandoned acquisition cleanup. */
+	async closePendingAcquireCleanup(key: string, generation: number): Promise<void> {
+		const owner = this.#retiredAcquisitionCleanups.get(key);
+		if (!owner || owner.generation !== generation) return;
+		if (owner.retry) return owner.retry;
+		let tracked!: Promise<void>;
+		tracked = (async () => {
+			let failure = owner.failure;
+			if (!failure) {
+				try {
+					await owner.completion;
+				} catch (error) {
+					if (!(error instanceof MCPConnectionCleanupFailure)) throw error;
+					failure = owner.failure ?? error;
+				}
+			}
+			if (failure) {
+				try {
+					await failure.close();
+				} catch (error) {
+					if (this.#retiredAcquisitionCleanups.get(key) === owner) {
+						owner.failure = error instanceof MCPConnectionCleanupFailure ? error : failure;
+					}
+					throw error;
+				}
+			}
+			if (this.#retiredAcquisitionCleanups.get(key) === owner) this.#retiredAcquisitionCleanups.delete(key);
+		})().finally(() => {
+			if (this.#retiredAcquisitionCleanups.get(key) === owner && owner.retry === tracked) owner.retry = undefined;
+		});
+		owner.retry = tracked;
+		return tracked;
+	}
+
 	async acquire(name: string, config: MCPServerConfig, options: MCPPoolAcquireOptions = {}): Promise<MCPPoolLease> {
 		if (this.#shuttingDown) throw new Error("MCP connection pool is shut down");
 		const keyOptions: MCPPoolKeyOptions = options;
 		const key = computeMCPPoolKey(name, config, keyOptions);
+		if (options.signal?.aborted) {
+			throw new MCPPoolAcquireAbortError(
+				name,
+				key,
+				options.signal.reason ?? new Error(`MCP connection acquisition aborted: ${name}`),
+			);
+		}
+		for (;;) {
+			const cleanup = this.#retiredAcquisitionCleanups.get(key);
+			if (!cleanup) break;
+			this.notifyPendingAcquireCleanup(options.onCleanupPending, cleanup);
+			await this.closePendingAcquireCleanup(cleanup.key, cleanup.generation);
+		}
+		if (options.signal?.aborted) {
+			throw new MCPPoolAcquireAbortError(
+				name,
+				key,
+				options.signal.reason ?? new Error(`MCP connection acquisition aborted: ${name}`),
+			);
+		}
 
 		let entry = this.#entries.get(key);
 		let claim: () => void = () => {};
 		if (entry?.pending) {
-			const acquisition = await this.waitForPendingEntry(key, name, entry.pending, options.signal);
+			const acquisition = await this.waitForPendingEntry(key, name, entry.pending, options);
 			entry = acquisition.entry;
 			claim = acquisition.claim;
 		}
 		if (!entry) {
 			let pending = this.#pending.get(key);
 			if (!pending) pending = this.startPendingEntry(key, name, config, options);
-			const acquisition = await this.waitForPendingEntry(key, name, pending, options.signal);
+			const acquisition = await this.waitForPendingEntry(key, name, pending, options);
 			entry = acquisition.entry;
 			claim = acquisition.claim;
 		}
@@ -502,10 +662,17 @@ export class MCPConnectionPool {
 		key: string,
 		name: string,
 		pending: PendingEntry,
-		signal?: AbortSignal,
+		options: Pick<MCPPoolAcquireOptions, "signal" | "onCleanupPending">,
 	): Promise<PendingAcquisition> {
 		const { promise, resolve, reject } = Promise.withResolvers<PendingAcquisition>();
-		const waiter: PendingWaiter = { resolve, reject, settled: false, claimed: false };
+		const signal = options.signal;
+		const waiter: PendingWaiter = {
+			resolve,
+			reject,
+			settled: false,
+			claimed: false,
+			onCleanupPending: options.onCleanupPending,
+		};
 		pending.waiters.add(waiter);
 		const settle = (fn: () => void): void => {
 			if (waiter.settled) return;
@@ -515,14 +682,21 @@ export class MCPConnectionPool {
 			fn();
 		};
 		const abortWaiter = (): void => {
-			const reason = new MCPPoolAcquireAbortError(
-				name,
-				key,
-				signal?.reason ?? new Error(`MCP connection acquisition aborted: ${name}`),
-				pending.settlement,
-			);
-			settle(() => reject(reason));
-			if (pending.waiters.size === 0 && !pending.settled) this.cancelPendingEntry(key, pending, reason);
+			if (waiter.settled) return;
+			waiter.settled = true;
+			pending.waiters.delete(waiter);
+			waiter.removeAbortListener?.();
+			const cause = signal?.reason ?? new Error(`MCP connection acquisition aborted: ${name}`);
+			let reason: MCPPoolAcquireAbortError;
+			if (pending.waiters.size === 0 && !pending.settled) {
+				const cleanup = this.retainCancelledAcquireCleanup(key, name, pending, cause);
+				reason = cleanup.error;
+				this.cancelPendingEntry(key, pending, reason);
+				this.notifyPendingAcquireCleanup(waiter.onCleanupPending, cleanup);
+			} else {
+				reason = new MCPPoolAcquireAbortError(name, key, cause);
+			}
+			reject(reason);
 		};
 		if (signal) {
 			if (signal.aborted) abortWaiter();
@@ -618,12 +792,22 @@ export class MCPConnectionPool {
 					try {
 						await this.closeEntry(entry);
 					} catch (error) {
-						logger.error("MCP cancelled acquire cleanup failed", { path: `mcp:${name}`, poolKey: key, error });
+						throw new MCPConnectionCleanupFailure(
+							new AggregateError(
+								[
+									pending.cancellationReason ?? new Error(`MCP connection acquisition abandoned: ${name}`),
+									error,
+								],
+								`MCP cancelled acquisition cleanup failed: ${name}`,
+							),
+							entry.connection.transport,
+						);
 					}
 				},
 				error => {
 					pending.settled = true;
 					pending.reject(error);
+					if (pending.cancelled && error instanceof MCPConnectionCleanupFailure) throw error;
 				},
 			)
 			.finally(() => {
@@ -678,11 +862,16 @@ export class MCPConnectionPool {
 				try {
 					await connection.transport.close();
 				} catch (closeError) {
-					logger.error("MCP late transport close failed", {
-						path: `mcp:${name}`,
-						poolKey: key,
-						error: closeError,
-					});
+					throw new MCPConnectionCleanupFailure(
+						new AggregateError(
+							[
+								pending.cancellationReason ?? new Error(`MCP connection acquisition abandoned: ${name}`),
+								closeError,
+							],
+							`MCP cancelled acquisition cleanup failed: ${name}`,
+						),
+						connection.transport,
+					);
 				}
 				throw pending.cancellationReason ?? new Error(`MCP connection acquisition abandoned: ${name}`);
 			}
@@ -938,6 +1127,7 @@ export class MCPConnectionPool {
 		this.#shutdownController.abort(reason);
 		for (const [key, pending] of this.#pending) {
 			if (!pending.cancelled) {
+				this.retainCancelledAcquireCleanup(key, pending.entry?.name ?? "unknown", pending, reason);
 				pending.cancelled = true;
 				pending.cancellationReason = reason;
 				pending.openAbortController.abort(reason);
@@ -951,6 +1141,17 @@ export class MCPConnectionPool {
 			pending.waiters.clear();
 			if (this.#pending.get(key) === pending) this.#pending.delete(key);
 		}
+		for (const cleanup of this.#retiredAcquisitionCleanups.values()) {
+			const failure = this.getPendingAcquireCleanupFailure(cleanup.error);
+			if (!failure) continue;
+			void this.closePendingAcquireCleanup(cleanup.key, cleanup.generation).catch(error =>
+				logger.error("MCP pool shutdown pending acquire cleanup failed", {
+					serverName: cleanup.serverName,
+					poolKey: cleanup.key,
+					error,
+				}),
+			);
+		}
 		for (const lease of this.#allLeases) lease.invalidate(reason);
 		this.#allLeases.clear();
 		const entries = [...new Set([...this.#entries.values(), ...this.#retiredEntries])];

package/src/runtime-mcp/transports/stdio.ts

@@ -13,6 +13,7 @@ import type {
 	JsonRpcRequest,
 	JsonRpcResponse,
 	MCPRequestOptions,
+	MCPStdioPreparedLaunch,
 	MCPStdioServerConfig,
 	MCPTransport,
 } from "../../runtime-mcp/types";
@@ -56,6 +57,22 @@ function buildMinimalStdioEnv(explicit?: Record<string, string>): Record<string,
 	return { ...env, ...explicit };
 }
 
+function combinedOperationAndCleanupFailure(operationError: unknown, cleanupError: unknown): MCPExpectedFailure {
+	return new MCPExpectedFailure(
+		new AggregateError(
+			[operationError, cleanupError],
+			"MCP stdio operation failed and subprocess cleanup also failed",
+		),
+	);
+}
+
+type StdioConnectAttempt = {
+	generation: number;
+	revoked: boolean;
+	settled: boolean;
+	completion: Promise<void>;
+};
+
 export class StdioTransport implements MCPTransport {
 	#process: OwnedProcess | null = null;
 	#pendingRequests = new Map<
@@ -69,6 +86,10 @@ export class StdioTransport implements MCPTransport {
 	#readLoop: Promise<void> | null = null;
 	#stderrLoop: Promise<void> | null = null;
 	#closePromise: Promise<void> | null = null;
+	#connectGeneration = 0;
+	#connectAttempt: StdioConnectAttempt | null = null;
+	/** Retained until the per-attempt cleanup resolves successfully. */
+	#afterProcessExit: (() => Promise<void>) | null = null;
 
 	onClose?: () => void;
 	onError?: (error: Error) => void;
@@ -85,33 +106,122 @@ export class StdioTransport implements MCPTransport {
 		return true;
 	}
 
+	#registerCleanup(attempt: StdioConnectAttempt, cleanup: () => Promise<void>): void {
+		if (this.#connectAttempt !== attempt) {
+			throw new Error("MCP stdio attempt registered cleanup after its ownership ended");
+		}
+		if (this.#afterProcessExit && this.#afterProcessExit !== cleanup) {
+			throw new Error("MCP stdio attempt registered conflicting cleanup owners");
+		}
+		this.#afterProcessExit = cleanup;
+	}
+
+	#assertConnectAttemptActive(attempt: StdioConnectAttempt): void {
+		if (attempt.revoked || this.#connectAttempt !== attempt || this.#connectGeneration !== attempt.generation) {
+			throw new Error("MCP stdio connection attempt was closed");
+		}
+	}
+
+	#revokeConnectAttempt(): StdioConnectAttempt | null {
+		const attempt = this.#connectAttempt;
+		if (attempt && !attempt.revoked) {
+			attempt.revoked = true;
+			this.#connectGeneration++;
+		}
+		return attempt;
+	}
+
 	/**
 	 * Start the subprocess and begin reading.
 	 */
 	async connect(): Promise<void> {
 		if (this.#connected) return;
-		if (this.#closePromise || this.#process) {
+		if (this.#closePromise) {
+			throw new MCPExpectedFailure(new Error("MCP stdio child teardown is incomplete"));
+		}
+		if (this.#connectAttempt) {
+			if (!this.#connectAttempt.settled) return this.#connectAttempt.completion;
+			if (this.#process || this.#afterProcessExit) {
+				throw new MCPExpectedFailure(new Error("MCP stdio child teardown is incomplete"));
+			}
+			this.#connectAttempt = null;
+		}
+		if (this.#process || this.#afterProcessExit) {
 			throw new MCPExpectedFailure(new Error("MCP stdio child teardown is incomplete"));
 		}
 
-		const args = this.config.args ?? [];
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		const attempt: StdioConnectAttempt = {
+			generation: ++this.#connectGeneration,
+			revoked: false,
+			settled: false,
+			completion: promise,
+		};
+		this.#connectAttempt = attempt;
+		void this.#finishConnect(attempt).then(
+			() => {
+				attempt.settled = true;
+				resolve();
+			},
+			error => {
+				attempt.settled = true;
+				reject(error);
+			},
+		);
+		void promise.catch(() => {});
+		return promise;
+	}
+
+	async #finishConnect(attempt: StdioConnectAttempt): Promise<void> {
+		let launch: MCPStdioPreparedLaunch = {
+			command: this.config.command,
+			args: Object.freeze([...(this.config.args ?? [])]),
+			cwd: this.config.cwd ?? process.cwd(),
+			registerCleanup: cleanup => this.#registerCleanup(attempt, cleanup),
+		};
 		const env = this.config.noInheritEnv
 			? buildMinimalStdioEnv(this.config.env)
 			: {
 					...Bun.env,
 					...this.config.env,
 				};
-		const cwd = this.config.cwd ?? process.cwd();
-
 		try {
-			this.#process = spawnOwnedProcess([this.config.command, ...args], {
-				cwd,
+			this.#assertConnectAttemptActive(attempt);
+			if (this.config.prepareSpawn) launch = await this.config.prepareSpawn(launch);
+			if (launch.afterProcessExit) this.#registerCleanup(attempt, launch.afterProcessExit);
+			else if (!this.#afterProcessExit && this.config.afterProcessExit) {
+				this.#registerCleanup(attempt, this.config.afterProcessExit);
+			}
+			this.#assertConnectAttemptActive(attempt);
+			await this.config.spawnGuard?.(launch);
+			this.#assertConnectAttemptActive(attempt);
+			await this.config.afterSpawnGuardForTest?.();
+			this.#assertConnectAttemptActive(attempt);
+			const process = spawnOwnedProcess([launch.command, ...launch.args], {
+				cwd: launch.cwd,
 				env,
 				stdin: "pipe",
 				gracefulMs: CLOSE_WAIT_MS,
-				name: `mcp-stdio:${this.config.command}`,
+				name: `mcp-stdio:${launch.command}`,
 			});
+			if (attempt.revoked) {
+				const teardown = await process.dispose();
+				await process.awaitExit({ timeoutMs: CLOSE_WAIT_MS }).catch(() => ({ exited: false, code: null }));
+				if (teardown.status !== "terminated") {
+					this.#process = process;
+					throw new MCPExpectedFailure(new Error(`stdio child teardown ${teardown.status}`));
+				}
+				throw new Error("MCP stdio connection attempt was closed");
+			}
+			this.#process = process;
 		} catch (error) {
+			if (!this.#process) {
+				try {
+					await this.#runAfterProcessExit();
+				} catch (cleanupError) {
+					throw combinedOperationAndCleanupFailure(error, cleanupError);
+				}
+			}
 			throw new MCPExpectedFailure(error);
 		}
 
@@ -367,19 +477,32 @@ export class StdioTransport implements MCPTransport {
 		}
 	}
 
+	async #runAfterProcessExit(): Promise<void> {
+		const cleanup = this.#afterProcessExit;
+		if (!cleanup) return;
+		await cleanup();
+		if (this.#afterProcessExit === cleanup) this.#afterProcessExit = null;
+	}
+
 	async close(): Promise<void> {
 		await this.#closeInternal(false);
 	}
 
 	#closeInternal(fromReadLoop: boolean, failure?: MCPExpectedFailure): Promise<void> {
 		if (this.#closePromise) return this.#closePromise;
-		this.#closePromise = this.#finishClose(fromReadLoop, failure).finally(() => {
+		const connectAttempt = this.#revokeConnectAttempt();
+		this.#closePromise = this.#finishClose(fromReadLoop, failure, connectAttempt).finally(() => {
+			if (this.#connectAttempt === connectAttempt) this.#connectAttempt = null;
 			this.#closePromise = null;
 		});
 		return this.#closePromise;
 	}
 
-	async #finishClose(fromReadLoop: boolean, failure?: MCPExpectedFailure): Promise<void> {
+	async #finishClose(
+		fromReadLoop: boolean,
+		failure: MCPExpectedFailure | undefined,
+		connectAttempt: StdioConnectAttempt | null,
+	): Promise<void> {
 		const wasConnected = this.#connected;
 		this.#connected = false;
 
@@ -388,16 +511,36 @@ export class StdioTransport implements MCPTransport {
 		}
 		this.#pendingRequests.clear();
 
+		let primaryFailure: unknown = failure;
+		if (connectAttempt) {
+			try {
+				await connectAttempt.completion;
+			} catch (error) {
+				if (primaryFailure === undefined && this.#process) primaryFailure = error;
+			}
+		}
 		const stdin = this.#getStdin();
 		const process = this.#process;
 		if (process) {
-			stdin?.end();
-			const teardown = await process.dispose();
-			await process.awaitExit({ timeoutMs: CLOSE_WAIT_MS }).catch(() => ({ exited: false, code: null }));
-			if (teardown.status !== "terminated") {
-				throw new MCPExpectedFailure(new Error(`stdio child teardown ${teardown.status}`));
+			try {
+				stdin?.end();
+				const teardown = await process.dispose();
+				await process.awaitExit({ timeoutMs: CLOSE_WAIT_MS }).catch(() => ({ exited: false, code: null }));
+				if (teardown.status !== "terminated") {
+					throw new MCPExpectedFailure(new Error(`stdio child teardown ${teardown.status}`));
+				}
+				this.#process = null;
+			} catch (cleanupError) {
+				if (primaryFailure) throw combinedOperationAndCleanupFailure(primaryFailure, cleanupError);
+				throw cleanupError;
 			}
-			this.#process = null;
+		}
+
+		try {
+			await this.#runAfterProcessExit();
+		} catch (cleanupError) {
+			if (primaryFailure) throw combinedOperationAndCleanupFailure(primaryFailure, cleanupError);
+			throw cleanupError;
 		}
 
 		if (!fromReadLoop && this.#readLoop) {
@@ -413,12 +556,3 @@ export class StdioTransport implements MCPTransport {
 		if (wasConnected) this.onClose?.();
 	}
 }
-
-/**
- * Create and connect a stdio transport.
- */
-export async function createStdioTransport(config: MCPStdioServerConfig): Promise<StdioTransport> {
-	const transport = new StdioTransport(config);
-	await transport.connect();
-	return transport;
-}

package/src/runtime-mcp/types.ts

@@ -95,6 +95,22 @@ export interface MCPServerConfigBase {
 }
 
 /** Stdio server configuration */
+export interface MCPStdioSpawnLaunch {
+	command: string;
+	args: readonly string[];
+	cwd: string;
+	/** Transport-supplied registrar for retryable cleanup before preparation allocates resources. */
+	registerCleanup?: (cleanup: () => Promise<void>) => void;
+}
+
+export interface MCPStdioPreparedLaunch extends MCPStdioSpawnLaunch {
+	/**
+	 * Per-attempt cleanup run after confirmed child exit or failed spawn. The same
+	 * callback may already have been registered during preparation.
+	 */
+	afterProcessExit?: () => Promise<void>;
+}
+
 export interface MCPStdioServerConfig extends MCPServerConfigBase {
 	type?: "stdio"; // Default if not specified
 	command: string;
@@ -108,6 +124,14 @@ export interface MCPStdioServerConfig extends MCPServerConfigBase {
 	 */
 	noInheritEnv?: boolean;
 	cwd?: string;
+	/** Internal trusted-boundary preparation of immutable per-spawn authority. */
+	prepareSpawn?: (launch: MCPStdioSpawnLaunch) => Promise<MCPStdioPreparedLaunch>;
+	/** Internal trusted-boundary check run immediately before process creation. */
+	spawnGuard?: (launch: MCPStdioSpawnLaunch) => Promise<void>;
+	/** Internal cleanup run only after the owned stdio child is confirmed exited. */
+	afterProcessExit?: () => Promise<void>;
+	/** Test seam for deterministic mutation after the guard and before process creation. */
+	afterSpawnGuardForTest?: () => Promise<void>;
 }
 
 /** HTTP server configuration (Streamable HTTP transport) */

package/src/sdk/acp/adapter.ts

@@ -875,7 +875,7 @@ export class AcpSdkAdapter {
 
 	#expiredOwnedLeaseFrame(frame: Record<string, unknown>): boolean {
 		const response = this.#leaseErrorFrame(frame);
-		if (!response || response.ok !== false) return false;
+		if (response?.ok !== false) return false;
 		const leaseId = typeof response.leaseId === "string" ? response.leaseId : "";
 		const connectionId = typeof response.connectionId === "string" ? response.connectionId : "";
 		if (!leaseId || !this.#ownsLeaseId(leaseId)) return false;

package/src/sdk/broker/broker.ts

@@ -3095,11 +3095,12 @@ export class Broker {
 		}
 		const limit = stored?.limit ?? requestedLimit ?? SESSION_LIST_DEFAULT_LIMIT;
 		const observedAt = stored?.observedAt ?? (scope === undefined ? undefined : new Date().toISOString());
+		const resolveSessionId = typeof input.resolveSessionId === "string" ? input.resolveSessionId : undefined;
 		const snapshot = stored ?? {
-			sessions:
-				scope === undefined
-					? [...result.sessions]
-					: result.sessions.filter(session => scopeMatchesLocator(scope, session.locator)),
+			sessions: (scope === undefined
+				? [...result.sessions]
+				: result.sessions.filter(session => scopeMatchesLocator(scope, session.locator))
+			).filter(session => resolveSessionId === undefined || session.sessionId === resolveSessionId),
 			indexSeq: result.indexSeq,
 			warnings: [...result.warnings],
 			limit,