@zvada/agent-server 0.3.9 → 0.3.11

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,100 +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(),
-				);
-				// A cancel during connection repair must never submit the prompt.
-				if (controller.signal.aborted) break;
-
-				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
@@ -248,7 +223,10 @@ export class ClaudeCodeAgent extends BaseAgent {
 			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();
 		}
 	}
 
@@ -264,7 +242,7 @@ export class ClaudeCodeAgent extends BaseAgent {
 		return this.manager.setMcpServers(sessionId, servers);
 	}
 
-	/** Reattach remote MCP servers before the next turn after a host resumes. */
+	/** Resume saved history in a fresh subprocess on the next turn after host suspension. */
 	invalidateMcpConnections(): void {
 		this.manager.invalidateMcpConnections();
 	}

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,
@@ -91,15 +93,6 @@ function transientMcpFailure(errors: Record<string, string>): boolean {
 	);
 }
 
-function assertMcpConnected(errors: Record<string, string>): void {
-	const failed = Object.entries(errors);
-	if (failed.length) {
-		throw new Error(
-			`mcp servers failed to connect: ${failed.map(([name, error]) => `${name} (${error})`).join(", ")}`,
-		);
-	}
-}
-
 /** Per-turn handle: iterate `events` until the turn's `result` arrives (or the turn errors). */
 export interface ClaudeEventTap {
 	readonly events: AsyncIterable<SDKMessage>;
@@ -127,9 +120,11 @@ export class ClaudeGeneratorSession {
 	private mcpUpdate = Promise.resolve();
 	private mcpUpdateFailed = false;
 	private readonly failedMcpServers = new Set<string>();
-	private mcpConnectionGeneration = 0;
-	private connectedMcpGeneration = 0;
+	private processInvalidated = false;
 	private nativeSessionId: string | null = null;
+	/** Set by the CLI's first message; until then it has begun no turn. */
+	private cliStarted = false;
+	private startupError: unknown;
 	/** SDK cost is cumulative within this query; token usage is already per turn. */
 	private cumulativeCost: number | undefined = 0;
 
@@ -153,7 +148,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;
 	}
 
@@ -167,18 +165,18 @@ export class ClaudeGeneratorSession {
 		return this.config;
 	}
 	get mcpConnectionsStale(): boolean {
-		return (
-			this.mcpUpdateFailed ||
-			(this.mcpConnectionGeneration !== this.connectedMcpGeneration &&
-				Object.values(this.config.mcpServers ?? {}).some(remoteMcpServer))
-		);
+		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 {
-		// Also retain a signal that lands while the first remote server is
-		// being attached and currentConfig still has no remote servers.
-		this.mcpConnectionGeneration++;
+		// 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`). */
@@ -198,7 +196,9 @@ export class ClaudeGeneratorSession {
 		servers: Record<string, McpServerConfig>,
 	): Promise<McpSetServersResult | undefined> {
 		// Explicit swaps and turn preparation share the same control channel.
-		const update = this.mcpUpdate.then(() => this.updateMcpServers(servers));
+		// 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(
 			() => {},
 			() => {},
@@ -210,14 +210,11 @@ export class ClaudeGeneratorSession {
 		servers: Record<string, McpServerConfig>,
 	): Promise<McpSetServersResult | undefined> {
 		if (this.config.disableTools || this.state === "terminated" || !this.query) return undefined;
+		if (this.needsProcessResume)
+			throw new Error("Claude process must resume after host suspension");
 		const query = this.query;
-		const reconnect = this.mcpConnectionsStale;
-		const generation = this.mcpConnectionGeneration;
-		const resetNames = Object.keys(servers).filter(
-			(name) =>
-				this.failedMcpServers.has(name) ||
-				(generation !== this.connectedMcpGeneration && remoteMcpServer(servers[name]!)),
-		);
+		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>();
@@ -263,23 +260,16 @@ export class ClaudeGeneratorSession {
 			result = await reattach(failed);
 		}
 		check(result.errors ?? {});
-		if (reconnect || retry) {
+		// 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(
-				Object.fromEntries(
-					Object.keys(desired).flatMap((name) => {
-						const status = statuses.find((entry) => entry.name === name);
-						return status?.status === "connected"
-							? []
-							: [[name, status?.error ?? `server is ${status?.status ?? "missing"}`]];
-					}),
-				),
-			);
+			check(mcpConnectionErrors(required, statuses));
 		}
 		this.config = { ...this.config, mcpServers: servers };
 		this.mcpUpdateFailed = false;
 		this.failedMcpServers.clear();
-		this.connectedMcpGeneration = generation;
 		return {
 			added: [...added],
 			removed: [...removed],
@@ -315,15 +305,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) {
-			await this.setMcpServers(this.config.mcpServers!);
+			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.currentState === "terminated") throw new Error("Session terminated during startup");
+		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();
 	}
@@ -331,9 +337,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.
@@ -363,9 +377,17 @@ export class ClaudeGeneratorSession {
 	 * SDK acknowledged it; false when the round-trip timed out or failed — the
 	 * subprocess may still be running its turn and the caller must report that
 	 * honestly instead of assuming a clean cancel.
+	 *
+	 * A session still starting, or whose CLI has sent nothing yet, is terminated
+	 * instead: it has begun no turn, an interrupt would wait out its startup, and
+	 * a prompt the CLI has not dequeued survives an interrupt and runs anyway.
 	 */
 	async interruptTurn(timeoutMs = 2000): Promise<boolean> {
-		if ((this.state !== "busy" && this.state !== "starting") || !this.query) return true;
+		if (this.state === "idle" || this.state === "terminated") return true;
+		if (this.state === "starting" || !this.cliStarted || !this.query) {
+			await this.terminate();
+			return true;
+		}
 		let timer: ReturnType<typeof setTimeout> | undefined;
 		try {
 			await Promise.race([
@@ -410,11 +432,20 @@ export class ClaudeGeneratorSession {
 		if (!this.query) return;
 		try {
 			for await (const event of this.query) {
+				this.cliStarted = true;
 				if (event.type === "system" && event.subtype === "init" && event.session_id) {
 					this.nativeSessionId = event.session_id;
 				}
 				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 = {
@@ -435,6 +466,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);
@@ -117,9 +107,7 @@ export class ClaudeSessionManager {
 			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 {
@@ -142,10 +130,6 @@ export class ClaudeSessionManager {
 		for (const session of this.sessions.values()) session.invalidateMcpConnections();
 	}
 
-	private needsRestart(prev: ClaudeSessionConfig, next: ClaudeSessionConfig): boolean {
-		return claudeSessionNeedsRestart(prev, next);
-	}
-
 	private async hotSwapIfNeeded(
 		session: ClaudeGeneratorSession,
 		next: ClaudeSessionConfig,