@gajae-code/coding-agent 0.16.7 → 0.17.1

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

@@ -47,12 +47,13 @@ import {
 	acpMcpLaunchFailure,
 } from "../../sdk/acp";
 import { resolveAcpFinalText } from "../../sdk/acp/final-text";
-import { ACP_MCP_LIFECYCLE_TIMEOUT_MS, type SessionLifecycleMcpServer } from "../../sdk/acp/mcp";
+import type { SessionLifecycleMcpServer } from "../../sdk/acp/mcp";
 import { ensureBroker } from "../../sdk/broker/ensure";
 import { canonicalSessionCwd } from "../../sdk/broker/session-index";
 import { readSdkBrokerDiscovery, SdkClient, SdkClientError } from "../../sdk/client";
 import type { AbortScope } from "../../sdk/host/control/operations";
 import { SYNTHETIC_PROVIDER_ID } from "../../sdk/model-profile-namespace";
+import { failedPromptOutcome, isSdkPromptFailurePhase, rephaseFailedOutcome } from "../../sdk/prompt-failure";
 import type { SdkPromptTerminalOutcome } from "../../sdk/prompt-status";
 import { PromptActivity, type PromptWatchdogClock, systemPromptWatchdogClock } from "../../sdk/prompt-watchdog";
 import { validateRequiredPromptText } from "../../sdk/protocol/adapter-validation";
@@ -101,16 +102,53 @@ const MAX_PROMPT_FRAME_BYTES = 256 * 1024;
  * envelope. A canonical-length UUID keeps the measurement equal to the real frame.
  */
 const PROMPT_FRAME_ID_PLACEHOLDER = "00000000-0000-4000-8000-000000000000";
+/**
+ * Wall-clock ceiling an external ACP client grants a `session/new` before it
+ * abandons the connection (paseo's daemon uses 60s). gjc must return a
+ * `session.create` response — a launched session or a terminal launch error —
+ * inside this window, or the client reports a dead provider while gjc is still
+ * healthily spawning the host. See issue #5565.
+ */
+export const ACP_EXTERNAL_CONNECT_TIMEOUT_MS = 60_000;
 /**
  * Readiness budget every ACP session launch requests, independent of MCP.
  *
- * Host cold start costs the same whether or not the client declared MCP servers,
- * so leaving the MCP-less path on the broker's 10s default made it the only ACP
- * launch that fails under ordinary concurrency: a second host starting beside the
- * first measurably crosses that deadline, and the broker then reports the launch
- * as `terminal_uncertain`, which an external client surfaces as a dead provider.
+ * Two constraints bound this value:
+ *
+ * 1. Floor — host cold start costs the same whether or not the client declared
+ *    MCP servers, so leaving the MCP-less path on the broker's 10s default made
+ *    it the only ACP launch that failed under ordinary concurrency: a second
+ *    host starting beside the first measurably crosses that deadline, the broker
+ *    reports the launch as `terminal_uncertain`, and an external client surfaces
+ *    a dead provider.
+ * 2. Ceiling — the broker may park a startup in its admission queue for a whole
+ *    readiness budget before the readiness clock even starts, so the ACP adapter
+ *    sizes its client-side wait at `lifecycleStartupBudgetMs(R)` = queue wait +
+ *    readiness = `2·R`, plus caller slack. With R = 30.5s that wait reached ~62s
+ *    — past paseo's 60s connect timeout — so a queued or slow-cold-start launch
+ *    let paseo abandon the connection before gjc could answer `session/new` at
+ *    all (#5565). R must keep `2·R + slack` safely under
+ *    {@link ACP_EXTERNAL_CONNECT_TIMEOUT_MS}.
+ *
+ * 22s satisfies both: comfortably above the ~16s cold starts observed on slow
+ * hosts (and the 10s concurrency floor) while holding the client-side lifecycle
+ * budget near 45s — a ~15s margin under the 60s ceiling.
+ */
+export const ACP_SESSION_READINESS_TIMEOUT_MS = 22_000;
+
+/**
+ * A freshly created session host can accept the first turn before it has finished
+ * coming up (provider stream, tool registry, MCP wiring), so the very first prompt
+ * can terminalize as `prompt_failed` — surfaced to an ACP client as an opaque
+ * `-32603` with no usable result (issue #5574). The failed turn produced no answer,
+ * so re-submitting the same first prompt a bounded number of times recovers the
+ * startup race instead of ending the session on its first turn. Only the first
+ * logical prompt of a session retries, and only an `agent_failed` `prompt_failed`
+ * terminal (never a deadline, a client cancel, or a clean stop) is retried.
  */
-const ACP_SESSION_READINESS_TIMEOUT_MS = ACP_MCP_LIFECYCLE_TIMEOUT_MS;
+const ACP_FIRST_PROMPT_MAX_RETRIES = 2;
+/** Backoff before each first-prompt retry, scaled by attempt (250ms, then 500ms). */
+const ACP_FIRST_PROMPT_RETRY_BASE_DELAY_MS = 250;
 
 type JsonObject = Record<string, unknown>;
 interface PromptWaiter {
@@ -143,6 +181,10 @@ interface PromptWaiter {
 	cancelWatchdog?: () => void;
 	/** What the host is observably doing — a tool running, a model call unanswered — and the bound that follows from it. */
 	activity: PromptActivity;
+	/** True once a prompt-owned progress frame (agent_start / message / tool) was observed; gates first-turn retries. */
+	observedTurnActivity: boolean;
+	/** True once a prompt-owned tool execution frame was observed; vetoes a first-turn retry that would re-run it. */
+	observedToolExecution: boolean;
 	/** Coordinates a prompt-control rejection racing an acknowledged ACP cancellation. */
 	cancelAttempt?: Promise<boolean>;
 	/** Whether ANY overlapping cancel attempt for this prompt was acknowledged:
@@ -169,6 +211,7 @@ type PendingAttachment = { epoch: number; task: Promise<void> };
 type SessionRecord = {
 	cwd: string;
 	adapter: AcpSdkAdapter;
+	primaryControlSurface: "cli" | "sdk";
 	attachment: SessionAttachment;
 	closeIdempotencyKey: string;
 	unsubscribe: () => void;
@@ -198,8 +241,78 @@ type SessionRecord = {
 	activePrompt?: PromptWaiter;
 	/** Set by `session/cancel` so an in-flight prompt settles as `cancelled`, never as an error. */
 	cancelRequested?: boolean;
+	/** True once the session's first logical prompt has settled; gates first-turn readiness retries. */
+	firstPromptDone?: boolean;
+	/** Whether the current prompt attempt was observed doing work; reset per attempt, read by the first-turn retry gate. */
+	promptObservedActivity?: boolean;
+	/** Whether the current prompt attempt executed a tool; reset per attempt, vetoes a first-turn retry that would re-run it. */
+	promptObservedToolExecution?: boolean;
+	/** Whether the current prompt attempt published assistant text/thought output; reset per attempt, vetoes a first-turn retry that would re-emit it. */
+	promptObservedAssistantOutput?: boolean;
+	/** Owner token held across the first-turn retry backoff; a non-owner prompt is rejected as a conflict (review P1). */
+	pendingFirstPromptRetry?: FirstPromptRetryReservation;
 };
 
+/**
+ * Identity token proving a caller owns an in-progress first-turn retry. While it is held on the
+ * session record, `#submitPrompt` rejects any prompt that is not this owner, so a concurrent
+ * request cannot slip into the gap between `#settlePrompt` clearing `activePrompt` on the failed
+ * first attempt and the retry resubmitting after its backoff (review P1, issue #5574).
+ */
+type FirstPromptRetryReservation = {
+	readonly firstPromptRetry: true;
+	/**
+	 * Set once `#submitPrompt` dispatched a turn for this prompt. Distinguishes a prompt that
+	 * genuinely owned the session's first turn from a preflight rejection, so only the former
+	 * settles `firstPromptDone` (review P2).
+	 */
+	admitted?: boolean;
+	/**
+	 * Terminal settlement recorded by a teardown that won the backoff gap. The failed attempt
+	 * already cleared `activePrompt`, so `#teardownSession` has no waiter to settle for this
+	 * caller and nothing else carries the outcome across the sleep. Without it the retry wakes
+	 * to a deleted record and resubmits into `not_found`, where a client-driven close/delete
+	 * owes the ACP `cancelled` stop reason (review P1).
+	 */
+	settlement?: { kind: "cancelled" } | { kind: "rejected"; error: AcpSdkAdapterError };
+};
+
+/**
+ * Prompt-owned frame types that prove the turn is underway (as opposed to a
+ * terminal or a bare failure diagnostic). Observing one is the first-turn
+ * readiness-race fingerprint the retry gate keys on.
+ */
+function isTurnProgressEventType(type: string | undefined): boolean {
+	switch (type) {
+		case "agent_start":
+		case "message_start":
+		case "message_update":
+		case "message_end":
+		case "tool_execution_start":
+		case "tool_execution_update":
+		case "tool_execution_end":
+			return true;
+		default:
+			return false;
+	}
+}
+
+/**
+ * Prompt-owned frame types that prove a tool actually executed. A turn that ran a tool did
+ * side-effecting work, so it must never be re-run by the first-turn readiness retry (issue
+ * #5574 / review P1): a re-submit is an independent turn that would repeat those side effects.
+ */
+function isTurnToolExecutionEventType(type: string | undefined): boolean {
+	switch (type) {
+		case "tool_execution_start":
+		case "tool_execution_update":
+		case "tool_execution_end":
+			return true;
+		default:
+			return false;
+	}
+}
+
 function promptWaiterRetired(record: SessionRecord, waiter: PromptWaiter): boolean {
 	return waiter.settled || record.activePrompt !== waiter;
 }
@@ -496,6 +609,45 @@ function logDroppedPromptTerminal(
 	});
 }
 
+type SdkPromptFailedOutcome = Extract<SdkPromptTerminalOutcome, { kind: "failed" }>;
+
+/**
+ * A prompt rejection that still carries the terminal's structured failure classification.
+ * The ACP client sees only the code and message, but the first-turn retry gate must decide on
+ * what the terminal actually proved — the failure's execution phase and its bounded origin
+ * category — so settlement carries that classification instead of discarding it into a bare
+ * `AcpSdkAdapterError` (review P1, issue #5574).
+ */
+class AcpPromptFailureError extends AcpSdkAdapterError {
+	readonly failure: SdkPromptFailedOutcome;
+	constructor(failure: SdkPromptFailedOutcome) {
+		super(failure.code, failure.message);
+		this.failure = failure;
+	}
+}
+
+/**
+ * The startup-readiness failure class (issue #5574): the turn failed AFTER it started, with a
+ * bounded provider/transport classifier — the signature of a host that accepted the turn before
+ * its provider stream had finished coming up.
+ *
+ * Every other failure a `prompt_failed` terminal can carry is a genuine failure of this turn and
+ * is surfaced rather than re-submitted, even when it happened to publish nothing: a provider
+ * rejection (quota, refusal, 4xx), an agent runtime failure, a submission-phase rejection, or a
+ * deadline. Without this class check, "started, no output" alone authorized a retry, so any such
+ * rejection was silently re-run as a second turn (review P1).
+ */
+function isStartupReadinessFailure(error: unknown): boolean {
+	if (!(error instanceof AcpPromptFailureError)) return false;
+	const { failure } = error;
+	return (
+		failure.code === "prompt_failed" &&
+		failure.provenance === "agent_failed" &&
+		failure.phase === "post_start" &&
+		failure.category === "provider_transport"
+	);
+}
+
 function terminalOutcome(event: JsonObject): SdkPromptTerminalOutcome | undefined {
 	const outcome = object(event.outcome);
 	if (!outcome) return undefined;
@@ -514,13 +666,15 @@ function terminalOutcome(event: JsonObject): SdkPromptTerminalOutcome | undefine
 		(outcome.code === "prompt_failed" || outcome.code === "prompt_deadline_exceeded") &&
 		typeof outcome.message === "string" &&
 		(outcome.provenance === "agent_failed" || outcome.provenance === "deadline")
-	)
-		return {
-			kind: "failed",
+	) {
+		return failedPromptOutcome({
 			code: outcome.code,
-			message: outcome.message,
 			provenance: outcome.provenance,
-		};
+			...(typeof outcome.providerCode === "string" ? { providerCode: outcome.providerCode } : {}),
+			...(isSdkPromptFailurePhase(outcome.phase) ? { phase: outcome.phase } : {}),
+			evidence: {},
+		});
+	}
 	return undefined;
 }
 
@@ -756,6 +910,22 @@ function configValues(query: unknown): Map<string, string> {
 	return values;
 }
 
+/**
+ * Recover a session-scoped preset only when the host's current model carries
+ * the synthetic profile namespace. A plain `modelPreset` value may be the
+ * persisted default and is therefore insufficient to identify an active
+ * profile, especially when attaching through the base ACP provider.
+ */
+export function activeModelPresetFromConfig(query: unknown): string | undefined {
+	const values = configValues(query);
+	const model = values.get(MODEL_CONFIG_ID);
+	const preset = values.get(MODEL_PRESET_CONFIG_KEY);
+	const prefix = `${SYNTHETIC_PROVIDER_ID}/`;
+	if (!model?.startsWith(prefix) || !preset) return undefined;
+	const syntheticPreset = model.slice(prefix.length);
+	return syntheticPreset === preset ? syntheticPreset : undefined;
+}
+
 function modelPresetConfigOptions(query: unknown, current: string): { value: string; name: string }[] {
 	const options = new Map<string, string>();
 	for (const item of pageItems(query)) {
@@ -1380,8 +1550,11 @@ export class AcpAgent implements Agent {
 		);
 		const id = sessionId(result);
 		this.#knownSessionCwds.set(id, params.cwd);
-		this.#ownedSessionIds.add(id);
 		this.#knownSessionMcpServers.set(id, mcpServers);
+		// This connection launched the host, so it owns the broker lifecycle before the
+		// attachment reports a control surface. Without it a failed attach discards the
+		// session as unowned and masks the real error with cleanup uncertainty.
+		this.#ownedSessionIds.add(id);
 		try {
 			await this.#attach(id, params.cwd, undefined, result);
 			await applyAcpStartupOptions(this.#adapter(id), this.#startupOptions);
@@ -1437,8 +1610,10 @@ export class AcpAgent implements Agent {
 		);
 		const id = sessionId(result);
 		this.#knownSessionCwds.set(id, params.cwd);
-		this.#ownedSessionIds.add(id);
 		this.#knownSessionMcpServers.set(id, mcpServers);
+		// Forking launches a host through this connection, so lifecycle ownership is
+		// established before attachment for the same reason as `newSession`.
+		this.#ownedSessionIds.add(id);
 		try {
 			await this.#attach(id, params.cwd, undefined, result);
 			const response = { sessionId: id, ...(await this.#sessionState(id)) };
@@ -1484,8 +1659,10 @@ export class AcpAgent implements Agent {
 
 	closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
 		const record = this.#sessions.get(params.sessionId);
-		// ACP close has no cwd. Only connection-owned sessions may reach broker lifecycle control.
-		if (!this.#ownedSessionIds.has(params.sessionId)) return Promise.resolve({});
+		// ACP close has no cwd. Broker lifecycle control stays owner-only, but a live
+		// local attachment is always released: a CLI-primary session the client closed
+		// must not keep its adapter, lease heartbeat, subscriptions and pending prompt.
+		if (!this.#ownedSessionIds.has(params.sessionId) && record === undefined) return Promise.resolve({});
 		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId);
 		if (!cwd) return Promise.resolve({});
 		return this.#enqueueLifecycleOperation(params.sessionId, async () => {
@@ -1500,7 +1677,17 @@ export class AcpAgent implements Agent {
 		const pendingLocator = this.#pendingDeleteLocators.get(params.sessionId);
 		// Capture authority before joining the lifecycle chain: an admitted delete must
 		// remain authorized when a preceding close retires connection ownership.
-		if (!this.#ownedSessionIds.has(params.sessionId) && pendingLocator === undefined) return {};
+		if (!this.#ownedSessionIds.has(params.sessionId) && pendingLocator === undefined) {
+			// Deleting a live session this connection does not own would claim a durable
+			// deletion it never performs. Unknown ids stay the protocol no-op; a live
+			// CLI-primary attachment is refused explicitly instead of faking success.
+			if (record !== undefined)
+				throw new AcpSdkAdapterError(
+					"operation_prohibited",
+					`ACP session ${params.sessionId} is owned by its terminal host; delete it from that session instead.`,
+				);
+			return {};
+		}
 		const cwd = record?.cwd ?? this.#knownSessionCwds.get(params.sessionId) ?? pendingLocator?.cwd;
 		return this.#enqueueLifecycleOperation(params.sessionId, async () => {
 			// ACP's delete request has no cwd. Unknown ids remain the protocol no-op,
@@ -1590,10 +1777,14 @@ export class AcpAgent implements Agent {
 				await this.setSessionMode({ sessionId: params.sessionId, modeId: params.value });
 				break;
 			case MODEL_CONFIG_ID:
-				if (this.#startupOptions?.modelPreset === undefined) {
-					await this.#adapter(params.sessionId).setModel(params.value);
-				} else if (params.value !== ACP_CUSTOM_MODEL_PRESET) {
-					await this.#adapter(params.sessionId).control("model.profile.set", { id: params.value });
+				{
+					const config = await this.#adapter(params.sessionId).query("config.list/get");
+					const activePreset = this.#startupOptions?.modelPreset ?? activeModelPresetFromConfig(config);
+					if (activePreset === undefined) {
+						await this.#adapter(params.sessionId).setModel(params.value);
+					} else if (params.value !== ACP_CUSTOM_MODEL_PRESET) {
+						await this.#adapter(params.sessionId).control("model.profile.set", { id: params.value });
+					}
 				}
 				break;
 			case THINKING_CONFIG_ID:
@@ -1614,8 +1805,168 @@ export class AcpAgent implements Agent {
 	}
 
 	async prompt(params: PromptRequest): Promise<PromptResponse> {
+		const record = this.#sessions.get(params.sessionId);
+		// An unknown session must still report not_found; the retry loop only guards a
+		// live session's first turn against a startup readiness race (issue #5574).
+		if (!record) return await this.#submitPrompt(params, true);
+		// Identity of THIS caller's first-turn retry. Held on the record across the backoff so a
+		// concurrent prompt racing the gap is rejected as a conflict rather than admitted (review P1).
+		const retryReservation: FirstPromptRetryReservation = { firstPromptRetry: true };
+		try {
+			let echoUserMessage = true;
+			for (let attempt = 0; ; attempt++) {
+				try {
+					return await this.#submitPrompt(params, echoUserMessage, retryReservation);
+				} catch (error) {
+					if (!this.#shouldRetryFirstPrompt(record, error, attempt)) throw error;
+					// The user's message was already echoed on the first attempt; re-echoing
+					// would duplicate it in the client transcript.
+					echoUserMessage = false;
+					// Reserve the session BEFORE the backoff sleep. `#settlePrompt` already cleared
+					// `activePrompt` when it rejected this attempt, so without the reservation the
+					// backoff gap admits a competing prompt that steals the first turn (review P1).
+					record.pendingFirstPromptRetry = retryReservation;
+					logger.warn("ACP first-turn prompt failed; retrying after readiness backoff", {
+						sessionId: params.sessionId,
+						attempt: attempt + 1,
+						maxRetries: ACP_FIRST_PROMPT_MAX_RETRIES,
+					});
+					await this.#delayFirstPromptRetry(attempt);
+					// The failed attempt publishes its final text and its failure diagnostic on async
+					// tails, and `#submitPrompt` rejects any prompt while one of them is still in
+					// flight. A slow or backpressured ACP client keeps a tail running well past a
+					// 250/500ms backoff, so an authorized retry would lose its own turn to a
+					// `conflict` raised by its own predecessor's publications. Wait the tails out
+					// here instead of weakening those guards, which still have to reject prompts
+					// racing in from other callers (review P1).
+					await this.#drainPromptPublicationTails(params.sessionId);
+					// A session/close or session/delete that won the backoff gap tore the record
+					// down without a waiter to settle, leaving its outcome on this reservation.
+					// Honor it here: resubmitting would only reach `#submitPrompt`'s not_found,
+					// which is not what a client-driven teardown owes the caller (review P1).
+					const settlement = retryReservation.settlement;
+					if (settlement) {
+						if (settlement.kind === "cancelled") return { stopReason: "cancelled" };
+						throw settlement.error;
+					}
+					// A session/cancel that arrived during the backoff gap (activePrompt already
+					// cleared by the failed attempt, retry not yet resubmitted) must settle the
+					// retry as `cancelled` instead of dispatching a fresh turn the client no
+					// longer wants. The check lives here, before resubmission, because
+					// `#submitPrompt` unconditionally clears `cancelRequested` for the new turn
+					// it is about to start, so a later check would miss it (review P1).
+					if (record.cancelRequested) {
+						record.cancelRequested = false;
+						return { stopReason: "cancelled" };
+					}
+				}
+			}
+		} finally {
+			// Release the reservation on retry completion (success), cancellation, or final
+			// failure. Guarded so a later prompt that took ownership is never cleared by this caller.
+			if (record.pendingFirstPromptRetry === retryReservation) record.pendingFirstPromptRetry = undefined;
+			// Only a turn that was actually admitted (dispatched to the host) settles the
+			// session's first prompt. A preflight rejection — validation, auth/preflight, a
+			// stale-state conflict, an oversize frame, or an ensureProviders() failure — never
+			// owned a turn, so it must not consume the one-shot first-turn retry budget: a later
+			// valid first prompt that hits the startup readiness race must still be retryable
+			// (review P2).
+			if (retryReservation.admitted) record.firstPromptDone = true;
+		}
+	}
+
+	/**
+	 * The readiness-race signature (issue #5574): the session's first turn was accepted
+	 * and started producing frames (an `agent_start`), then failed as `prompt_failed` before
+	 * ever completing. Re-submitting the same first prompt a bounded number of times lets a
+	 * host that has since finished coming up answer it, instead of ending the session on its
+	 * first turn.
+	 *
+	 * A retry re-submits the prompt as a fresh, INDEPENDENT `turn.prompt` — `AcpSdkAdapter`
+	 * assigns a new request id per call — so it must never re-run a turn that already did
+	 * side-effecting work. If the failed turn executed a tool, re-submitting would run the
+	 * user's instruction, and its side effects, a second time (review P1). A turn that only
+	 * started (agent_start / streamed text) but ran no tool produced no external effect, so
+	 * recovering it is safe.
+	 *
+	 * Every gate is deliberately narrow so a genuine failure is still surfaced:
+	 * - only the first logical prompt of the session (`!firstPromptDone`);
+	 * - only the startup-readiness failure class the terminal itself classified
+	 *   (`isStartupReadinessFailure`): a post-start `agent_failed` `prompt_failed` with a
+	 *   provider/transport classifier — never a client cancel, a `prompt_deadline_exceeded`,
+	 *   a provider rejection, an agent runtime failure, a transport error, or a preflight
+	 *   rejection, however little output they happened to produce;
+	 * - only after the turn was observed starting (`promptObservedActivity`), the race's
+	 *   fingerprint, which a turn rejected before it ever started never has;
+	 * - but NEVER once the turn executed a tool (`promptObservedToolExecution`), so a
+	 *   progressed, side-effecting turn is never re-run as a second turn;
+	 * - but NEVER once the turn published assistant text/thought output
+	 *   (`promptObservedAssistantOutput`), so a re-submit cannot expose duplicated output
+	 *   from both attempts to the live ACP update stream — including a failed terminal's own
+	 *   `finalText`, which is published on an async tail after this gate runs;
+	 * - never once the client has asked to cancel.
+	 */
+	#shouldRetryFirstPrompt(record: SessionRecord, error: unknown, attempt: number): boolean {
+		if (attempt >= ACP_FIRST_PROMPT_MAX_RETRIES) return false;
+		// The primary gate: only the failure class the terminal classified as a startup
+		// readiness race is recoverable. The activity/tool/output gates below stay as secondary
+		// safety checks on top of it — they bound what may be re-run, not what is worth re-running.
+		if (!isStartupReadinessFailure(error)) return false;
+		if (record.firstPromptDone) return false;
+		if (record.cancelRequested) return false;
+		if (!record.promptObservedActivity) return false;
+		// Never re-run a turn that already executed a tool: a re-submit is a new, independent
+		// turn.prompt, so repeating a tool-executing turn would run the user's instruction and
+		// its side effects a second time (review P1).
+		if (record.promptObservedToolExecution) return false;
+		// Never re-run a turn that already published — or has committed to publishing —
+		// assistant text/thought output: a re-submit is a new, independent turn.prompt whose
+		// output would be delivered to ACP consumers on top of the failed attempt's chunks or
+		// its terminal's final text, duplicating or corrupting the assistant stream.
+		if (record.promptObservedAssistantOutput) return false;
+		return true;
+	}
+
+	/**
+	 * Settles the publication tails a finished turn left running: its terminal's final text, its
+	 * end-of-turn metadata, and its failure diagnostic. Each tail owns one of `#submitPrompt`'s
+	 * conflict guards, and a tail can start another (the failure diagnostic awaits the final text),
+	 * so this drains until none is left rather than sampling once.
+	 */
+	async #drainPromptPublicationTails(id: string): Promise<void> {
+		for (;;) {
+			const tails = [
+				this.#finalTextTails.get(id),
+				this.#terminalMetadataTails.get(id),
+				this.#failureDiagnosticTails.get(id),
+			].filter((tail): tail is Promise<void> => tail !== undefined);
+			if (tails.length === 0) return;
+			// A publication failure is the tail's own business; it is logged where it happens and
+			// must not decide the retry.
+			await Promise.allSettled(tails);
+		}
+	}
+
+	/** Backoff between first-prompt retries, on the injectable watchdog clock so tests can advance it. */
+	#delayFirstPromptRetry(attempt: number): Promise<void> {
+		const delayMs = ACP_FIRST_PROMPT_RETRY_BASE_DELAY_MS * (attempt + 1);
+		return new Promise<void>(resolve => {
+			this.#promptWatchdogClock.schedule(resolve, delayMs);
+		});
+	}
+
+	async #submitPrompt(
+		params: PromptRequest,
+		echoUserMessage: boolean,
+		retryReservation?: FirstPromptRetryReservation,
+	): Promise<PromptResponse> {
 		const record = this.#sessions.get(params.sessionId);
 		if (!record) throw new AcpSdkAdapterError("not_found", `Unknown session, not found: ${params.sessionId}`);
+		// A first-turn retry holds the session across its backoff gap. Any prompt that is not the
+		// retry owner is rejected here, before any state mutation or dispatch, so it cannot steal
+		// the first turn while the authorized retry is still pending (review P1, issue #5574).
+		if (record.pendingFirstPromptRetry && record.pendingFirstPromptRetry !== retryReservation)
+			throw new AcpSdkAdapterError("conflict", "ACP session is retrying its first prompt.");
 		if (record.activePrompt) throw new AcpSdkAdapterError("conflict", "ACP session already has an active prompt.");
 		if (record.authFailure) throw new AcpSdkAdapterError("authentication_failed", record.authFailure);
 		if (this.#retiredPromptAcknowledgements.has(params.sessionId))
@@ -1684,6 +2035,11 @@ export class AcpAgent implements Agent {
 				)} KiB transport limit. Attach a smaller or more compressed image.`,
 			);
 		record.publicationGeneration++;
+		// Reset per attempt: a first-turn readiness retry keys on whether THIS attempt was
+		// observed doing work, never a prior attempt's activity.
+		record.promptObservedActivity = false;
+		record.promptObservedToolExecution = false;
+		record.promptObservedAssistantOutput = false;
 		const { promise: response, resolve, reject } = Promise.withResolvers<PromptResponse>();
 		const waiter: PromptWaiter = {
 			acknowledged: false,
@@ -1700,6 +2056,8 @@ export class AcpAgent implements Agent {
 			lastFrameAt: this.#promptWatchdogClock.now(),
 			lastFrameType: "prompt_dispatch",
 			activity: new PromptActivity(),
+			observedTurnActivity: false,
+			observedToolExecution: false,
 			resolve,
 			reject,
 		};
@@ -1746,19 +2104,26 @@ export class AcpAgent implements Agent {
 		// image never appear in the client UI — only the agent's reply does. Replay
 		// (session/load) already emits these; a live turn must too, and the image blocks
 		// must be published verbatim so attachments are visible, not just fed to the model.
-		for (const block of params.prompt) {
-			if (block.type !== "text" && block.type !== "image") continue;
-			if (block.type === "text" && block.text.length === 0) continue;
-			await this.#publishSessionUpdate(
-				params.sessionId,
-				{
-					sessionId: params.sessionId,
-					update: { sessionUpdate: "user_message_chunk", content: block },
-				},
-				record.adapter,
-			);
-		}
+		// A first-turn readiness retry (issue #5574) skips the echo: the message was already
+		// published on the first attempt and re-echoing would duplicate it in the transcript.
+		if (echoUserMessage)
+			for (const block of params.prompt) {
+				if (block.type !== "text" && block.type !== "image") continue;
+				if (block.type === "text" && block.text.length === 0) continue;
+				await this.#publishSessionUpdate(
+					params.sessionId,
+					{
+						sessionId: params.sessionId,
+						update: { sessionUpdate: "user_message_chunk", content: block },
+					},
+					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;
 		}
@@ -1843,6 +2208,8 @@ export class AcpAgent implements Agent {
 				}
 				if (matchesWaiter) {
 					this.#observePromptActivity(waiter, deferredFrame);
+					if (waiter.observedTurnActivity) record.promptObservedActivity = true;
+					if (waiter.observedToolExecution) record.promptObservedToolExecution = true;
 					observedDeferredActivity = true;
 				}
 			}
@@ -2029,7 +2396,11 @@ export class AcpAgent implements Agent {
 			}
 			waiter?.cancelAttemptResolve?.(true);
 		} catch (error) {
-			if (!waiter) record.cancelRequested = false;
+			// With no active prompt the cancel intent normally clears — except when a first-turn
+			// retry is reserved across its backoff gap. That reservation owner has not yet observed
+			// the cancel; clearing it here would let the retry resubmit a turn the client cancelled
+			// (review P1). Leave the flag for the retry's post-backoff check to settle as cancelled.
+			if (!waiter && !record.pendingFirstPromptRetry) record.cancelRequested = false;
 			// Only the LAST in-flight attempt resolves the shared promise false;
 			// an earlier attempt may still acknowledge (review thread P2). After
 			// every attempt of this wave failed, RE-ARM the aggregate: a later
@@ -2227,7 +2598,7 @@ export class AcpAgent implements Agent {
 			// session host remains authoritative for its immutable configuration, so
 			// attachment must not reinterpret the replay as a mutation request.
 			this.#pendingDeleteLocators.delete(id);
-			await attached.adapter.ensureProviders();
+			if (attached.primaryControlSurface === "sdk") await attached.adapter.ensureProviders();
 			return;
 		}
 		const knownCwd = this.#knownSessionCwds.get(id);
@@ -2313,7 +2684,7 @@ export class AcpAgent implements Agent {
 		if (existing) {
 			if (path.resolve(existing.cwd) !== path.resolve(cwd))
 				throw new AcpSdkAdapterError("conflict", `ACP session ${id} has conflicting cwd authority.`);
-			await existing.adapter.ensureProviders();
+			if (existing.primaryControlSurface === "sdk") await existing.adapter.ensureProviders();
 			return;
 		}
 		const attaching = this.#attaching.get(id);
@@ -2368,7 +2739,10 @@ export class AcpAgent implements Agent {
 			});
 			unsubscribePendingFrames = adapter.onFrame(frame => pendingAdapterFrames.push(frame));
 			this.#pendingRouterAdapters.set(id, adapter);
-			await adapter.start();
+			// Query startup provenance before activating reverse providers. A CLI
+			// host must retain terminal permission/UI leases and lifecycle authority;
+			// a broker-launched SDK host keeps ACP ownership across reconnects.
+			await adapter.start({ activateProviders: false });
 			let capabilities: JsonObject | undefined;
 			try {
 				const response = object(await adapter.query("runtime.capabilities"));
@@ -2377,11 +2751,22 @@ export class AcpAgent implements Agent {
 				// page item, so fall back to the envelope only for direct-result hosts.
 				capabilities = object(pageItems(result)[0]) ?? result;
 			} catch {}
-			if (capabilities?.promptTerminalOutcomeVersion !== 1)
+			const primaryControlSurface =
+				capabilities?.primaryControlSurface === "sdk"
+					? "sdk"
+					: capabilities?.primaryControlSurface === "cli"
+						? "cli"
+						: undefined;
+			if (capabilities?.promptTerminalOutcomeVersion !== 1 || primaryControlSurface === undefined)
 				throw new AcpSdkAdapterError(
 					"unavailable",
-					"This ACP client requires a newer GJC SDK session; restart the session.",
+					"This ACP client requires a newer GJC SDK session with startup control provenance; restart the session.",
 				);
+			if (primaryControlSurface === "sdk") {
+				adapter.authorizeProviderActivation();
+				await adapter.ensureProviders();
+				await applyAcpPermissionMode(adapter, this.#clientCapabilities);
+			}
 			this.#assertSessionEpoch(id, epoch);
 			const exactAttachment = this.#router.attachment(id) ?? currentAttachment;
 			if (!exactAttachment.isCurrent())
@@ -2389,6 +2774,7 @@ export class AcpAgent implements Agent {
 			const record: SessionRecord = {
 				cwd,
 				adapter,
+				primaryControlSurface,
 				attachment: exactAttachment,
 				closeIdempotencyKey: randomUUID(),
 				unsubscribe: () => {},
@@ -2404,6 +2790,12 @@ export class AcpAgent implements Agent {
 				backgroundCorrelations: [],
 				toolArgs: new Map(),
 			};
+			// Preserve first-turn state across reattachment (issue #5574). The startup-readiness
+			// retry only guards a session's very first logical prompt; a fresh record built on
+			// reconnect/reattach would otherwise reset that guard and let a later prompt take the
+			// retry — and re-run — path. Reattachment retains the session's settled prompt
+			// correlations, so a non-empty set proves at least one prompt has already completed.
+			if (record.settledPromptCorrelations.length > 0) record.firstPromptDone = true;
 			record.unsubscribe = adapter.onFrame(frame => this.#enqueueSdkFrame(id, adapter!, frame));
 			record.reconnectUnsubscribe = adapter.onReconnectFailed(error =>
 				this.#recoverSessionAfterTransportFailure(id, adapter!, error),
@@ -2415,8 +2807,10 @@ export class AcpAgent implements Agent {
 			this.#pendingRouterAdapters.delete(id);
 			this.#pendingRouterFrames.delete(id);
 			this.#knownSessionCwds.set(id, cwd);
-			this.#ownedSessionIds.add(id);
-			await applyAcpPermissionMode(adapter, this.#clientCapabilities);
+			// Host provenance is authoritative for lifecycle authority: a CLI-primary host
+			// keeps it in its terminal even when this connection created the session.
+			if (primaryControlSurface === "sdk") this.#ownedSessionIds.add(id);
+			else this.#ownedSessionIds.delete(id);
 			this.#assertSessionEpoch(id, epoch);
 			// A successful attachment establishes a new live-owner epoch. Any locator
 			// retained from an earlier cleanup_pending delete belongs to the terminal
@@ -2552,7 +2946,9 @@ export class AcpAgent implements Agent {
 			// The record is published before permission initialization. Let a canceled
 			// provisional attachment retire it before selecting the generation key.
 			if (attaching) await Promise.allSettled([attaching.task]);
-			await this.#teardownSession(id, "closed", true);
+			// A CLI-primary host owns its own process lifecycle: release this ACP
+			// attachment locally and never ask the broker to close the session.
+			await this.#teardownSession(id, "closed", this.#ownedSessionIds.has(id));
 			this.#knownSessionCwds.delete(id);
 			this.#ownedSessionIds.delete(id);
 			this.#knownSessionMcpServers.delete(id);
@@ -2586,19 +2982,36 @@ export class AcpAgent implements Agent {
 				record.unsubscribe();
 				record.reconnectUnsubscribe();
 				record.activePrompt = undefined;
-				// `session/close` is the client asking to end its own work, so the pending turn
-				// settles as `cancelled` rather than surfacing a spurious error. ACP: "Agents
-				// MUST catch these errors and return the semantically meaningful `cancelled`
-				// stop reason." Involuntary teardown (transport loss) still rejects.
+				const voluntary = reason === "closed" || reason === "discarded" || reason === "deleted";
+				// `session/close` and `session/delete` are the client asking to end its own work, so
+				// the pending turn settles as `cancelled` rather than surfacing a spurious error.
+				// ACP: "Agents MUST catch these errors and return the semantically meaningful
+				// `cancelled` stop reason." Involuntary teardown (transport loss) still rejects.
 				if (waiter && !waiter.settled) {
 					clearPromptWatchdog(waiter);
-					if (reason === "closed" || reason === "discarded") {
+					if (voluntary) {
 						waiter.settled = true;
 						waiter.resolve({ stopReason: "cancelled" });
 					} else {
 						waiter.reject(new AcpSdkAdapterError("connection_closed", `ACP session was ${reason}.`));
 					}
 				}
+				// A first-turn retry sleeping out its backoff owns no waiter — its failed attempt
+				// already cleared `activePrompt` — so the settlement above cannot reach it. Record
+				// the teardown on its reservation instead, with the same voluntary/involuntary
+				// split, and release the reservation: otherwise the retry wakes to a deleted
+				// record and resubmits, surfacing `not_found` where the client's close/delete owes
+				// `cancelled` (review P1).
+				const reservation = record.pendingFirstPromptRetry;
+				if (reservation) {
+					reservation.settlement ??= voluntary
+						? { kind: "cancelled" }
+						: {
+								kind: "rejected",
+								error: new AcpSdkAdapterError("connection_closed", `ACP session was ${reason}.`),
+							};
+					record.pendingFirstPromptRetry = undefined;
+				}
 			}
 
 			const failures: unknown[] = [];
@@ -2809,6 +3222,8 @@ export class AcpAgent implements Agent {
 		}
 		if (!correlationsExactlyMatch(waiter.correlation, correlation)) return;
 		this.#observePromptActivity(waiter, frame);
+		if (waiter.observedTurnActivity) record.promptObservedActivity = true;
+		if (waiter.observedToolExecution) record.promptObservedToolExecution = true;
 		this.#armPromptWatchdog(id, record, waiter);
 	}
 
@@ -2817,6 +3232,10 @@ export class AcpAgent implements Agent {
 		waiter.lastFrameAt = this.#promptWatchdogClock.now();
 		waiter.lastFrameType =
 			typeof event?.type === "string" ? event.type : typeof frame.type === "string" ? frame.type : "unknown";
+		if (isTurnProgressEventType(typeof event?.type === "string" ? event.type : undefined))
+			waiter.observedTurnActivity = true;
+		if (isTurnToolExecutionEventType(typeof event?.type === "string" ? event.type : undefined))
+			waiter.observedToolExecution = true;
 		waiter.activity.observe(
 			typeof event?.type === "string" ? event.type : undefined,
 			typeof event?.toolCallId === "string" ? event.toolCallId : undefined,
@@ -3031,7 +3450,24 @@ export class AcpAgent implements Agent {
 				);
 				return;
 			}
-			activePrompt.terminal = { outcome, correlation };
+			// When a client cancel has been requested, a trailing stopped terminal may
+			// still carry the normal `end_turn` reason (the model finished its response as
+			// the cancel arrived mid-stream, or the cancel was processed before the prompt
+			// was acknowledged). The client's cancellation is the authoritative cause;
+			// remap only `end_turn` — deliberate host reasons (e.g. `refusal`, `max_tokens`)
+			// remain authoritative and must NOT be overridden.
+			const settledOutcome =
+				record.cancelRequested && outcome.kind === "stopped" && outcome.reason === "end_turn"
+					? { ...outcome, reason: "cancelled" as const, provenance: "client_cancel" as const }
+					: outcome;
+			activePrompt.terminal = { outcome: settledOutcome, correlation };
+			// A terminal carrying final text still publishes it as an assistant chunk, on the
+			// async tail `#scheduleTerminalUpdates` starts below. A failed terminal can carry it
+			// with no preceding stream chunks at all, so the streamed-chunk flag stays false and
+			// the first-turn retry gate — which the settlement below releases — would see
+			// "started, no output", resubmit, and let BOTH this terminal's final text and the
+			// retry's answer reach ACP consumers. Record the output before settling (review P1).
+			if (typeof event.finalText === "string" && event.finalText) record.promptObservedAssistantOutput = true;
 			// Failure diagnostics are useful but advisory. Settle before any mapped
 			// session update can await a backpressured client transport; otherwise an
 			// already-decided failure can still lose to the inactivity watchdog.
@@ -3098,6 +3534,16 @@ export class AcpAgent implements Agent {
 				notification.update.content.type === "text"
 			)
 				promptOwner.emittedAssistantText += notification.update.content.text;
+			// A live assistant text/thought chunk for this prompt owner has now been exposed to
+			// ACP consumers. Record it so the first-turn readiness retry is vetoed: a re-submit
+			// would deliver a second attempt's output on top of these chunks (issue #5574).
+			if (
+				promptOwner &&
+				event.type !== "agent_failed" &&
+				(notification.update.sessionUpdate === "agent_message_chunk" ||
+					notification.update.sessionUpdate === "agent_thought_chunk")
+			)
+				record.promptObservedAssistantOutput = true;
 			// The prompt rejection carries the sanitized failure diagnostic. Publishing
 			// a second session update after settlement would be stale as soon as the client
 			// starts a replacement turn, and an in-flight transport write cannot be revoked.
@@ -3344,7 +3790,16 @@ export class AcpAgent implements Agent {
 			waiter.resolve({ stopReason: outcome.reason });
 			return;
 		}
-		waiter.reject(new AcpSdkAdapterError(outcome.code, outcome.message));
+		// `phase` is the host's own claim, and a host that omits it leaves `terminalOutcome`
+		// deriving the phase with no evidence at all — `submission`, even for a turn this
+		// 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 =
+			outcome.phase === "post_start"
+				? outcome
+				: (rephaseFailedOutcome(outcome, { hasActivity: waiter.observedTurnActivity }) as SdkPromptFailedOutcome);
+		waiter.reject(new AcpPromptFailureError(failure));
 	}
 
 	async #emitEndOfTurnUpdates(id: string, adapter: AcpSdkAdapter, publicationGeneration: number): Promise<void> {
@@ -3473,25 +3928,20 @@ export class AcpAgent implements Agent {
 	): Promise<Pick<NewSessionResponse, "configOptions" | "modes">> {
 		const record = this.#sessions.get(id);
 		if (!record) throw new AcpSdkAdapterError("not_found", `Unknown session, not found: ${id}`);
-		const modelPreset = this.#startupOptions?.modelPreset;
-		const [config, sessionCatalog] = await Promise.all([
-			record.adapter.query("config.list/get"),
-			modelPreset === undefined
-				? collectModelCatalogAndActiveProviders(record.adapter)
-				: record.adapter
-						.query("models.profiles.list")
-						.then((profiles): { modelCatalog: unknown; activeProviders: undefined } => ({
-							modelCatalog: profiles,
-							activeProviders: undefined,
-						})),
-		]);
-		// The active-provider walk overlaps the catalog inside the batch above, but
-		// only after the first models.list/current page has finalized host-side
-		// credential state, so catalog rows and provider availability never mix
-		// pre- and post-refresh credential snapshots. Only an older session host
-		// that rejects `providers.list/active` with `operation_not_session_owned`
-		// falls back to the full catalog; operational failures fail closed so the
-		// active-provider contract is not silently widened.
+		const config = await record.adapter.query("config.list/get");
+		const modelPreset = this.#startupOptions?.modelPreset ?? activeModelPresetFromConfig(config);
+		const sessionCatalog = await (modelPreset === undefined
+			? collectModelCatalogAndActiveProviders(record.adapter)
+			: record.adapter
+					.query("models.profiles.list")
+					.then((profiles): { modelCatalog: unknown; activeProviders: undefined } => ({
+						modelCatalog: profiles,
+						activeProviders: undefined,
+					})));
+		// Only an older session host that rejects `providers.list/active` with
+		// `operation_not_session_owned` falls back to the full catalog;
+		// operational failures fail closed so the active-provider contract is not
+		// silently widened.
 		const modelCatalog = sessionCatalog.modelCatalog;
 		const activeProviders = sessionCatalog.activeProviders;
 		record.authFailure = undefined;
@@ -3787,6 +4237,10 @@ export class AcpAgent implements Agent {
 					);
 				}
 				const messageId = typeof message.id === "string" ? message.id : undefined;
+				// A replayed user turn is proof the loaded session already had a prompt, so the
+				// next live prompt is not its first — keep the first-turn readiness retry (issue
+				// #5574) off for a resumed/loaded session that has prior history.
+				if (message.role === "user") record.firstPromptDone = true;
 				const richContent = Array.isArray(message.content) ? message.content : undefined;
 				if ((message.role === "user" || message.role === "assistant") && richContent) {
 					for (const rawBlock of richContent) {