@gajae-code/coding-agent 0.16.1 → 0.16.4

package/src/modes/controllers/event-controller.ts

@@ -128,6 +128,15 @@ type AgentSessionEventHandlers = {
 	[E in AgentSessionEventKind]: (event: Extract<AgentSessionEvent, { type: E }>) => Promise<void>;
 };
 
+interface AssistantTextPresentation {
+	component: AssistantMessageComponent;
+	latestMessage: AssistantMessage;
+	sessionIdentity: InteractiveModeContext["session"];
+	sessionEpoch: number;
+	paintEpoch: number;
+	cancel: () => void;
+}
+
 export class EventController {
 	#lastReadGroup: ReadToolGroupComponent | undefined = undefined;
 	#lastThinkingCount = 0;
@@ -146,6 +155,16 @@ export class EventController {
 	#visibleTranscriptChanged = false;
 	#handlingEvent = false;
 	#eventQueue: Promise<void> = Promise.resolve();
+	#disposed = false;
+	#assistantTextSuspended = false;
+	#sessionPresentationEpoch = 0;
+	#paintEpoch = 0;
+	#pendingAssistantText: AssistantTextPresentation | undefined;
+	#assistantTextMutationScope: AssistantTextPresentation | undefined;
+	#assistantLifetimes = new WeakMap<
+		AssistantMessageComponent,
+		{ sessionIdentity: InteractiveModeContext["session"]; sessionEpoch: number }
+	>();
 
 	constructor(private ctx: InteractiveModeContext) {
 		this.#handlers = {
@@ -177,6 +196,8 @@ export class EventController {
 	}
 
 	dispose(): void {
+		this.#disposed = true;
+		this.resetAssistantTextPresentation();
 		this.#cancelIdleCompaction();
 		this.#clearRetryCountdown();
 		if (this.ctx.retryEscapeHandler) {
@@ -199,6 +220,104 @@ export class EventController {
 		this.clearIrcExpiryTimers();
 	}
 
+	#cancelAssistantTextPresentation(): void {
+		const pending = this.#pendingAssistantText;
+		this.#pendingAssistantText = undefined;
+		pending?.cancel();
+	}
+
+	/** Temporary TUI stop discards scheduling, not historical assistant callback lifetimes. */
+	suspendAssistantTextPresentation(): void {
+		this.#assistantTextSuspended = true;
+		this.#paintEpoch += 1;
+		this.#cancelAssistantTextPresentation();
+	}
+
+	/** Rearm before the first restarted frame, even without a new provider event. */
+	resumeAssistantTextPresentation(): void {
+		this.#cancelAssistantTextPresentation();
+		this.#assistantTextSuspended = false;
+		const component = this.ctx.streamingComponent;
+		const message = this.ctx.streamingMessage;
+		if (component && message && this.#isLiveAssistant(component)) {
+			this.#queueAssistantText(component, message);
+		}
+	}
+
+	/** Session/transcript replacement invalidates callbacks before removing old children. */
+	resetAssistantTextPresentation(): void {
+		this.#sessionPresentationEpoch += 1;
+		this.#cancelAssistantTextPresentation();
+	}
+
+	#isLiveAssistant(component: AssistantMessageComponent): boolean {
+		const lifetime = this.#assistantLifetimes.get(component);
+		return (
+			!this.#disposed &&
+			!this.ctx.isStopped?.() &&
+			lifetime !== undefined &&
+			lifetime.sessionIdentity === this.ctx.session &&
+			lifetime.sessionEpoch === this.#sessionPresentationEpoch &&
+			this.ctx.chatContainer.hasLiveChild(component)
+		);
+	}
+
+	#isValidAssistantText(record: AssistantTextPresentation): boolean {
+		return (
+			!this.#assistantTextSuspended &&
+			this.#isLiveAssistant(record.component) &&
+			record.sessionIdentity === this.ctx.session &&
+			record.sessionEpoch === this.#sessionPresentationEpoch &&
+			record.paintEpoch === this.#paintEpoch &&
+			record.component === this.ctx.streamingComponent
+		);
+	}
+
+	#queueAssistantText(component: AssistantMessageComponent, latestMessage: AssistantMessage): void {
+		if (this.#assistantTextSuspended || !this.#isLiveAssistant(component)) return;
+		const pending = this.#pendingAssistantText;
+		if (pending && this.#isValidAssistantText(pending)) {
+			pending.latestMessage = latestMessage;
+			return;
+		}
+		this.#cancelAssistantTextPresentation();
+		const record: AssistantTextPresentation = {
+			component,
+			latestMessage,
+			sessionIdentity: this.ctx.session,
+			sessionEpoch: this.#sessionPresentationEpoch,
+			paintEpoch: this.#paintEpoch,
+			cancel: () => {},
+		};
+		this.#pendingAssistantText = record;
+		record.cancel = this.ctx.ui.enqueueBeforeRender(() => this.#flushAssistantText(record));
+	}
+
+	#flushAssistantText(record = this.#pendingAssistantText): void {
+		if (!record || this.#pendingAssistantText !== record) return;
+		this.#cancelAssistantTextPresentation();
+		if (!this.#isValidAssistantText(record)) return;
+		const previousScope = this.#assistantTextMutationScope;
+		this.#assistantTextMutationScope = record;
+		try {
+			record.component.updateContent(record.latestMessage, { streaming: true });
+		} finally {
+			this.#assistantTextMutationScope = previousScope;
+		}
+	}
+
+	#observeAssistantMutation(component: AssistantMessageComponent): void {
+		if (!this.#isLiveAssistant(component)) return;
+		const scope = this.#assistantTextMutationScope;
+		if (scope?.component === component && this.#isValidAssistantText(scope)) {
+			// Only this synchronous projection publishes before frame source selection.
+			// An unrelated awaited event retains its own dirty flag and settlement semantics.
+			this.ctx.recordVisibleTranscriptMutation?.();
+			return;
+		}
+		this.#observeVisibleTranscriptMutation();
+	}
+
 	#recordVisibleTranscriptMutation(): void {
 		this.#visibleTranscriptChanged = true;
 	}
@@ -292,9 +411,10 @@ export class EventController {
 	}
 
 	async #dispatchEvent(event: AgentSessionEvent): Promise<void> {
+		if (this.#disposed) return;
 		if (this.ctx.isStopped?.()) return;
 		if (!this.ctx.isInitialized) await this.ctx.init();
-		if (this.ctx.isStopped?.()) return;
+		if (this.#disposed || this.ctx.isStopped?.()) return;
 		this.#visibleTranscriptChanged = false;
 		this.#handlingEvent = true;
 		try {
@@ -462,18 +582,26 @@ export class EventController {
 			this.ctx.ui.requestRender();
 			this.#recordVisibleTranscriptMutation();
 		} else if (event.message.role === "assistant") {
+			this.#cancelAssistantTextPresentation();
 			this.#lastThinkingCount = 0;
 			this.#resetReadGroup();
 			this.#toolIntentCache.clear();
 			this.#thinkingContentIndices.clear();
-			this.ctx.streamingComponent = new AssistantMessageComponent(
+			const component: AssistantMessageComponent = new AssistantMessageComponent(
 				undefined,
 				this.ctx.hideThinkingBlock,
-				() => this.ctx.ui.requestRender(),
+				() => {
+					if (this.#isLiveAssistant(component)) this.ctx.ui.requestRender();
+				},
 				this.ctx.getAssistantViewportAnchorId?.(event.message),
-				() => this.#observeVisibleTranscriptMutation(),
+				() => this.#observeAssistantMutation(component),
 				this.ctx.session,
 			);
+			this.#assistantLifetimes.set(component, {
+				sessionIdentity: this.ctx.session,
+				sessionEpoch: this.#sessionPresentationEpoch,
+			});
+			this.ctx.streamingComponent = component;
 			this.ctx.streamingMessage = event.message;
 			addChatChild(this.ctx, this.ctx.streamingComponent);
 			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: true });
@@ -605,8 +733,20 @@ export class EventController {
 				transferSessionMessageIdentity([this.ctx.streamingMessage], [event.message]);
 			}
 			this.ctx.streamingMessage = event.message;
-			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: true });
 			const contentIndex = event.assistantMessageEvent?.contentIndex;
+			if (
+				event.assistantMessageEvent?.type === "text_delta" &&
+				typeof contentIndex === "number" &&
+				Number.isInteger(contentIndex) &&
+				contentIndex >= 0 &&
+				contentIndex < event.message.content.length &&
+				event.message.content[contentIndex]?.type === "text"
+			) {
+				this.#queueAssistantText(this.ctx.streamingComponent, event.message);
+			} else {
+				this.#cancelAssistantTextPresentation();
+				this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: true });
+			}
 			const changedContent =
 				typeof contentIndex === "number" && contentIndex >= 0
 					? this.ctx.streamingMessage.content[contentIndex]
@@ -714,6 +854,7 @@ export class EventController {
 
 	async #handleMessageEnd(event: Extract<AgentSessionEvent, { type: "message_end" }>): Promise<void> {
 		if (event.message.role === "user") return;
+		if (event.message.role === "assistant") this.#cancelAssistantTextPresentation();
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			if (this.ctx.streamingMessage?.role === "assistant") {
 				transferSessionMessageIdentity([this.ctx.streamingMessage], [event.message]);
@@ -916,6 +1057,8 @@ export class EventController {
 	}
 
 	async #handleAgentEnd(event: Extract<AgentSessionEvent, { type: "agent_end" }>): Promise<void> {
+		this.#flushAssistantText();
+		this.#cancelAssistantTextPresentation();
 		this.ctx.setWorkingMessage(undefined);
 		stopInteractiveActivityIndicator(this.ctx, { foregroundSettled: true });
 		if (this.ctx.streamingComponent) {

package/src/modes/controllers/selector-controller.ts

@@ -1976,6 +1976,22 @@ export class SelectorController {
 								width ?? this.ctx.editor.getTopBorderAvailableWidth(this.ctx.ui.terminal.columns);
 							return this.ctx.statusLine.getPreviewContent(availableWidth);
 						},
+						getStatusLinePreviewForSettings: (previewSettings, width?: number) => {
+							const availableWidth =
+								width ?? this.ctx.editor.getTopBorderAvailableWidth(this.ctx.ui.terminal.columns);
+							return this.ctx.statusLine.getPreviewContentForSettings(availableWidth, {
+								...buildStatusLineSettings(settings),
+								...previewSettings,
+							});
+						},
+						getStatusLinePreviewPartsForSettings: (previewSettings, width?: number) => {
+							const availableWidth =
+								width ?? this.ctx.editor.getTopBorderAvailableWidth(this.ctx.ui.terminal.columns);
+							return this.ctx.statusLine.getPreviewPartsForSettings(availableWidth, {
+								...buildStatusLineSettings(settings),
+								...previewSettings,
+							});
+						},
 						onPluginsChanged: () => {
 							this.ctx.ui.requestRender();
 						},
@@ -2982,6 +2998,8 @@ export class SelectorController {
 						this.ctx.ui.requestRender();
 						try {
 							await mgr.uninstallPlugin(pluginId, scope);
+							await this.ctx.session.reloadSkills();
+							await this.ctx.refreshSlashCommandState();
 							this.ctx.showStatus(`Uninstalled ${pluginId}`);
 						} catch (err) {
 							this.ctx.showStatus(`Uninstall failed: ${err}`);
@@ -3019,6 +3037,8 @@ export class SelectorController {
 					try {
 						const force = installedIds.has(`${name}@${marketplace}`);
 						await mgr.installPlugin(name, marketplace, { force });
+						await this.ctx.session.reloadSkills();
+						await this.ctx.refreshSlashCommandState();
 						this.ctx.showStatus(`Installed ${name} from ${marketplace}`);
 					} catch (err) {
 						this.ctx.showStatus(`Install failed: ${err}`);
@@ -3245,6 +3265,7 @@ export class SelectorController {
 	}
 
 	#clearTransientSessionUi(options?: { restoreBackground?: boolean; clearSpecializedLoaders?: boolean }): void {
+		this.ctx.resetAssistantTextPresentation();
 		if (options?.clearSpecializedLoaders) clearInteractiveActivityLoaders(this.ctx);
 		stopInteractiveActivityIndicator(this.ctx, {
 			restoreBackground: options?.restoreBackground,

package/src/modes/interactive-mode.ts

@@ -13,7 +13,7 @@ import {
 	Text,
 	TUI,
 } from "@gajae-code/tui";
-import { APP_NAME, adjustHsv, getProjectDir, logger, postmortem, sanitizeText } from "@gajae-code/utils";
+import { APP_NAME, adjustHsv, getAgentDir, getProjectDir, logger, postmortem, sanitizeText } from "@gajae-code/utils";
 import chalk from "chalk";
 import { AsyncJobManager } from "../async";
 import {
@@ -49,6 +49,7 @@ import type { AgentSession, AgentSessionEvent, AsyncJobSnapshotItem } from "../s
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import { getRecentSessions, getSessionMessageEntryId } from "../session/session-manager";
+import { createDefaultPaseoAnnounceDependencies, startPaseoAnnouncement } from "../setup/paseo/announce";
 import type { LspStartupServerInfo } from "../tools";
 import { formatPhaseDisplayName } from "../tools/todo-write";
 import { copyToClipboard } from "../utils/clipboard";
@@ -745,6 +746,10 @@ export class InteractiveMode implements InteractiveModeContext {
 			version: this.#version,
 			focusDomain: "composer",
 			keyDisplayContext: this.#keyDisplayContext,
+			onUpdate: () => {
+				this.updateEditorChrome();
+				this.ui.requestRender();
+			},
 		});
 		this.statusLine.setAutoCompactEnabled(session.autoCompactionEnabled);
 
@@ -776,6 +781,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#btwController = new BtwController(this);
 		this.#extensionUiController = new ExtensionUiController(this);
 		this.#eventController = new EventController(this);
+		this.ui.setRenderPreparationLifecycleCallbacks({
+			invalidate: () => this.#eventController.suspendAssistantTextPresentation(),
+			beforeStart: () => this.#eventController.resumeAssistantTextPresentation(),
+		});
 		this.#commandController = new CommandController(this);
 		this.#todoCommandController = new TodoCommandController(this);
 		this.#selectorController = new SelectorController(this);
@@ -1065,6 +1074,37 @@ export class InteractiveMode implements InteractiveModeContext {
 			crashRelayTimer.unref?.();
 		}
 
+		// Make this session visible in Paseo. Interactive-only by construction: a
+		// `gjc acp` provider process never builds an InteractiveMode, so an imported
+		// session can never announce itself back into Paseo.
+		if (this.settings.getGlobal("paseo.autoImport") === true) {
+			const sessionId = this.sessionManager.getSessionId();
+			const announcement = startPaseoAnnouncement(
+				{
+					sessionId,
+					cwd: this.sessionManager.getCwd(),
+					isEnabled: () => this.settings.getGlobal("paseo.autoImport") === true,
+					onOutcome: outcome => {
+						if (this.#stopped || outcome.kind === "skipped") return;
+						this.showStatus(
+							outcome.kind === "failed"
+								? `Paseo import failed: ${outcome.detail}`
+								: `Controllable in Paseo as ${outcome.providerKey}`,
+							{ dim: true },
+						);
+					},
+				},
+				createDefaultPaseoAnnounceDependencies(getAgentDir()),
+			);
+			const stopWatchingSettings = this.settings.onChanged(path => {
+				if (path === "paseo.autoImport" && this.settings.getGlobal(path) !== true) announcement.cancel();
+			});
+			this.#stopListeners.add(() => {
+				stopWatchingSettings();
+				announcement.cancel();
+			});
+		}
+
 		if (starReminderGate.schedule) {
 			scheduleLaunchStarReminderAfterFirstRender({
 				confirm: (title, message) =>
@@ -1517,6 +1557,7 @@ export class InteractiveMode implements InteractiveModeContext {
 
 	rebuildChatFromMessages(policy: TranscriptRebuildPolicy): void {
 		prepareTranscriptRebuild(this.ui, policy);
+		this.resetAssistantTextPresentation();
 		this.chatContainer.clear();
 		const context = this.session.buildDisplaySessionContext();
 		this.renderSessionContext(context);
@@ -1649,6 +1690,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	stop(): void {
 		const wasInitialized = this.isInitialized;
 		this.#stopped = true;
+		this.ui.setRenderPreparationLifecycleCallbacks(undefined);
 		this.#inputController.discardDeferredSubmission();
 		for (const listener of this.#stopListeners) {
 			try {
@@ -2077,6 +2119,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#uiHelpers.isKnownSlashCommand(text);
 	}
 
+	resetAssistantTextPresentation(): void {
+		this.#eventController.resetAssistantTextPresentation();
+	}
+
 	/** Advances the sticky-viewport source only for semantic transcript output. */
 	recordVisibleTranscriptMutation(): void {
 		const identity = `session:${this.sessionManager.getSessionId()}`;

package/src/modes/types.ts

@@ -355,6 +355,7 @@ export interface InteractiveModeContext {
 	extractAssistantText(message: AssistantMessage): string;
 	/** Records one semantic visible-transcript mutation for the sticky viewport. */
 	recordVisibleTranscriptMutation?(): void;
+	resetAssistantTextPresentation(): void;
 	updateEditorTopBorder(): void;
 	updateEditorBorderColor(): void;
 	rebuildChatFromMessages(policy: TranscriptRebuildPolicy): void;

package/src/modes/utils/ui-helpers.ts

@@ -944,6 +944,7 @@ export class UiHelpers {
 		this.ctx.pendingPythonComponents = this.ctx.pendingPythonComponents.filter(component =>
 			runningExecutionComponents.includes(component),
 		);
+		this.ctx.resetAssistantTextPresentation();
 		this.ctx.chatContainer.clear();
 
 		// Reuse a pre-built context when available (e.g. from navigateTree) to avoid a second O(N) walk.

package/src/prompts/system/system-prompt.md

@@ -47,6 +47,14 @@ Optimize for correctness first, maintainability second, and brevity third. Prefe
 - Do not defer actionable work. Underpromise and overdeliver: report only what is done or in progress, never announce remaining work instead of doing it.
 </communication>
 
+{{#if reasoningLanguageEnglish}}
+<reasoning-language>
+- Reason through development and technical problem-solving in English.
+- Keep user-facing answers in the language the user requested or used.
+- This changes reasoning language only; it does not relax correctness, safety, or communication requirements.
+</reasoning-language>
+{{/if}}
+
 <completion-contract>
 - Never present partial work as complete.
 - Never suppress tests or warnings to make code pass.

package/src/prompts/tools/bash.md

@@ -18,7 +18,7 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 {{/if}}
 {{#if foregroundFoldEnabled}}
 - In the interactive TUI, the user can press the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via the `app.tool.backgroundFold` keybinding) while a foreground command is still running to fold it into a background job. All three command surfaces fold: managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded command keeps its original timeout and is never killed or restarted by folding; a folded PTY continues output-only, so it stops accepting input. The turn then ends cleanly and a later turn resumes automatically with the command's result, so the interrupted task is finished rather than abandoned. `task`/`subagent` waits are deliberately NOT foldable. Do not instruct users to use raw shell `Ctrl+Z`/`bg` inside the GJC TUI; ownership and output routing are not safe there.
-- A user steer folds the same way: when the user sends a message while a foreground command has already run for at least 2 seconds, the command is folded into a background job and this call returns the background-start result plus the line `Folded into background job <id> because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.` The steer is then delivered at this tool boundary, so handle it next; do not re-run the folded command. Steers that arrive within the first 2 seconds let the command finish normally. This applies only while `busyPromptMode` is `steer` and `toolInterruptPolicy` is `abort_tools`.
+- A user steer folds the same way: when the user sends a message while a foreground command has already run for at least 2 seconds, the command is folded into a background job and this call returns the background-start result plus the line `Folded into background job <id> because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.` The steer is then delivered at this tool boundary, so handle it next; do not re-run the folded command. Steers that arrive within the first 2 seconds let the command finish normally. This applies only while `busyPromptMode` is `steer`; `toolInterruptPolicy` is not a gate, since a fold never kills the command.
 {{/if}}
 </instruction>
 {{#if restrictedAllowedPrefixes}}

package/src/prompts/tools/job.md

@@ -2,7 +2,7 @@ Inspects, waits, or cancels async jobs.
 
 Background job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.
 
-In the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` and `toolInterruptPolicy=abort_tools`). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.
+In the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` (`toolInterruptPolicy` is not a gate)). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.
 
 # Operations
 

package/src/prompts/tools/search.md

@@ -5,6 +5,7 @@ Searches files using powerful regex matching.
 - `paths` accepts an array of files, directories, globs, or internal URLs; when omitted, the whole working directory is searched
 - `paths` is an array; do not embed commas or spaces inside a single entry. Pass `["src", "tests"]` not `["src,tests"]`.
 - Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
+- `timeout` is in seconds (default 5, range 0.5–60). Increase it only for intentionally broad searches; narrow `paths` first
 </instruction>
 
 <output>
@@ -20,4 +21,5 @@ Searches files using powerful regex matching.
 <critical>
 - Search paths are an array; pass separate entries rather than comma-joined paths.
 - Use a cross-line pattern only when the match actually spans lines.
+- Do not retry a timed-out search unchanged; narrow `paths`/`pattern` or explicitly increase `timeout`.
 </critical>

package/src/runtime-mcp/client.ts

@@ -24,8 +24,8 @@ import {
 	normalizeMcpCacheHints,
 	resolveMCPProtocolPreference,
 } from "./protocol";
-import { createHttpTransport, HttpTransport } from "./transports/http";
-import { createStdioTransport } from "./transports/stdio";
+import { HttpTransport } from "./transports/http";
+import { StdioTransport } from "./transports/stdio";
 import type {
 	MCPDiscoverResultLite,
 	MCPGetPromptParams,
@@ -188,18 +188,18 @@ async function defaultRequestHandler(method: string, _params: unknown): Promise<
 /**
  * Create a transport for the given server config.
  */
-async function createTransport(config: MCPServerConfig): Promise<MCPTransport> {
+function createTransport(config: MCPServerConfig): StdioTransport | HttpTransport {
 	const serverType = config.type ?? "stdio";
 
 	switch (serverType) {
 		case "stdio":
-			return createStdioTransport(config as MCPStdioServerConfig);
+			return new StdioTransport(config as MCPStdioServerConfig);
 		case "http":
-			return createHttpTransport(config as MCPHttpServerConfig);
+			return new HttpTransport(config as MCPHttpServerConfig);
 		case "sse":
 			// Compatibility: `sse` configs use Streamable HTTP, not the legacy MCP SSE
 			// protocol. The configured URL receives JSON-RPC POST requests directly.
-			return createHttpTransport(config as MCPSseServerConfig);
+			return new HttpTransport(config as MCPSseServerConfig);
 		default:
 			throw new Error(`Unknown server type: ${serverType}`);
 	}
@@ -295,6 +295,42 @@ function unwrapTransportFailure(error: unknown): unknown {
 	return error instanceof MCPExpectedFailure && error.cause !== undefined ? error.cause : error;
 }
 
+function transportFailureCauses(error: unknown): unknown[] {
+	const failure = unwrapTransportFailure(error);
+	return failure instanceof AggregateError ? failure.errors : [failure];
+}
+
+function connectionAndCleanupCause(connectionError: unknown, cleanupError: unknown): AggregateError {
+	return new AggregateError(
+		[...transportFailureCauses(connectionError), ...transportFailureCauses(cleanupError)],
+		"MCP connection failed and transport cleanup also failed",
+	);
+}
+
+function combinedConnectionAndCleanupFailure(connectionError: unknown, cleanupError: unknown): MCPExpectedFailure {
+	return new MCPExpectedFailure(connectionAndCleanupCause(connectionError, cleanupError));
+}
+
+/** Failed connection whose still-owned transport cleanup can be retried explicitly. */
+export class MCPConnectionCleanupFailure extends MCPExpectedFailure {
+	#transport: MCPTransport;
+
+	constructor(cause: unknown, transport: MCPTransport) {
+		super(cause);
+		this.name = "MCPConnectionCleanupFailure";
+		this.#transport = transport;
+	}
+
+	/** Retry the same retained transport cleanup; failures preserve all prior causes. */
+	async close(): Promise<void> {
+		try {
+			await this.#transport.close();
+		} catch (cleanupError) {
+			throw new MCPConnectionCleanupFailure(connectionAndCleanupCause(this, cleanupError), this.#transport);
+		}
+	}
+}
+
 type ModernNegotiation =
 	| { outcome: "modern"; discovery: MCPDiscoverResultLite | null; discoverState: "yes" | "no"; versionRetry: boolean }
 	| { outcome: "legacy-fallback"; reason: MCPDowngradeReason };
@@ -505,14 +541,14 @@ export async function connectToServer(
 	},
 ): Promise<MCPServerConnection> {
 	const timeoutMs = config.timeout ?? CONNECTION_TIMEOUT_MS;
-	let transport: MCPTransport | undefined;
+	let transport: StdioTransport | HttpTransport | undefined;
 	const connectAbort = new AbortController();
 	const connectSignal = options?.signal ? AbortSignal.any([options.signal, connectAbort.signal]) : connectAbort.signal;
 
 	const preference = resolveMCPProtocolPreference(config.protocol);
 
 	const connect = async (): Promise<MCPServerConnection> => {
-		transport = await createTransport(config);
+		transport = createTransport(config);
 		if (options?.onNotification) {
 			transport.onNotification = options.onNotification;
 		}
@@ -561,6 +597,7 @@ export async function connectToServer(
 		};
 
 		try {
+			await transport.connect();
 			// stdio has no per-request HTTP era signals; it stays on the legacy handshake.
 			if ((config.type ?? "stdio") === "stdio") {
 				return await connectLegacy("legacy-forced", "stdio-transport");
@@ -609,8 +646,8 @@ export async function connectToServer(
 		} catch (error) {
 			try {
 				await transport.close();
-			} catch {
-				// Preserve the initialization failure when cleanup also fails.
+			} catch (cleanupError) {
+				throw combinedConnectionAndCleanupFailure(error, cleanupError);
 			}
 			throw error;
 		}
@@ -625,20 +662,26 @@ export async function connectToServer(
 		// abort initialization and wait for transport cleanup before returning.
 		const aborted = options?.signal?.aborted === true;
 		connectAbort.abort(error);
+		let failure = error;
+		let cleanupIncomplete = false;
 		if (transport) {
 			try {
 				await transport.close();
-			} catch {
-				// Preserve the primary connection failure when cleanup also fails.
+			} catch (cleanupError) {
+				failure = combinedConnectionAndCleanupFailure(failure, cleanupError);
+				cleanupIncomplete = true;
 			}
 		}
-		if (error instanceof MCPExpectedFailure) {
-			throw error;
+		if (cleanupIncomplete && transport) {
+			throw new MCPConnectionCleanupFailure(unwrapTransportFailure(failure), transport);
 		}
-		if (aborted || (error instanceof Error && error.message === connectionTimeoutMessage)) {
-			throw new MCPExpectedFailure(error);
+		if (failure instanceof MCPExpectedFailure) {
+			throw failure;
 		}
-		throw error;
+		if (aborted || (failure instanceof Error && failure.message === connectionTimeoutMessage)) {
+			throw new MCPExpectedFailure(failure);
+		}
+		throw failure;
 	}
 }