Merge pull request #377 from code-yeongyu/perf/mcp-reload-measure

feat(mcp): keep unchanged MCP servers alive across a classic /reload

Author: code-yeongyu

packages/coding-agent/src/changes.md

@@ -21,6 +21,13 @@
 - Root cause of the omo `team_wait` starvation forensics: member self-poller injections via `pi.sendUserMessage(..., { deliverAs: "followUp" })` vanished without a trace when the fresh-prompt path threw, leaving no record in the session JSONL while RPC-path `steer`/`follow_up` commands (which bypass `prompt()`) landed normally.
 - Interactive `prompt()` behavior is unchanged: a rejected interactive prompt still drops the input and surfaces the error to the user (pinned by `test/suite/regressions/pre-prompt-compaction-no-continue.test.ts`).
 - Coverage: `test/suite/agent-session-extension-injection.test.ts` pins retention for followUp and steer injections, exact-once delivery after recovery through the post-run drain, and no double-queueing on the streaming accept path.
+
+## Reload-safe MCP preservation and extension-removal lifecycle event (2026-07-26)
+
+- `session_extensions_removed` is emitted on the old extension runner when a `/reload` or a session replacement (`/new`, `/resume`, `/fork`, import) rebuilds the extension set. Its payload is `{ type: "session_extensions_removed", reason: SessionShutdownEvent["reason"], removed: Array<{ path, resolvedPath }> }`, allowing an extension that did not survive the rebuild to release resources after the new settings and active builtin set are known.
+- Unchanged MCP servers now survive a classic `/reload`: the shared service reattaches and reconciles by config hash, preserving live connections while replacing changed servers and disposing removed ones. Provider-scoped MCP services still dispose on reload because their factory creates a replacement instance.
+- If the MCP builtin itself is disabled during a reload or replacement, its removal event disposes the preserved classic service so stdio children cannot leak. For an otherwise wedged server, use `/mcp reconnect <name>` to force a fresh connection.
+
 ## Same-model-first transient retries and capped server waits (2026-07-26)
 
 ### What changed

packages/coding-agent/src/core/agent-session-runtime.ts

@@ -9,7 +9,7 @@ import type {
 	SessionShutdownEvent,
 	SessionStartEvent,
 } from "./extensions/index.ts";
-import { emitSessionShutdownEvent } from "./extensions/runner.ts";
+import { type ExtensionRunner, emitSessionShutdownEvent } from "./extensions/runner.ts";
 import type { CreateAgentSessionResult } from "./sdk.ts";
 import { assertSessionCwdExists } from "./session-cwd.ts";
 import { SessionManager } from "./session-manager.ts";
@@ -89,6 +89,11 @@ export class AgentSessionRuntime {
 	private _diagnostics: AgentSessionRuntimeDiagnostic[];
 	private _modelFallbackMessage?: string;
 	private readonly _launchProfile?: Readonly<AgentSessionLaunchProfile>;
+	private _removedOnReplacement?: {
+		oldRunner: ExtensionRunner;
+		oldIdentities: Array<{ path: string; resolvedPath: string }>;
+		reason: SessionShutdownEvent["reason"];
+	};
 
 	constructor(
 		_session: AgentSession,
@@ -181,7 +186,17 @@ export class AgentSessionRuntime {
 	}
 
 	private async teardownCurrent(reason: SessionShutdownEvent["reason"], targetSessionFile?: string): Promise<void> {
-		await emitSessionShutdownEvent(this.session.extensionRunner, {
+		const oldRunner = this.session.extensionRunner;
+		// Test hosts and partial runner implementations may lack identity introspection;
+		// skip removal reporting there rather than break the replacement itself.
+		if (typeof oldRunner.getExtensionIdentities === "function") {
+			this._removedOnReplacement = {
+				oldRunner,
+				oldIdentities: oldRunner.getExtensionIdentities(),
+				reason,
+			};
+		}
+		await emitSessionShutdownEvent(oldRunner, {
 			type: "session_shutdown",
 			reason,
 			targetSessionFile,
@@ -190,11 +205,26 @@ export class AgentSessionRuntime {
 		this.session.dispose();
 	}
 
-	private apply(result: CreateAgentSessionRuntimeResult): void {
+	private async reportRemovedExtensions(): Promise<void> {
+		const pending = this._removedOnReplacement;
+		this._removedOnReplacement = undefined;
+		if (!pending) return;
+		const newRunner = this.session.extensionRunner;
+		if (typeof newRunner.getExtensionIdentities !== "function") return;
+		const newResolvedPaths = new Set(
+			newRunner.getExtensionIdentities().map((extension) => extension.resolvedPath),
+		);
+		const removed = pending.oldIdentities.filter((extension) => !newResolvedPaths.has(extension.resolvedPath));
+		if (removed.length === 0) return;
+		await pending.oldRunner.emit({ type: "session_extensions_removed", reason: pending.reason, removed });
+	}
+
+	private async apply(result: CreateAgentSessionRuntimeResult): Promise<void> {
 		this._session = result.session;
 		this._services = result.services;
 		this._diagnostics = result.diagnostics;
 		this._modelFallbackMessage = result.modelFallbackMessage;
+		await this.reportRemovedExtensions();
 	}
 
 	private async finishSessionReplacement(withSession?: (ctx: ReplacedSessionContext) => Promise<void>): Promise<void> {
@@ -223,7 +253,7 @@ export class AgentSessionRuntime {
 		const sessionManager = SessionManager.open(sessionPath, undefined, options?.cwdOverride);
 		assertSessionCwdExists(sessionManager, this.cwd);
 		await this.teardownCurrent("resume", sessionManager.getSessionFile());
-		this.apply(
+		await this.apply(
 			await this.createRuntime({
 				cwd: sessionManager.getCwd(),
 				agentDir: this.services.agentDir,
@@ -257,7 +287,7 @@ export class AgentSessionRuntime {
 		}
 
 		await this.teardownCurrent("new", sessionManager.getSessionFile());
-		this.apply(
+		await this.apply(
 			await this.createRuntime({
 				cwd: this.cwd,
 				agentDir: this.services.agentDir,
@@ -312,7 +342,7 @@ export class AgentSessionRuntime {
 				const sessionManager = SessionManager.create(this.cwd, sessionDir);
 				sessionManager.newSession({ parentSession: currentSessionFile });
 				await this.teardownCurrent("fork", sessionManager.getSessionFile());
-				this.apply(
+				await this.apply(
 					await this.createRuntime({
 						cwd: this.cwd,
 						agentDir: this.services.agentDir,
@@ -336,7 +366,7 @@ export class AgentSessionRuntime {
 				throw new Error("Failed to create forked session");
 			}
 			await this.teardownCurrent("fork", sessionManager.getSessionFile());
-			this.apply(
+			await this.apply(
 				await this.createRuntime({
 					cwd: sessionManager.getCwd(),
 					agentDir: this.services.agentDir,
@@ -356,7 +386,7 @@ export class AgentSessionRuntime {
 			sessionManager.createBranchedSession(targetLeafId);
 		}
 		await this.teardownCurrent("fork", sessionManager.getSessionFile());
-		this.apply(
+		await this.apply(
 			await this.createRuntime({
 				cwd: this.cwd,
 				agentDir: this.services.agentDir,
@@ -401,7 +431,7 @@ export class AgentSessionRuntime {
 		const sessionManager = SessionManager.open(destinationPath, sessionDir, cwdOverride);
 		assertSessionCwdExists(sessionManager, this.cwd);
 		await this.teardownCurrent("resume", sessionManager.getSessionFile());
-		this.apply(
+		await this.apply(
 			await this.createRuntime({
 				cwd: sessionManager.getCwd(),
 				agentDir: this.services.agentDir,

packages/coding-agent/src/core/agent-session.ts

@@ -4976,8 +4976,10 @@ export class AgentSession {
 
 	async reload(options?: { beforeSessionStart?: () => void | Promise<void> }): Promise<void> {
 		resetTimings("reload");
-		const previousFlagValues = this._extensionRunner.getFlagValues();
-		await emitSessionShutdownEvent(this._extensionRunner, { type: "session_shutdown", reason: "reload" });
+		const oldExtensionRunner = this._extensionRunner;
+		const oldExtensionIdentities = oldExtensionRunner.getExtensionIdentities();
+		const previousFlagValues = oldExtensionRunner.getFlagValues();
+		await emitSessionShutdownEvent(oldExtensionRunner, { type: "session_shutdown", reason: "reload" });
 		time("shutdown", "reload");
 		await this.settingsManager.reload();
 		this.syncQueueModesFromSettings();
@@ -5003,12 +5005,27 @@ export class AgentSession {
 		time("models", "reload");
 		await this._resourceLoader.reload({ settingsAlreadyReloadedFor: this.settingsManager });
 		time("resources", "reload");
-		this._buildRuntime({
-			activeToolNames: this.getActiveToolNames(),
-			flagValues: previousFlagValues,
-			includeAllExtensionTools: true,
-		});
-		time("runtime", "reload");
+		try {
+			this._buildRuntime({
+				activeToolNames: this.getActiveToolNames(),
+				flagValues: previousFlagValues,
+				includeAllExtensionTools: true,
+			});
+		} finally {
+			// An extension removed by this reload must be told even if the rebuild throws
+			// (e.g. _refreshToolRegistry rejecting an extension's tool metadata): the new
+			// runner is already installed without it, so nothing else would dispose it.
+			const newExtensionResolvedPaths = new Set(
+				this._extensionRunner.getExtensionIdentities().map((extension) => extension.resolvedPath),
+			);
+			const removed = oldExtensionIdentities.filter(
+				(extension) => !newExtensionResolvedPaths.has(extension.resolvedPath),
+			);
+			if (removed.length > 0) {
+				await oldExtensionRunner.emit({ type: "session_extensions_removed", reason: "reload", removed });
+			}
+			time("runtime", "reload");
+		}
 
 		const hasBindings =
 			this._extensionUIContext ||

packages/coding-agent/src/core/extensions/builtin/mcp/changes.md

@@ -1,5 +1,22 @@
 # mcp Extension Changes
 
+## Classic reload preserves unchanged MCP servers (2026-07-26)
+
+### What changed
+- Classic (non-provider-scoped) MCP reloads keep the shared `McpService` alive. The reload-time `session_start` reattaches it and its existing config-hash reconciliation preserves unchanged servers while replacing changed definitions and disposing removed definitions.
+- Provider-scoped MCP services still dispose on `reload`, because rebuilding an extension factory creates a new scoped instance and preserving the old one would orphan its child processes.
+- Core now emits `{ type: "session_extensions_removed", reason: "reload", removed: Array<{ path, resolvedPath }> }` on the old runner after it knows the rebuilt extension set. MCP matches its builtin identity (`<builtin:mcp>`) in that event and disposes the preserved classic service when MCP is disabled during a reload.
+- `/mcp reconnect <name>` remains the explicit escape hatch for a server that is connected but wedged: it renews that server without requiring a full reload.
+
+### Why
+- Spawning every MCP server again on every classic reload adds a fixed process startup cost even when config is unchanged. Preserving and reconciling retains healthy children, while the removal event closes the only gap where the preserved singleton otherwise loses its owning extension.
+
+### Why extension system couldn't handle this alone
+- The core alone can identify removed extension entries but must remain resource-agnostic; MCP alone cannot know the post-reload builtin set at `session_shutdown`. The core event provides the lifecycle boundary and MCP owns the service-specific disposal.
+
+### Expected merge conflict zones
+- LOW: `index.ts` lifecycle handlers; `service.ts` remains the config-hash reconciliation owner.
+
 ## Raced background registration replays session state (2026-07-21)
 
 ### What changed

packages/coding-agent/src/core/extensions/builtin/mcp/index.ts

@@ -16,6 +16,8 @@ import {
 } from "./skills.ts";
 import { reportMcpAsyncError, wrapAsync } from "./wrap.ts";
 
+const MCP_BUILTIN_EXTENSION_PATH = "<builtin:mcp>";
+
 export function createMcpExtension(service: McpService, sessionOwned = true): ExtensionFactory {
 	return (pi: ExtensionAPI): void => {
 		let attachPromise: Promise<void> | undefined;
@@ -149,11 +151,20 @@ export function createMcpExtension(service: McpService, sessionOwned = true): Ex
 			wrapAsync(
 				"mcp.session_shutdown",
 				async (event) => {
+					if (event.reason === "reload" && !sessionOwned) return;
 					await service.handleSessionShutdown(event);
-					// A classic extension instance can be reused by the test/legacy host
-					// after reload. Its singleton is intentionally refreshed for that next
-					// session; scoped factories keep their closed instance.
-					if (!sessionOwned && event.reason === "reload" && service.isDisposed()) service = getMcpService();
+				},
+				sink,
+			),
+		);
+		pi.on(
+			"session_extensions_removed",
+			wrapAsync(
+				"mcp.session_extensions_removed",
+				async (event) => {
+					if (event.removed.some((extension) => extension.path === MCP_BUILTIN_EXTENSION_PATH)) {
+						await service.dispose("reload");
+					}
 				},
 				sink,
 			),

packages/coding-agent/src/core/extensions/runner.ts

@@ -591,6 +591,10 @@ export class ExtensionRunner {
 		return this.extensions.map((e) => e.path);
 	}
 
+	getExtensionIdentities(): Array<{ path: string; resolvedPath: string }> {
+		return this.extensions.map(({ path, resolvedPath }) => ({ path, resolvedPath }));
+	}
+
 	/**
 	 * Get all registered tools from all extensions. The first registration within a source tier
 	 * wins, while a non-builtin extension may override a builtin extension tool.

packages/coding-agent/src/core/extensions/types.ts

@@ -773,6 +773,13 @@ export interface SessionShutdownEvent {
 	targetSessionFile?: string;
 }
 
+/** Fired on the old extension runner when a reload or session replacement rebuilds the runner and one or more extensions are absent from it. */
+export interface SessionExtensionsRemovedEvent {
+	type: "session_extensions_removed";
+	reason: SessionShutdownEvent["reason"];
+	removed: Array<{ path: string; resolvedPath: string }>;
+}
+
 /** Preparation data for tree navigation */
 export interface TreePreparation {
 	targetId: string;
@@ -812,6 +819,7 @@ export type SessionEvent =
 	| SessionBeforeCompactEvent
 	| SessionCompactEvent
 	| SessionShutdownEvent
+	| SessionExtensionsRemovedEvent
 	| SessionBeforeTreeEvent
 	| SessionTreeEvent;
 
@@ -1401,6 +1409,7 @@ export interface ExtensionAPI {
 	): void;
 	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
 	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_extensions_removed", handler: ExtensionHandler<SessionExtensionsRemovedEvent>): void;
 	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
 	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
 	on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;