@gajae-code/coding-agent 0.18.0 → 0.18.5

package/src/modes/acp/acp-agent.ts

@@ -214,6 +214,12 @@ interface PromptWaiter {
 	/** Whether ANY overlapping cancel attempt for this prompt was acknowledged:
 	 *  a later failed attempt must not erase an earlier success (review thread P2). */
 	cancelAcknowledged?: boolean;
+	/** Durable cancel intent after a no-effect abort before this waiter starts work; retained until settlement. */
+	cancelBeforeAdmission?: boolean;
+	/** Abort scope replayed after admission and again at correlated start if no turn was active yet. */
+	cancelBeforeAdmissionScope?: AbortScope;
+	/** A correlated start may need one final abort after an admitted-but-not-running no-effect response. */
+	cancelAfterStartAbortIssued?: boolean;
 	/** In-flight cancel attempts for this prompt: cancellation intent must stay
 	 *  set while any attempt can still acknowledge, so a failure only clears
 	 *  the shared flag when no attempt remains pending (review thread P2). */
@@ -591,6 +597,12 @@ function isAbortAcknowledged(value: unknown, scope: AbortScope): boolean {
 	if (result.aborted === true) return true;
 	return result.ok === true && result.turn === "stopped" && result.selection === scope;
 }
+function isAbortNoEffect(value: unknown): boolean {
+	const candidate = object(value);
+	const result = object(candidate?.result) ?? candidate;
+	return result?.turn === "no_active_turn" || result?.turn === "no_effect" || result?.turn === "no_store";
+}
+
 function strictCorrelationFrom(...values: unknown[]): PromptCorrelation | undefined {
 	const correlation: PromptCorrelation = {};
 	let malformed = false;
@@ -655,7 +667,9 @@ function logDroppedPromptTerminal(
 	});
 }
 
-type SdkPromptFailedOutcome = Extract<SdkPromptTerminalOutcome, { kind: "failed" }>;
+type SdkPromptFailedOutcome = Extract<SdkPromptTerminalOutcome, { kind: "failed" }> & {
+	deliveryFailure?: { cause: string; frameBytes: number };
+};
 
 /**
  * A prompt rejection that still carries the terminal's structured failure classification.
@@ -791,6 +805,13 @@ function promptFailureWireData(failure: SdkPromptFailedOutcome): Record<string,
 		category: failure.category,
 		retryability: promptFailureRetryability(failure.category),
 		...(isSafePromptFailureCode(failure.providerCode) ? { providerCode: failure.providerCode } : {}),
+		...(failure.deliveryFailure
+			? {
+					reason: "delivery_failed",
+					cause: failure.deliveryFailure.cause,
+					frameBytes: String(failure.deliveryFailure.frameBytes),
+				}
+			: {}),
 		...(operatorMessage === undefined ? {} : { operatorMessage }),
 	};
 }
@@ -909,13 +930,28 @@ function terminalOutcome(event: JsonObject): SdkPromptTerminalOutcome | undefine
 		typeof outcome.message === "string" &&
 		(outcome.provenance === "agent_failed" || outcome.provenance === "deadline")
 	) {
-		return failedPromptOutcome({
+		const failure = failedPromptOutcome({
 			code: outcome.code,
 			provenance: outcome.provenance,
 			...(typeof outcome.providerCode === "string" ? { providerCode: outcome.providerCode } : {}),
 			...(isSdkPromptFailurePhase(outcome.phase) ? { phase: outcome.phase } : {}),
 			evidence: {},
 		});
+		const delivery = object(event.error);
+		if (
+			delivery?.code === "delivery_failed" &&
+			isSafePromptFailureCode(delivery.cause) &&
+			typeof delivery.frameBytes === "number" &&
+			Number.isSafeInteger(delivery.frameBytes) &&
+			delivery.frameBytes >= 0
+		) {
+			const classified: SdkPromptFailedOutcome = {
+				...failure,
+				deliveryFailure: { cause: delivery.cause, frameBytes: delivery.frameBytes },
+			};
+			return classified;
+		}
+		return failure;
 	}
 	return undefined;
 }
@@ -1103,6 +1139,15 @@ function frameMessageRole(event: JsonObject | undefined): string | undefined {
 	return typeof role === "string" ? role : undefined;
 }
 
+function frameMessageHasToolCall(event: JsonObject | undefined): boolean {
+	const content = object(event?.message)?.content;
+	if (!Array.isArray(content)) return false;
+	return content.some(block => {
+		const value = object(block);
+		return value?.type === "toolCall" || value?.type === "tool_use";
+	});
+}
+
 const ACP_CONFIG_OPTIONS = [
 	{ id: MODEL_CONFIG_ID, name: "Model", category: "model", options: [] },
 	{ id: THINKING_CONFIG_ID, name: "Thinking", category: "thought_level", options: [] },
@@ -1495,6 +1540,11 @@ export function acpRequestFailure(error: unknown): unknown {
 	const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
 	if (typeof code !== "string") return error;
 	const message = error instanceof Error ? error.message : code;
+	// ACP clients render `data.details` after the JSON-RPC message. The MCP launch
+	// diagnostic is already the complete additional message, so repeating it in
+	// `details` produces `Internal error: X.: X.` on the wire.
+	const duplicateMcpLaunchDetails =
+		code === "unavailable" && message.startsWith("MCP server request failed to start (");
 	// A prompt terminal additionally publishes its classification (issue #5615). The
 	// spread is empty for every other error, so their payloads are byte-identical to
 	// before. `code`/`details` and the JSON-RPC code itself are untouched either way:
@@ -1502,8 +1552,8 @@ export function acpRequestFailure(error: unknown): unknown {
 	const promptFailure = promptFailureFromDirectError(error);
 	const data =
 		promptFailure !== undefined
-			? { code, details: message, ...promptFailureWireData(promptFailure) }
-			: { code, details: message };
+			? { code, ...(duplicateMcpLaunchDetails ? {} : { details: message }), ...promptFailureWireData(promptFailure) }
+			: { code, ...(duplicateMcpLaunchDetails ? {} : { details: message }) };
 	// An abandoned prompt additionally publishes the plan it never finished (issue #5669).
 	// Same rule as above: `code`/`details` and the JSON-RPC code are untouched, and an abandon
 	// that observed no plan adds no keys, so its payload stays byte-identical to before.
@@ -2362,7 +2412,7 @@ export class AcpAgent implements Agent {
 				this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 				return await response;
 			}
-			if (record.cancelRequested && waiter.cancelAcknowledged) {
+			if (record.cancelRequested && (waiter.cancelAcknowledged || waiter.cancelBeforeAdmission)) {
 				this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 				await this.#settleCancelledPrompt(params.sessionId, record, waiter);
 				return await response;
@@ -2385,7 +2435,7 @@ export class AcpAgent implements Agent {
 			this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 			return await response;
 		}
-		if (record.cancelRequested && waiter.cancelAcknowledged) {
+		if (record.cancelRequested && (waiter.cancelAcknowledged || waiter.cancelBeforeAdmission)) {
 			this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 			await this.#settleCancelledPrompt(params.sessionId, record, waiter);
 			return await response;
@@ -2415,18 +2465,18 @@ export class AcpAgent implements Agent {
 					record.adapter,
 				);
 			}
-		waiter.dispatched = true;
-		// The turn is now dispatched to the host: this prompt owned the session's first turn,
-		// so it — not a preflight rejection that threw before this point — is what settles
-		// `firstPromptDone` in `prompt()` (review P2).
-		if (retryReservation) retryReservation.admitted = true;
 		if (waiter.settled || record.activePrompt !== waiter) {
 			return await response;
 		}
-		if (record.cancelRequested && waiter.cancelAcknowledged) {
+		if (record.cancelRequested && (waiter.cancelAcknowledged || waiter.cancelBeforeAdmission)) {
 			await this.#settleCancelledPrompt(params.sessionId, record, waiter);
 			return await response;
 		}
+		waiter.dispatched = true;
+		// The turn is now dispatched to the host: this prompt owned the session's first turn,
+		// so it — not a preflight rejection that threw before this point — is what settles
+		// `firstPromptDone` in `prompt()` (review P2).
+		if (retryReservation) retryReservation.admitted = true;
 
 		waiter.acknowledgementPending = true;
 		const promptAdapter = record.adapter;
@@ -2546,6 +2596,19 @@ export class AcpAgent implements Agent {
 				this.#rememberSettledPromptCorrelation(params.sessionId, record, acknowledgementCorrelation);
 				return await response;
 			}
+			if (waiter.cancelBeforeAdmission && record.cancelRequested) {
+				const scope = waiter.cancelBeforeAdmissionScope ?? "turn";
+				// Keep the intent until an acknowledged abort or the prompt terminal settles it.
+				void this.cancel({
+					sessionId: params.sessionId,
+					_meta: { gjc: { abortScope: scope } },
+				} as CancelNotification).catch(error =>
+					logger.warn("ACP could not retry a cancel after prompt admission", {
+						sessionId: params.sessionId,
+						error: error instanceof Error ? error.message : String(error),
+					}),
+				);
+			}
 			// Frames held while ownership was unknown belong to this prompt only when the
 			// acknowledgement proves their complete correlation matches exactly.
 			const deferredActivityFrames = waiter.deferredActivityFrames.splice(0);
@@ -2691,7 +2754,10 @@ export class AcpAgent implements Agent {
 			// return the semantically meaningful `cancelled` stop reason, so that Clients
 			// can reliably confirm the cancellation." Surfacing the transport's `busy`
 			// rejection instead would show the user a spurious error for their own cancel.
-			if (record.cancelRequested && waiter.cancelAcknowledged) {
+			if (
+				record.cancelRequested &&
+				(waiter.cancelAcknowledged || (waiter.cancelBeforeAdmission && !waiter.acknowledged && !waiter.dispatched))
+			) {
 				record.cancelRequested = false;
 				// The client's turn is settled by the return; the advisory idle publication
 				// must not gate it and must still be attempted so the running phase is
@@ -2715,6 +2781,8 @@ export class AcpAgent implements Agent {
 		// `_meta.gjc.abortScope: "owned"` (or `GJC_ACP_ABORT_SCOPE=owned`).
 		const scope = resolveAcpAbortScope(params._meta, process.env);
 		const waiter = record.activePrompt;
+		const waiterWasUnacknowledged = waiter !== undefined && !waiter.acknowledged;
+		const waiterWasBeforeActivity = waiter !== undefined && !waiter.observedTurnActivity;
 		if (waiter) {
 			// Overlapping cancels must not lose an earlier successful
 			// acknowledgement: ANY successful attempt resolves the shared
@@ -2733,9 +2801,27 @@ export class AcpAgent implements Agent {
 			}
 		}
 		try {
-			const acknowledgement = await record.adapter.cancel(scope);
+			let acknowledgement = await record.adapter.cancel(scope);
+			let acknowledgementScope = scope;
+			if (
+				!isAbortAcknowledged(acknowledgement, scope) &&
+				isAbortNoEffect(acknowledgement) &&
+				(waiterWasUnacknowledged || waiterWasBeforeActivity) &&
+				waiter &&
+				record.activePrompt === waiter &&
+				!waiter.settled
+			) {
+				waiter.cancelBeforeAdmission = true;
+				waiter.cancelBeforeAdmissionScope =
+					waiter.cancelBeforeAdmissionScope === "owned" || scope === "owned" ? "owned" : "turn";
+				if (waiter.acknowledged) {
+					// The first abort raced prompt admission. Retry now that the turn is admitted.
+					acknowledgementScope = waiter.cancelBeforeAdmissionScope;
+					acknowledgement = await record.adapter.cancel(acknowledgementScope);
+				}
+			}
 			const result = object(object(acknowledgement)?.result) ?? object(acknowledgement);
-			if (!isAbortAcknowledged(acknowledgement, scope))
+			if (!isAbortAcknowledged(acknowledgement, acknowledgementScope))
 				throw new AcpSdkAdapterError(
 					"abort_unacknowledged",
 					"SDK did not acknowledge cancellation of the active prompt.",
@@ -2846,7 +2932,12 @@ export class AcpAgent implements Agent {
 		} finally {
 			if (waiter) {
 				waiter.pendingCancelAttempts = Math.max(0, (waiter.pendingCancelAttempts ?? 1) - 1);
-				if (waiter.pendingCancelAttempts === 0 && !waiter.cancelAcknowledged && record.activePrompt === waiter) {
+				if (
+					waiter.pendingCancelAttempts === 0 &&
+					!waiter.cancelAcknowledged &&
+					!waiter.cancelBeforeAdmission &&
+					record.activePrompt === waiter
+				) {
 					record.cancelRequested = false;
 				}
 			}
@@ -2869,8 +2960,9 @@ export class AcpAgent implements Agent {
 
 	async #settleCancelledPrompt(id: string, record: SessionRecord, waiter: PromptWaiter): Promise<void> {
 		// The authoritative terminal wins whenever it arrives in time; this only runs
-		// when nothing settled the prompt after the SDK acknowledged the cancellation.
-		if (!waiter.cancelAcknowledged) return;
+		// after an acknowledged abort or before turn dispatch for this waiter.
+		const preAdmissionCancellation = waiter.cancelBeforeAdmission && !waiter.acknowledged && !waiter.dispatched;
+		if (!waiter.cancelAcknowledged && !preAdmissionCancellation) return;
 		if (this.#sessions.get(id) !== record || record.activePrompt !== waiter || waiter.settled) return;
 		if (waiter.terminalReserved) return;
 		// An overlapping acknowledged cancel does not supersede the earlier
@@ -2893,6 +2985,8 @@ export class AcpAgent implements Agent {
 		if (!record.backgroundBusy) record.busy = false;
 		clearPromptWatchdog(waiter);
 		record.cancelRequested = false;
+		waiter.cancelBeforeAdmission = false;
+		waiter.cancelBeforeAdmissionScope = undefined;
 		waiter.settled = true;
 		this.#fenceRetiredPromptAcknowledgement(id, waiter);
 		waiter.deferredFrames.length = 0;
@@ -4144,6 +4238,7 @@ export class AcpAgent implements Agent {
 			typeof event?.type === "string" ? event.type : undefined,
 			typeof event?.toolCallId === "string" ? event.toolCallId : undefined,
 			frameMessageRole(event),
+			frameMessageHasToolCall(event),
 		);
 	}
 
@@ -4605,6 +4700,24 @@ export class AcpAgent implements Agent {
 		}
 		if (toolCallId && event.type === "tool_execution_end") record.toolArgs.delete(toolCallId);
 		if (event.type === "agent_start") {
+			if (
+				promptOwner?.cancelBeforeAdmission &&
+				record.cancelRequested &&
+				!promptOwner.cancelAcknowledged &&
+				!promptOwner.cancelAfterStartAbortIssued
+			) {
+				promptOwner.cancelAfterStartAbortIssued = true;
+				const scope = promptOwner.cancelBeforeAdmissionScope ?? "turn";
+				void this.cancel({
+					sessionId: id,
+					_meta: { gjc: { abortScope: scope } },
+				} as CancelNotification).catch(error =>
+					logger.warn("ACP could not retry a cancel after prompt start", {
+						sessionId: id,
+						error: error instanceof Error ? error.message : String(error),
+					}),
+				);
+			}
 			await this.#publishSessionUpdate(
 				id,
 				{
@@ -4874,6 +4987,8 @@ export class AcpAgent implements Agent {
 		record.activePrompt = undefined;
 		clearPromptWatchdog(waiter);
 		waiter.settled = true;
+		waiter.cancelBeforeAdmission = false;
+		waiter.cancelBeforeAdmissionScope = undefined;
 		const { outcome } = waiter.terminal;
 		this.#rememberSettledPromptCorrelation(id, record, waiter.correlation);
 		if (outcome.kind === "stopped") {
@@ -4885,10 +5000,11 @@ export class AcpAgent implements Agent {
 		// connection watched start. Upgrade it from the frames this prompt actually owned, never
 		// downgrade a terminal that already reported `post_start`, and carry the whole
 		// classification on the rejection so the first-turn retry gate can read it (review P1).
-		const failure =
+		const failure = (
 			outcome.phase === "post_start"
 				? outcome
-				: (rephaseFailedOutcome(outcome, { hasActivity: waiter.observedTurnActivity }) as SdkPromptFailedOutcome);
+				: rephaseFailedOutcome(outcome, { hasActivity: waiter.observedTurnActivity })
+		) as SdkPromptFailedOutcome;
 		waiter.reject(new AcpPromptFailureError(failure));
 	}
 

package/src/modes/controllers/ssh-command-controller.ts

@@ -134,7 +134,9 @@ export class SSHCommandController {
 					this.ctx.showError("Missing value for --port.");
 					return;
 				}
-				const parsed = Number.parseInt(value, 10);
+				// Same rule as the ACP `/ssh add` parser: `Number.parseInt` accepts
+				// trailing garbage ("22oops" -> 22), which would save a typo as a port.
+				const parsed = /^\d+$/.test(value) ? Number.parseInt(value, 10) : Number.NaN;
 				if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
 					this.ctx.showError("Invalid --port value. Must be an integer between 1 and 65535.");
 					return;

package/src/modes/interactive-mode.ts

@@ -565,6 +565,13 @@ export class InteractiveMode implements InteractiveModeContext {
 	#suspendedActivityIndicator?: Loader;
 	#stopped = false;
 	#initPromise?: Promise<void>;
+	// Until startup's first paint renders the session transcript, chatContainer holds
+	// only pre-paint notices. A transcript rebuild before then (e.g. an extension
+	// session_start message with display:true) would wipe those notices and leave
+	// session components that the first paint preserves and renders again, so every
+	// session-derived block would show twice. Rebuilds are no-ops until the first
+	// paint, which renders the full session anyway.
+	#initialTranscriptPainted = false;
 	#stopListeners = new Set<() => void>();
 	#eventBus?: EventBus;
 	#eventBusUnsubscribers: Array<() => void> = [];
@@ -1561,6 +1568,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	rebuildChatFromMessages(policy: TranscriptRebuildPolicy): void {
+		if (!this.#initialTranscriptPainted) return;
 		prepareTranscriptRebuild(this.ui, policy);
 		this.resetAssistantTextPresentation();
 		this.chatContainer.clear();
@@ -2184,11 +2192,13 @@ export class InteractiveMode implements InteractiveModeContext {
 		prebuiltContext?: SessionContext,
 		options?: { preserveExistingChat?: boolean },
 	): void {
+		if (!this.#initialTranscriptPainted) return;
 		prepareTranscriptRebuild(this.ui, policy);
 		this.#uiHelpers.renderInitialMessages(prebuiltContext, options);
 	}
 	renderInitialMessages(prebuiltContext?: SessionContext, options?: { preserveExistingChat?: boolean }): void {
 		this.#uiHelpers.renderInitialMessages(prebuiltContext, options);
+		this.#initialTranscriptPainted = true;
 	}
 
 	getUserMessageText(message: Message): string {

package/src/modes/utils/context-usage.ts

@@ -1,10 +1,6 @@
 import type { AgentMessage } from "@gajae-code/agent-core";
 import type { CompactionSettings } from "@gajae-code/agent-core/compaction";
-import {
-	effectiveReserveTokens,
-	estimateMessageTokensHeuristic,
-	resolveThresholdTokens,
-} from "@gajae-code/agent-core/compaction";
+import { effectiveReserveTokens, estimateMessageTokensHeuristic } from "@gajae-code/agent-core/compaction";
 import type { Model } from "@gajae-code/ai/core";
 import { formatNumber } from "@gajae-code/utils";
 import type { AgentSession } from "../../session/agent-session";
@@ -135,7 +131,7 @@ export function computeContextBreakdown(
 	if (contextWindow > 0) {
 		const compactionSettings = session.settings.getGroup("compaction") as CompactionSettings;
 		if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
-			const threshold = resolveThresholdTokens(contextWindow, compactionSettings);
+			const threshold = session.getAutoCompactionThresholdTokens(tokensForFreeSpace);
 			autoCompactBufferTokens = Math.max(0, contextWindow - threshold);
 		} else {
 			autoCompactBufferTokens = 0;

package/src/prompts/tools/task.md

@@ -2,18 +2,12 @@ Launches subagents to parallelize workflows.
 
 - Results are delivered automatically when complete.
 - The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.
-{{#if ircEnabled}}
-- Coordinate with running tasks via `irc` using those ids. `subagent` cancel terminates a task and **cannot carry a message**.
-{{else}}
+- Coordinate with running tasks via `irc` when available, using those ids. `subagent` cancel terminates a task and **cannot carry a message**.
 - Use `subagent` action `inspect` or `list` to snapshot manager state.
-{{/if}}
 - To wait or cancel, use the `subagent` tool; its await/cancel doctrine is authoritative.
 
-{{#if ircEnabled}}
-Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
-{{else}}
 Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
-{{/if}}
+Use `irc` for live coordination when it is available.
 
 <parameters>
 - `agent`: agent type for all tasks
@@ -36,27 +30,16 @@ Subagents have no conversation history. Every fact, file path, and direction the
 - HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.
 - NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
 - **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
-{{#if ircEnabled}}
-- Each task: ≤3–5 explicit files. Overlapping file sets are tolerable when peers can coordinate via `irc`, but still fan out to a cluster when the scopes are cleanly separable.
-- No globs, no "update all", no package-wide scope.
-{{else}}
-- Each task: ≤3–5 explicit files. No globs, no "update all", no package-wide scope. Fan out to a cluster instead.
-{{/if}}
+- Each task: ≤3–5 explicit files. No globs, no "update all", no package-wide scope. Use `irc` to coordinate overlapping work when it is available; otherwise keep file sets independent.
 - Pass large payloads via `local://<path>` URIs, not inline.
 {{#if contextEnabled}}- Put shared constraints in `context` once; do not duplicate across assignments.{{/if}}
 - Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.
 </rules>
 
 <parallelization>
-{{#if ircEnabled}}
-Test: can task B run correctly without seeing A's output? If no, sequence A → B — **unless** B can reasonably ask A for the missing piece over `irc`. Live coordination beats a serial waterfall when the contract is small and easy to describe in a DM.
-Still sequence when one task produces a large, evolving contract (generated types, schema migration, core module API) the other consumes wholesale — IRC round-trips do not replace a finished artifact.
-Parallel when tasks touch disjoint files, are independent refactors/tests, or only need occasional clarification that can be resolved peer-to-peer.
-{{else}}
-Test: can task B run correctly without seeing A's output? If no, sequence A → B.
-Sequential when one task produces a contract (types, API, schema, core module) the other consumes.
-Parallel when tasks touch disjoint files or are independent refactors/tests.
-{{/if}}
+Test: can task B run correctly without seeing A's output? If no, sequence A → B, unless `irc` is available and A can answer a small clarification.
+Still sequence when one task produces a large, evolving contract (generated types, schema migration, core module API); live coordination is not a substitute for a finished contract.
+Parallel when tasks touch disjoint files, are independent refactors/tests, or need only occasional peer clarification.
 </parallelization>
 
 {{#if contextEnabled}}
@@ -77,10 +60,8 @@ Parallel when tasks touch disjoint files or are independent refactors/tests.
 {{#if spawningDisabled}}
 Agent spawning is disabled for this context.
 {{else}}
-{{#list agents join="\n"}}
-# {{name}}
-{{description}}
-{{/list}}
+Bundled role names: {{#list agents join=", "}}{{name}}{{/list}}. A configured agent may override a bundled role name and takes precedence.
+Other configured agents (project, user, plugin) may also be available; calling with an unknown `agent` lists the agents callable in this session.
 {{/if}}
 </agents>
 

package/src/sdk/acp/adapter.ts

@@ -112,6 +112,16 @@ function credentialFreeLifecycleResult(value: unknown): unknown {
 	return output;
 }
 
+const ACP_MCP_FAILURE_MESSAGE_MAX_LENGTH = 240;
+
+function credentialFreeLifecycleMessage(error: unknown): string {
+	const message = error instanceof Error ? error.message : String(error);
+	return message
+		.replace(/\b(?:endpoint|token|url)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi, "[redacted]")
+		.replace(/https?:\/\/[^\s)]+/gi, "[redacted-url]")
+		.slice(0, ACP_MCP_FAILURE_MESSAGE_MAX_LENGTH);
+}
+
 /**
  * Lifecycle failures the ACP MCP launch wrapper must report verbatim. Everything else
  * is re-attributed to the configured MCP servers, which is the useful answer for a
@@ -135,22 +145,47 @@ const ACP_MCP_PRESERVED_LAUNCH_CODES = new Set([
 	"worktree_in_use",
 ]);
 
+/**
+ * SDK client transport failures happen before the lifecycle request reaches any MCP server and
+ * must retain their original retry semantics. The `transport` origin marker is required because
+ * broker ERROR frames are also represented as SdkClientError instances with these same codes.
+ */
+const ACP_MCP_PRESERVED_TRANSPORT_CODES = new Set(["connection_closed", "unavailable", "timeout"]);
+
 /**
  * The error an ACP session launch must throw once a lifecycle request that carried MCP
- * servers has failed.
+ * servers has failed. Broker transport failures from the SDK client are preserved verbatim;
+ * other failures keep the adapter's `unavailable` code while carrying a bounded, credential-free
+ * copy of the original code and message as their cause diagnostic.
  */
 export function acpMcpLaunchFailure(error: unknown, mcpServers: SessionLifecycleMcpServer[]): unknown {
 	const code =
 		typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
 			? error.code
 			: undefined;
-	if (mcpServers.length === 0 || (code !== undefined && ACP_MCP_PRESERVED_LAUNCH_CODES.has(code))) return error;
+	if (
+		mcpServers.length === 0 ||
+		(code !== undefined && ACP_MCP_PRESERVED_LAUNCH_CODES.has(code)) ||
+		(error instanceof SdkClientError &&
+			error.transport === true &&
+			code !== undefined &&
+			ACP_MCP_PRESERVED_TRANSPORT_CODES.has(code))
+	)
+		return error;
 	const names = mcpServers
 		.slice(0, 8)
 		.map(server => server.name)
 		.join(", ");
 	const suffix = mcpServers.length > 8 ? `, and ${mcpServers.length - 8} more` : "";
-	return new AcpSdkAdapterError("unavailable", `MCP server request failed to start (${names}${suffix}).`);
+	const originalCode = code ?? "unknown";
+	const originalMessage = credentialFreeLifecycleMessage(error);
+	const diagnostic = originalMessage ? ` [${originalCode}: ${originalMessage}]` : ` [${originalCode}]`;
+	const wrapped = new AcpSdkAdapterError(
+		"unavailable",
+		`MCP server request failed to start (${names}${suffix}): broker lifecycle failed${diagnostic}`,
+	);
+	Object.assign(wrapped, { cause: error });
+	return wrapped;
 }
 
 export type AcpReconnectFailedHandler = (error: SdkClientError) => void;

package/src/sdk/broker/doctor-restart.ts

@@ -63,6 +63,41 @@ function typedResult(response: unknown): BrokerRestartResult {
 	return { ok: false, error: { code: "protocol_error", message: "broker returned a malformed restart response" } };
 }
 
+/**
+ * Sends one restart verb. SdkClient rejects an `{ok:false}` response as an
+ * SdkClientError, but that refusal is the broker's own typed decision, so it is
+ * returned as the result. Only a request that got no response for its id (its
+ * outcome is unknown) propagates as an error.
+ */
+async function restartRequest(
+	client: SdkClient,
+	operation: string,
+	input: Record<string, unknown>,
+): Promise<BrokerRestartResult> {
+	let requestFrameId: unknown;
+	let refused = false;
+	const unsubscribe = client.onFrame(frame => {
+		const id = typeof frame.id === "string" ? frame.id : frame.requestId;
+		if (requestFrameId !== undefined && id === requestFrameId && (frame.ok === false || frame.status === "error"))
+			refused = true;
+	});
+	try {
+		return typedResult(
+			await client.global(operation, input, {
+				onDispatch: ({ frame }) => {
+					requestFrameId = frame.id;
+				},
+			}),
+		);
+	} catch (error) {
+		if (refused && error instanceof SdkClientError)
+			return { ok: false, error: { code: error.code, message: error.message } };
+		throw error;
+	} finally {
+		unsubscribe();
+	}
+}
+
 export async function prepareDoctorBrokerRestart(
 	client: SdkClient,
 	discovery: BrokerDiscovery,
@@ -74,7 +109,7 @@ export async function prepareDoctorBrokerRestart(
 		deadlineAt: Date.now() + (options.deadlineMs ?? 30_000),
 		drain: options.drain,
 	};
-	return typedResult(await client.global("broker.prepare_restart", { ...input }));
+	return await restartRequest(client, "broker.prepare_restart", { ...input });
 }
 
 export async function commitDoctorBrokerRestart(
@@ -90,11 +125,11 @@ export async function commitDoctorBrokerRestart(
 		lease: prepared.lease,
 		occupancyEpoch: prepared.occupancyEpoch,
 	};
-	return typedResult(await client.global("broker.commit_restart", { ...input }));
+	return await restartRequest(client, "broker.commit_restart", { ...input });
 }
 
 export async function cancelDoctorBrokerRestart(client: SdkClient, requestId: string): Promise<BrokerRestartResult> {
-	return typedResult(await client.global("broker.cancel_restart", { requestId }));
+	return await restartRequest(client, "broker.cancel_restart", { requestId });
 }
 
 const OLD_OWNER_EXIT_POLL_MS = 50;