@zvada/agent-server 0.3.8 → 0.3.10

package/src/core/agents/claude-code/claude-agent.ts

@@ -2,9 +2,11 @@ import type { SDKMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk"
 import type { McpSetServersResult } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentCapabilities, AgentInput, McpServerConfig } from "../../../protocol/index.ts";
 import { type DiagnosticHandler, emitDiagnostic } from "../../diagnostics.ts";
+import { SessionResumeError } from "../../utils/errors.ts";
 import type { AgentExecuteOptions, CancelResult, RawAgentEvent } from "../base.ts";
-import { BaseAgent } from "../base.ts";
+import { SessionAgent } from "../session-agent.ts";
 import type {
+	ClaudeGeneratorSession,
 	ClaudeHooksFactory,
 	ClaudeSessionEndReason,
 	ClaudeSessionExtras,
@@ -100,15 +102,15 @@ export interface ClaudeCodeAgentOptions {
 	hooks?: ClaudeHooksFactory;
 	/**
 	 * Called exactly once when a live session's subprocess ends, with why:
-	 * `idle` (idle-timeout eviction), `replaced` (config change forced a
-	 * restart), `released` (explicit release/close), `shutdown`
+	 * `idle` (idle-timeout eviction), `replaced` (config change or host resume
+	 * required a new process), `released` (explicit release/close), `shutdown`
 	 * (terminateAll). The seam for host-managed per-session resources — BYOK
 	 * proxy keys, recorders — instead of re-deriving termination from side
 	 * effects. NOTE: `replaced` sessions usually respawn immediately with
 	 * context preserved; drop only resources bound to the dead subprocess.
 	 */
 	onSessionEnd?: (sessionId: string, reason: ClaudeSessionEndReason) => void;
-	/** Operational diagnostics (interrupt timeouts, resume fallbacks). */
+	/** Operational diagnostics (interrupt timeouts). */
 	onDiagnostic?: DiagnosticHandler;
 	/**
 	 * Raw SDK option overrides merged over the engine's options at session
@@ -124,7 +126,7 @@ export interface ClaudeCodeAgentOptions {
  * in-session multi-turn and model hot-swap; falls back to SDK `resume` when a
  * session must be reconstructed (e.g. after idle eviction or across processes).
  */
-export class ClaudeCodeAgent extends BaseAgent {
+export class ClaudeCodeAgent extends SessionAgent {
 	readonly harness = "claude-code" as const;
 	readonly capabilities = CAPABILITIES;
 	private readonly manager: ClaudeSessionManager;
@@ -143,98 +145,73 @@ export class ClaudeCodeAgent extends BaseAgent {
 		};
 	}
 
-	async *execute(
+	protected override async *executeTurn(
 		input: AgentInput,
 		options: AgentExecuteOptions,
+		controller: AbortController,
 	): AsyncIterableIterator<RawAgentEvent> {
-		const controller = this.trackTurn(options.sessionId, options.signal);
+		let unconfirmedSession: ClaudeGeneratorSession | undefined;
+		let removeInterrupt: (() => void) | undefined;
 		try {
+			controller.signal.throwIfAborted();
 			const cliPath = await this.agentOptions.resolveCliPath?.();
 			const content = toClaudeContent(input);
-
-			// Attempt 0 honors resumeSessionId. The SDK does not degrade a bad
-			// resume id into a fresh session — it fails the whole turn (result
-			// error_during_execution before any output) — so a classified resume
-			// failure is swallowed and the turn reruns ONCE on a fresh session,
-			// reported as resumed:false (the structured fallback signal, acp parity).
-			//
-			// The fallback is gated on whether THIS spawn actually attempted a
-			// resume (`attemptedResume`, surfaced by the manager) — NOT on the
-			// caller's `resumeSessionId`. Restarting a live session on an
-			// immutable-config change silently spawns a resume via
-			// `claudeRestartConfig` (an auto-injected same-process resume), even
-			// when the caller passed no `resumeSessionId`; gating on caller intent
-			// would leave that invisible resume failure un-fallback'd. `attemptedResume`
-			// is per-spawn and false on the warm hot-swap path (no new spawn), so a
-			// hot-swapped session's stale stored `resumeSessionId` can't misfire it.
-			// `resuming` (caller intent) below still drives the report/strip
-			// semantics; only the resume-failure classifier reads the spawn truth.
-			for (let attempt = 0; attempt < 2; attempt++) {
-				if (controller.signal.aborted) break;
-				const resuming = attempt === 0 && Boolean(options.resumeSessionId);
-				const { session, attemptedResume } = await this.manager.getOrCreate(
-					options.sessionId,
-					{
-						...sessionConfigFrom(options, cliPath),
-						...(resuming ? {} : { resumeSessionId: undefined, resumeSessionAt: undefined }),
-					},
-					this.sessionExtras(),
-				);
-
-				let reported = false;
-				const report = (id: string) => {
-					if (reported) return;
-					reported = true;
-					options.onNativeSession?.(id, { resumed: resuming });
+			controller.signal.throwIfAborted();
+			const { session, spawned } = await this.manager.getOrCreate(
+				options.sessionId,
+				sessionConfigFrom(options, cliPath),
+				this.sessionExtras(),
+			);
+			const attemptedResume = spawned && Boolean(options.resumeSessionId);
+			if (spawned) unconfirmedSession = session;
+			// A cancel during connection repair must never submit the prompt.
+			controller.signal.throwIfAborted();
+			let reported = false;
+			const report = (id: string) => {
+				if (reported) return;
+				options.onNativeSession?.(id, { resumed: Boolean(options.resumeSessionId) });
+				reported = true;
+				unconfirmedSession = undefined;
+			};
+			// A resume is only confirmed once the backend produces output.
+			if (!attemptedResume && session.currentSessionId) report(session.currentSessionId);
+			const tap = await session.sendMessage(content, options.turnId);
+			// Install the handler after sendMessage's idle wait so it cannot
+			// overwrite a preceding turn's permission handler.
+			session.permissionHandler = options.onPermissionRequest;
+			if (controller.signal.aborted) void session.interruptTurn();
+			const onAbort = () => void session.interruptTurn();
+			controller.signal.addEventListener("abort", onAbort, { once: true });
+			removeInterrupt = () => controller.signal.removeEventListener("abort", onAbort);
+			let sawOutput = false;
+			for await (const event of tap.events) {
+				const msg = event as {
+					type?: string;
+					session_id?: string;
+					subtype?: string;
+					errors?: string[];
 				};
-				// Resume turns defer the report until output proves the resume held —
-				// a doomed attempt's id is never reported. Other turns report as soon
-				// as an id is known.
-				if (!resuming && session.currentSessionId) report(session.currentSessionId);
-
-				// `sendMessage` waits until the session is idle (any prior turn
-				// drained), then marks it busy — so installing the per-turn permission
-				// handler AFTER it resolves can't clobber a still-running turn's
-				// handler. The SDK processes the turn on later async tasks, so the
-				// handler is in place before canUseTool can fire.
-				const tap = await session.sendMessage(content, options.turnId);
-				session.permissionHandler = options.onPermissionRequest;
-				// An abort that landed while we were spawning/sending has no listener
-				// yet — interrupt directly, then arm the listener for later aborts.
-				if (controller.signal.aborted) void session.interruptTurn();
-				controller.signal.addEventListener("abort", () => void session.interruptTurn(), {
-					once: true,
-				});
-
-				let sawOutput = false;
-				let resumeFailed = false;
-				for await (const event of tap.events) {
-					const msg = event as { type?: string; session_id?: string };
-					if (msg.type === "assistant" || msg.type === "stream_event") sawOutput = true;
-					if (
-						attemptedResume &&
-						!sawOutput &&
-						!controller.signal.aborted &&
-						claudeResumeFailed(event)
-					) {
-						resumeFailed = true;
-						continue;
-					}
-					if (msg.session_id && (!resuming || sawOutput)) report(msg.session_id);
-					yield event as RawAgentEvent;
+				if (msg.type === "assistant" || msg.type === "stream_event") sawOutput = true;
+				if (
+					attemptedResume &&
+					!sawOutput &&
+					!controller.signal.aborted &&
+					claudeResumeFailed(event)
+				) {
+					const reason = msg.errors?.join("; ") || "Claude failed before loading the conversation";
+					throw new SessionResumeError(session.currentConfig.resumeSessionId!, reason, {
+						cause: new Error(reason),
+					});
 				}
-
-				if (!resumeFailed) break;
-				const failedResumeId = session.currentConfig.resumeSessionId;
-				emitDiagnostic(this.agentOptions.onDiagnostic, {
-					type: "resumeFallback",
-					sessionId: options.sessionId,
-					// Read the spawn's actual resume id (the auto-injected case has no
-					// caller `resumeSessionId`), not the caller's value.
-					message: `resume of ${failedResumeId} failed; re-running on a fresh session`,
-					detail: { resumeSessionId: failedResumeId },
-				});
-				await this.manager.terminate(options.sessionId);
+				if (msg.session_id && (!attemptedResume || sawOutput || msg.subtype === "success"))
+					report(msg.session_id);
+				yield event as RawAgentEvent;
+			}
+			if (attemptedResume && unconfirmedSession && !controller.signal.aborted) {
+				throw new SessionResumeError(
+					session.currentConfig.resumeSessionId!,
+					"Claude ended before confirming the conversation was loaded",
+				);
 			}
 
 			// Ground truth for the adapter: an interrupted turn and a turn that
@@ -242,8 +219,14 @@ export class ClaudeCodeAgent extends BaseAgent {
 			// result shape (error_during_execution, null stop_reason). Only the
 			// agent knows whether an interrupt was actually requested.
 			if (controller.signal.aborted) yield { type: "turn_interrupted" };
+		} catch (error) {
+			if (!controller.signal.aborted) throw error;
+			yield { type: "turn_interrupted" };
 		} finally {
-			this.endTurn(options.sessionId, controller);
+			removeInterrupt?.();
+			// A cancelled/failed preparation must not leave an unconfirmed query
+			// looking like a healthy warm conversation on the next attempt.
+			await unconfirmedSession?.terminate();
 		}
 	}
 
@@ -259,6 +242,11 @@ export class ClaudeCodeAgent extends BaseAgent {
 		return this.manager.setMcpServers(sessionId, servers);
 	}
 
+	/** Resume saved history in a fresh subprocess on the next turn after host suspension. */
+	invalidateMcpConnections(): void {
+		this.manager.invalidateMcpConnections();
+	}
+
 	override async cancel(sessionId: string): Promise<CancelResult> {
 		// Abort FIRST: the controller ends the engine's execute loop, so this
 		// turn classifies as cancelled even when the generator drains to a

package/src/core/agents/claude-code/generator-session.ts

@@ -8,7 +8,9 @@ import type {
 } from "@anthropic-ai/claude-agent-sdk";
 import { AsyncQueue } from "../../../protocol/index.ts";
 import type { McpServerConfig } from "../../../protocol/index.ts";
+import { SessionResumeError } from "../../utils/errors.ts";
 import type { PermissionRequestHandler } from "../base.ts";
+import { assertMcpConnected, mcpConnectionErrors, snapshotMcpServers } from "../mcp-config.ts";
 import { claudeToolMeta } from "../tool-meta.ts";
 import {
 	type ClaudeSdkOptionOverrides,
@@ -75,6 +77,22 @@ export interface ClaudeSessionExtras {
 type SessionState = "starting" | "idle" | "busy" | "terminated";
 type ClaudeContent = SDKUserMessage["message"]["content"];
 
+function remoteMcpServer(server: McpServerConfig): boolean {
+	return server.type === "http" || server.type === "sse";
+}
+
+/** Connection setup only: never retry a model turn or a tool invocation. */
+function transientMcpFailure(errors: Record<string, string>): boolean {
+	return (
+		Object.keys(errors).length > 0 &&
+		Object.values(errors).every((error) =>
+			/socket connection was closed unexpectedly|\bECONNRESET\b|\bEPIPE\b|\bETIMEDOUT\b/i.test(
+				error,
+			),
+		)
+	);
+}
+
 /** Per-turn handle: iterate `events` until the turn's `result` arrives (or the turn errors). */
 export interface ClaudeEventTap {
 	readonly events: AsyncIterable<SDKMessage>;
@@ -99,7 +117,12 @@ export class ClaudeGeneratorSession {
 	currentTurnId?: string;
 	/** Resolved once at spawn; re-merged into every hot-swap. */
 	private sdkServers?: SdkMcpServers;
+	private mcpUpdate = Promise.resolve();
+	private mcpUpdateFailed = false;
+	private readonly failedMcpServers = new Set<string>();
+	private processInvalidated = false;
 	private nativeSessionId: string | null = null;
+	private startupError: unknown;
 	/** SDK cost is cumulative within this query; token usage is already per turn. */
 	private cumulativeCost: number | undefined = 0;
 
@@ -123,7 +146,10 @@ export class ClaudeGeneratorSession {
 		private readonly onTerminated?: (reason: ClaudeSessionEndReason) => void,
 		private readonly extras?: ClaudeSessionExtras,
 	) {
-		this.config = { ...config };
+		this.config = {
+			...config,
+			mcpServers: config.mcpServers ? snapshotMcpServers(config.mcpServers) : undefined,
+		};
 		this.idleTimeoutMs = config.idleTimeoutMs ?? 5 * 60_000;
 	}
 
@@ -136,6 +162,20 @@ export class ClaudeGeneratorSession {
 	get currentConfig(): Readonly<ClaudeSessionConfig> {
 		return this.config;
 	}
+	get mcpConnectionsStale(): boolean {
+		return this.mcpUpdateFailed || this.processInvalidated;
+	}
+	/** MCP client replacement cannot clear the subprocess-wide HTTP pool. */
+	get needsProcessResume(): boolean {
+		return this.processInvalidated;
+	}
+
+	/** A thawed VM can retain clients whose sockets still appear connected. */
+	invalidateMcpConnections(): void {
+		// Latch until process replacement, even if an in-flight MCP update
+		// succeeds or the current config no longer contains remote servers.
+		this.processInvalidated = true;
+	}
 
 	/** Hot-swap the model without losing context (Claude `setModel`). */
 	async setModel(model: string | undefined): Promise<void> {
@@ -152,19 +192,87 @@ export class ClaudeGeneratorSession {
 	 */
 	async setMcpServers(
 		servers: Record<string, McpServerConfig>,
+	): Promise<McpSetServersResult | undefined> {
+		// Explicit swaps and turn preparation share the same control channel.
+		// Snapshot before queuing: callers may reuse and mutate their config.
+		const snapshot = snapshotMcpServers(servers);
+		const update = this.mcpUpdate.then(() => this.updateMcpServers(snapshot));
+		this.mcpUpdate = update.then(
+			() => {},
+			() => {},
+		);
+		return update;
+	}
+
+	private async updateMcpServers(
+		servers: Record<string, McpServerConfig>,
 	): Promise<McpSetServersResult | undefined> {
 		if (this.config.disableTools || this.state === "terminated" || !this.query) return undefined;
-		const result = await this.query.setMcpServers({ ...servers, ...this.sdkServers });
-		const failed = Object.entries(result.errors ?? {});
-		if (failed.length) {
-			// Do NOT sync config: the fingerprint stays different, so the next
-			// turn retries instead of reporting a failed set as attached.
-			throw new Error(
-				`mcp servers failed to connect: ${failed.map(([n, e]) => `${n} (${e})`).join(", ")}`,
+		if (this.needsProcessResume)
+			throw new Error("Claude process must resume after host suspension");
+		const query = this.query;
+		const reconnect = this.mcpUpdateFailed;
+		const resetNames = Object.keys(servers).filter((name) => this.failedMcpServers.has(name));
+		const desired = { ...servers, ...this.sdkServers };
+		const added = new Set<string>();
+		const removed = new Set<string>();
+		const applyDesired = async () => {
+			const result = await query.setMcpServers(desired);
+			for (const name of result.added) added.add(name);
+			for (const name of result.removed) removed.add(name);
+			return result;
+		};
+		// A failed SDK update is not transactional: it can cache the new config
+		// with a failed client, then return errors:{} for the identical retry.
+		// Keep that uncertainty until a verified reattachment succeeds.
+		this.mcpUpdateFailed = true;
+		const check = (errors: Record<string, string>) => {
+			for (const name of Object.keys(errors)) this.failedMcpServers.add(name);
+			assertMcpConnected(errors);
+		};
+		const reattach = async (names: string[]) => {
+			const detached = { ...desired };
+			for (const name of names) {
+				if (!this.sdkServers?.[name]) delete detached[name];
+			}
+			check((await query.setMcpServers(detached)).errors ?? {});
+			return applyDesired();
+		};
+		let result = await applyDesired();
+		let retried = false;
+		if (reconnect) {
+			if (!transientMcpFailure(result.errors ?? {})) check(result.errors ?? {});
+			retried = Object.keys(result.errors ?? {}).length > 0;
+			result = await reattach([...new Set([...resetNames, ...Object.keys(result.errors ?? {})])]);
+		}
+		const failed = Object.keys(result.errors ?? {});
+		const retry =
+			!retried &&
+			transientMcpFailure(result.errors ?? {}) &&
+			failed.every(
+				(name) => servers[name] && remoteMcpServer(servers[name]!) && !this.sdkServers?.[name],
 			);
+		if (retry) {
+			// reconnectMcpServer(name) can restore the CLI's STARTUP credentials.
+			// Removing and adding uses this turn's exact configuration instead.
+			result = await reattach(failed);
+		}
+		check(result.errors ?? {});
+		// In-process SDK servers initialize lazily at the first prompt and are
+		// absent from startup status. This barrier checks external connections.
+		const required = Object.keys(desired).filter((name) => desired[name]?.type !== "sdk");
+		if (required.length) {
+			const statuses = await query.mcpServerStatus();
+			check(mcpConnectionErrors(required, statuses));
 		}
 		this.config = { ...this.config, mcpServers: servers };
-		return result;
+		this.mcpUpdateFailed = false;
+		this.failedMcpServers.clear();
+		return {
+			added: [...added],
+			removed: [...removed],
+			errors: result.errors,
+		};
 	}
 
 	async start(): Promise<void> {
@@ -175,7 +283,10 @@ export class ClaudeGeneratorSession {
 			cwd: this.config.cwd,
 		});
 		const options = buildClaudeOptions(
-			this.config,
+			// CLI startup MCP entries can survive the first dynamic removal and
+			// reconnect-by-name can reuse their original credentials. Give every
+			// wire server one owner: register it dynamically before the first turn.
+			{ ...this.config, mcpServers: {} },
 			this.sdkServers,
 			await this.extras?.sdkOptions?.({ sessionId: this.id, cwd: this.config.cwd }),
 		);
@@ -192,11 +303,31 @@ export class ClaudeGeneratorSession {
 			policy: this.extras?.toolPolicy,
 			getBroker: () => this.permissionHandler,
 		});
+		// Release/shutdown may finish while an async options/tool factory is
+		// pending. Never create a query after its owner has already terminated.
+		if (this.currentState === "terminated") throw new Error("Session terminated during startup");
 		this.query = sdk.query({
 			prompt: this.promptQueue as AsyncIterable<SDKUserMessage>,
 			options,
 		});
-		void this.consumeEvents();
+		const consumption = this.consumeEvents();
+		if (!this.config.disableTools && Object.keys(this.config.mcpServers ?? {}).length) {
+			try {
+				await this.setMcpServers(this.config.mcpServers!);
+			} catch (error) {
+				// Closing after an early result also rejects pending MCP controls.
+				// The SDK rejects controls before its iterator delivers that result.
+				if (error instanceof Error && error.message === "Query closed before response received") {
+					await consumption;
+				}
+				throw this.startupError ?? error;
+			}
+		}
+		if (this.startupError) throw this.startupError;
+		// TypeScript retains the pre-query narrowing across await; termination can
+		// happen while the initial MCP attachment is in flight.
+		if ((this.currentState as SessionState) === "terminated")
+			throw new Error("Session terminated during startup");
 		this.state = "idle";
 		this.resetIdleTimer();
 	}
@@ -204,9 +335,17 @@ export class ClaudeGeneratorSession {
 	/** Push a user message; returns a tap that streams this turn's events. */
 	async sendMessage(content: ClaudeContent, turnId?: string): Promise<ClaudeEventTap> {
 		while (this.state !== "idle") {
-			if (this.state === "terminated") throw new Error("Session is terminated");
+			if (this.state === "terminated")
+				throw this.startupError ?? new Error("Session is terminated");
 			await this.waitForIdle();
 		}
+		// Invalidation can land during preparation or the idle wait. Never
+		// enqueue a prompt on a process whose network pool predates suspension.
+		if (this.needsProcessResume || (!this.config.disableTools && this.mcpConnectionsStale)) {
+			throw new Error(
+				"MCP network connections changed during turn preparation; session is not ready",
+			);
+		}
 		this.clearIdleTimer();
 		this.state = "busy";
 		// After the idle wait, so a queued turn can't relabel the in-flight one.
@@ -288,6 +427,14 @@ export class ClaudeGeneratorSession {
 				}
 				if (event.type === "conversation_reset") this.cumulativeCost = 0;
 				if (event.type === "result") {
+					if (!this.currentTap && event.subtype !== "success") {
+						const reason = event.errors.join("; ") || "Claude failed during startup";
+						throw this.config.resumeSessionId
+							? new SessionResumeError(this.config.resumeSessionId, reason, {
+									cause: new Error(reason),
+								})
+							: new Error(reason);
+					}
 					// Keep the native total intact for raw diagnostics. A crash can
 					// report a zeroed total; that does not establish this turn's cost.
 					const result = {
@@ -308,6 +455,7 @@ export class ClaudeGeneratorSession {
 				}
 			}
 		} catch (err) {
+			if (!this.currentTap) this.startupError = err;
 			this.currentTap?.fail(err);
 		} finally {
 			await this.terminate();

package/src/core/agents/claude-code/session-manager.ts

@@ -5,10 +5,10 @@ import { ClaudeGeneratorSession } from "./generator-session.ts";
 import type { ClaudeSessionEndReason, ClaudeSessionExtras } from "./generator-session.ts";
 import type { ClaudeSessionConfig } from "./options.ts";
 
-/** The selected session and whether this invocation spawned it with a resume target. */
+/** The selected session and whether this invocation owns its new startup. */
 export interface ClaudeSessionSpawn {
 	session: ClaudeGeneratorSession;
-	attemptedResume: boolean;
+	spawned: boolean;
 }
 
 /** Directory-set identity: order and duplicates don't change the sandbox surface. */
@@ -27,7 +27,7 @@ export function claudeSessionNeedsRestart(
 		(prev.permissionMode ?? "") !== (next.permissionMode ?? "") ||
 		// thinking/effort are fixed at spawn in the modern SDK vocabulary (the
 		// old setMaxThinkingTokens hot-swap is deprecated and effort-blind), so
-		// a level change restarts — context survives via claudeRestartConfig.
+		// a level change restarts with the prepared resume target.
 		(prev.thinkingLevel ?? "") !== (next.thinkingLevel ?? "") ||
 		(prev.systemPromptAppend ?? "") !== (next.systemPromptAppend ?? "") ||
 		// A rewind (resumeSessionAt) is applied by the SDK only at spawn, so a
@@ -48,26 +48,12 @@ export function claudeSessionNeedsRestart(
 	);
 }
 
-/** Preserve context within the same cwd/credential boundary; explicit resume always wins. */
-export function claudeRestartConfig(
-	previous: ClaudeSessionConfig,
-	next: ClaudeSessionConfig,
-	nativeSessionId: string | null,
-): ClaudeSessionConfig {
-	if (next.resumeSessionId || !nativeSessionId) return next;
-	const sameResumeBoundary =
-		previous.cwd === next.cwd &&
-		(previous.apiKey ?? "") === (next.apiKey ?? "") &&
-		configFingerprint(previous.env) === configFingerprint(next.env);
-	return sameResumeBoundary ? { ...next, resumeSessionId: nativeSessionId } : next;
-}
-
 /**
  * One live `ClaudeGeneratorSession` per logical session id. Decides, per turn,
  * whether the existing session can be reused (hot-swapping model/mcp) or must
  * be torn down and recreated (cwd / permission / thinking / system-prompt
- * changes alter the subprocess in ways the live query can't). `resumeSessionId`
- * is read only at spawn — it never forces a restart on a warm session.
+ * changes alter the subprocess in ways the live query can't). A different
+ * resume target must also spawn; a warm process cannot switch conversations.
  */
 export class ClaudeSessionManager {
 	private readonly sessions = new Map<string, ClaudeGeneratorSession>();
@@ -81,27 +67,31 @@ export class ClaudeSessionManager {
 		config: ClaudeSessionConfig,
 		extras?: ClaudeSessionExtras,
 	): Promise<ClaudeSessionSpawn> {
-		let startConfig = config;
 		const existing = this.sessions.get(sessionId);
 		if (existing && existing.currentState !== "terminated") {
-			if (this.needsRestart(existing.currentConfig, config)) {
-				startConfig = claudeRestartConfig(
-					existing.currentConfig,
-					config,
-					existing.currentSessionId,
-				);
+			const differentTarget =
+				config.resumeSessionId &&
+				config.resumeSessionId !== existing.currentSessionId &&
+				config.resumeSessionId !== existing.currentConfig.resumeSessionId;
+			if (
+				differentTarget ||
+				existing.needsProcessResume ||
+				claudeSessionNeedsRestart(existing.currentConfig, config)
+			) {
+				// Host suspension invalidates the process-wide HTTP pool, including
+				// sockets for removed MCP servers. Use the same strict saved-history
+				// resume as idle eviction, with the next turn's prepared config.
 				await existing.terminate("replaced");
 				this.sessions.delete(sessionId);
 			} else {
 				await this.hotSwapIfNeeded(existing, config);
-				// A warm session's stored resume id describes its original spawn.
-				return { session: existing, attemptedResume: false };
+				return { session: existing, spawned: false };
 			}
 		}
 
 		const session = new ClaudeGeneratorSession(
 			sessionId,
-			startConfig,
+			config,
 			(reason) => {
 				if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
 				this.onSessionEnd?.(sessionId, reason);
@@ -113,12 +103,11 @@ export class ClaudeSessionManager {
 			await session.start();
 		} catch (err) {
 			// Don't leave a half-started session in the map — it could never serve a turn.
-			this.sessions.delete(sessionId);
+			await session.terminate();
+			if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
 			throw err;
 		}
-		// Whether THIS spawn carried a `resumeSessionId`: an explicit caller resume
-		// OR the manager's auto-injected resume on an immutable-config restart.
-		return { session, attemptedResume: Boolean(startConfig.resumeSessionId) };
+		return { session, spawned: true };
 	}
 
 	get(sessionId: string): ClaudeGeneratorSession | undefined {
@@ -137,8 +126,8 @@ export class ClaudeSessionManager {
 		this.sessions.clear();
 	}
 
-	private needsRestart(prev: ClaudeSessionConfig, next: ClaudeSessionConfig): boolean {
-		return claudeSessionNeedsRestart(prev, next);
+	invalidateMcpConnections(): void {
+		for (const session of this.sessions.values()) session.invalidateMcpConnections();
 	}
 
 	private async hotSwapIfNeeded(
@@ -151,8 +140,9 @@ export class ClaudeSessionManager {
 		// Text-only sessions must stay tool-free when the MCP configuration changes.
 		if (
 			!next.disableTools &&
-			configFingerprint(next.mcpServers ?? {}) !==
-				configFingerprint(session.currentConfig.mcpServers ?? {})
+			(session.mcpConnectionsStale ||
+				configFingerprint(next.mcpServers ?? {}) !==
+					configFingerprint(session.currentConfig.mcpServers ?? {}))
 		) {
 			await session.setMcpServers(next.mcpServers ?? {});
 		}