@gajae-code/coding-agent 0.17.2 → 0.17.4

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

@@ -60,7 +60,11 @@ import {
 	promptFailureRetryability,
 	rephaseFailedOutcome,
 } from "../../sdk/prompt-failure";
-import type { SdkPromptTerminalOutcome } from "../../sdk/prompt-status";
+import type {
+	SdkPromptFailureCategory,
+	SdkPromptFailurePhase,
+	SdkPromptTerminalOutcome,
+} from "../../sdk/prompt-status";
 import { PromptActivity, type PromptWatchdogClock, systemPromptWatchdogClock } from "../../sdk/prompt-watchdog";
 import { validateRequiredPromptText } from "../../sdk/protocol/adapter-validation";
 import { type SessionAttachment, SessionRouter, type SessionRouterFrame } from "../../sdk/router";
@@ -74,6 +78,7 @@ import {
 } from "./acp-event-mapper";
 import { resolveAcpPermissionMode } from "./permission-mode";
 import type { AcpStartupOptions } from "./startup-options";
+import { resolveStartupProvenance } from "./startup-provenance";
 import { ACP_TERMINAL_AUTH_FLAG } from "./terminal-auth";
 
 const ACP_DEFAULT_MODE_ID = "default";
@@ -159,6 +164,9 @@ const ACP_FIRST_PROMPT_RETRY_BASE_DELAY_MS = 250;
 type JsonObject = Record<string, unknown>;
 interface PromptWaiter {
 	acknowledged: boolean;
+	invocationKind: "prompt" | "skill";
+	/** ACP-owned identity, never inherited from caller metadata or reused for replay. */
+	clientRef: string;
 	/** True once turn.prompt / skill.invoke has been sent; cancel must not fake-settle after this. */
 	dispatched: boolean;
 	/** True only while the dispatched control request can still reveal its correlation. */
@@ -253,6 +261,8 @@ type SessionRecord = {
 	/** Replayable startup notice captured before ACP bootstrap; emitted once after the session id is known. */
 	routingInactiveNotice?: string;
 	activePrompt?: PromptWaiter;
+	/** One bounded read-only recovery owner for this attachment and waiter. */
+	statusRecovery?: 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. */
@@ -640,6 +650,46 @@ export class AcpPromptFailureError extends AcpSdkAdapterError {
 	}
 }
 
+/**
+ * Recover the shared prompt-failure projection for a direct SDK rejection.
+ *
+ * A terminal frame normally reaches {@link AcpPromptFailureError} through
+ * `#settlePrompt`, but a host may reject the `turn.prompt` control request
+ * itself with `code: "prompt_failed"`. That path never has a terminal outcome
+ * to retain, so translating the raw adapter error used to bypass
+ * `promptFailureWireData` and publish only the bare `code`/`details` pair.
+ * Keep the fallback deliberately narrow: only the two prompt terminal codes
+ * are upgraded, and any optional provider classifier is re-validated before
+ * it enters the existing classifier/projection seam.
+ */
+function promptFailureFromDirectError(error: unknown): SdkPromptFailedOutcome | undefined {
+	if (error instanceof AcpPromptFailureError) return error.failure;
+	let code: unknown;
+	let providerCode: unknown;
+	let phase: unknown;
+	try {
+		const candidate = error as {
+			code?: unknown;
+			providerCode?: unknown;
+			transportFailure?: { providerCode?: unknown };
+			phase?: unknown;
+		};
+		code = candidate?.code;
+		providerCode = candidate?.providerCode ?? candidate?.transportFailure?.providerCode;
+		phase = candidate?.phase;
+	} catch {
+		return undefined;
+	}
+	if (code !== "prompt_failed" && code !== "prompt_deadline_exceeded") return undefined;
+	return failedPromptOutcome({
+		code,
+		provenance: code === "prompt_deadline_exceeded" ? "deadline" : "agent_failed",
+		...(isSafePromptFailureCode(providerCode) ? { providerCode } : {}),
+		...(isSdkPromptFailurePhase(phase) ? { phase } : {}),
+		evidence: {},
+	});
+}
+
 /**
  * The wire projection of a prompt terminal's classification (issue #5615).
  *
@@ -655,12 +705,71 @@ export class AcpPromptFailureError extends AcpSdkAdapterError {
  * dropped instead of becoming a leak of provider text (the redaction contract in
  * `sanitizePromptFailure`). A dropped or absent code is omitted, never nulled.
  */
+export const OPERATOR_UPSTREAM_LABEL = "Upstream provider failure";
+export const OPERATOR_UPSTREAM_SUFFIX = ": the model provider ended this turn.";
+/**
+ * `post_start` proves execution began, so tools may already have run and had effects before the
+ * provider died. The wording therefore qualifies the turn rather than absolving the task: saying
+ * the task was unaffected would assert something the bounded classifiers do not establish.
+ */
+export const OPERATOR_PARTIAL_WORK_NOTE =
+	" Work this turn had already performed may have taken effect; check before retrying.";
+
+/**
+ * Operator-facing wording for a post-start terminal, assembled ONLY from bounded safe tokens: the
+ * classifier `phase`, the `category`, and a `providerCode` that passes `isSafePromptFailureCode`.
+ * Raw provider text never reaches this function and must never reach it.
+ *
+ * Gated on BOTH `phase === "post_start"` and `category === "provider_transport"`. A submission-phase
+ * provider failure is rejected by the phase gate: nothing executed, so wording about a turn the
+ * provider ended would describe an event that never occurred.
+ *
+ * It claims only what those tokens prove — that the upstream provider ended the turn — and says
+ * nothing about whether the operator's work survived. `post_start` proves execution began, so the
+ * wording qualifies that earlier work may already have taken effect instead of absolving the task.
+ *
+ * This is additive. The wire `code`/`details` pair and every `PROMPT_FAILURE_MESSAGE_*` constant
+ * stay exactly as they are — pinned ACP core-v1 conformance asserts on them — so this wording
+ * travels alongside the redacted message instead of repurposing it.
+ *
+ * It says NOTHING about the worktree, deliberately. Nothing on this path inspects the worktree, so
+ * any sentence about uncommitted work would assert a check that never ran — reporting an
+ * uninspected tree as clean is the absence-of-evidence-as-evidence-of-absence error, and an
+ * operator who believed it would sweep work away. Silence is the only honest option until something
+ * actually looks.
+ *
+ * Returns `undefined` for every other category: `phase` and `category` are already on the wire, so
+ * restating them in prose tells an operator nothing they do not already have.
+ */
+export function postStartOperatorMessage(input: {
+	phase: SdkPromptFailurePhase;
+	category: SdkPromptFailureCategory;
+	providerCode?: string;
+}): string | undefined {
+	// Phase first: a submission-phase provider failure never started executing, so wording about a
+	// turn that ended mid-flight would describe something that did not happen. `phase` is a bounded
+	// classifier already on the wire, so gating on it widens nothing.
+	if (input.phase !== "post_start") return undefined;
+	if (input.category !== "provider_transport") return undefined;
+	const code = isSafePromptFailureCode(input.providerCode) ? ` (${input.providerCode})` : "";
+	return `${OPERATOR_UPSTREAM_LABEL}${code}${OPERATOR_UPSTREAM_SUFFIX}${OPERATOR_PARTIAL_WORK_NOTE}`;
+}
+
 function promptFailureWireData(failure: SdkPromptFailedOutcome): Record<string, string> {
+	// `operatorMessage` says, in words, what the classifier tokens already say in codes: that the
+	// cause was an upstream provider problem rather than a failure of the operator's task. Built
+	// only from those same bounded tokens, so it widens nothing that reaches the wire.
+	const operatorMessage = postStartOperatorMessage({
+		phase: failure.phase,
+		category: failure.category,
+		...(failure.providerCode === undefined ? {} : { providerCode: failure.providerCode }),
+	});
 	return {
 		phase: failure.phase,
 		category: failure.category,
 		retryability: promptFailureRetryability(failure.category),
 		...(isSafePromptFailureCode(failure.providerCode) ? { providerCode: failure.providerCode } : {}),
+		...(operatorMessage === undefined ? {} : { operatorMessage }),
 	};
 }
 
@@ -1366,9 +1475,10 @@ export function acpRequestFailure(error: unknown): unknown {
 	// 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:
 	// this enriches `data`, it does not restate the redacted message.
+	const promptFailure = promptFailureFromDirectError(error);
 	const data =
-		error instanceof AcpPromptFailureError
-			? { code, details: message, ...promptFailureWireData(error.failure) }
+		promptFailure !== undefined
+			? { code, details: message, ...promptFailureWireData(promptFailure) }
 			: { code, 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
@@ -1510,7 +1620,7 @@ export class AcpAgent implements Agent {
 	/** Retain settled prompt identities across automatic transport reattachment. */
 	readonly #retiredPromptCorrelations = new Map<string, PromptCorrelation[]>();
 	/** Prevent a successor admission while a retired prompt can still reveal its identity. */
-	readonly #retiredPromptAcknowledgements = new Set<string>();
+	readonly #retiredPromptAcknowledgements = new Map<string, PromptWaiter>();
 	/** Ready terminal metadata writes retain ownership across same-id record replacement. */
 	readonly #terminalMetadataTails = new Map<string, Promise<void>>();
 	/** Unstreamed terminal text retains transcript ownership across same-id replacement. */
@@ -2112,6 +2222,7 @@ export class AcpAgent implements Agent {
 
 		const payload = acpPromptPayload(params.prompt);
 		const skillInvocation = acpSkillInvocation(params.prompt);
+		const clientRef = randomUUID();
 		if (!skillInvocation) {
 			const promptError = validateRequiredPromptText("turn.prompt", {
 				text: payload.text,
@@ -2146,7 +2257,7 @@ export class AcpAgent implements Agent {
 			JSON.stringify({
 				type: "control_request",
 				operation: skillInvocation ? "skill.invoke" : "turn.prompt",
-				input: skillInvocation ?? { text: payload.text, images: payload.images },
+				input: { ...(skillInvocation ?? { text: payload.text, images: payload.images }), clientRef },
 				// AcpSdkAdapter.control passes `confirm: false` to SdkClient, which serializes
 				// the field even though it is not part of the skill input payload.
 				...(skillInvocation ? { confirm: false } : {}),
@@ -2168,6 +2279,8 @@ export class AcpAgent implements Agent {
 		record.promptObservedAssistantOutput = false;
 		const { promise: response, resolve, reject } = Promise.withResolvers<PromptResponse>();
 		const waiter: PromptWaiter = {
+			invocationKind: skillInvocation ? "skill" : "prompt",
+			clientRef,
 			acknowledged: false,
 			dispatched: false,
 			acknowledgementPending: false,
@@ -2212,11 +2325,11 @@ export class AcpAgent implements Agent {
 		} catch (error) {
 			waiter.awaitingProviderPreflight = false;
 			if (waiter.settled || record.activePrompt !== waiter) {
-				this.#retiredPromptAcknowledgements.delete(params.sessionId);
+				this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 				return await response;
 			}
 			if (record.cancelRequested && waiter.cancelAcknowledged) {
-				this.#retiredPromptAcknowledgements.delete(params.sessionId);
+				this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 				await this.#settleCancelledPrompt(params.sessionId, record, waiter);
 				return await response;
 			}
@@ -2224,18 +2337,22 @@ export class AcpAgent implements Agent {
 				record.activePrompt = undefined;
 				record.busy = record.backgroundBusy;
 				clearPromptWatchdog(waiter);
-				this.#retiredPromptAcknowledgements.delete(params.sessionId);
+				// #5526's guarded release replaces the unguarded delete: it only clears
+				// the entry when it still belongs to THIS waiter, so a successor's
+				// acknowledgement is never dropped. Strictly narrower than the delete
+				// it supersedes; dev's watchdog clear above is unaffected.
+				this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 				void this.#publishPromptPhaseIdle(params.sessionId, record.adapter);
 			}
 			throw error;
 		}
 		waiter.awaitingProviderPreflight = false;
 		if (waiter.settled || record.activePrompt !== waiter) {
-			this.#retiredPromptAcknowledgements.delete(params.sessionId);
+			this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 			return await response;
 		}
 		if (record.cancelRequested && waiter.cancelAcknowledged) {
-			this.#retiredPromptAcknowledgements.delete(params.sessionId);
+			this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
 			await this.#settleCancelledPrompt(params.sessionId, record, waiter);
 			return await response;
 		}
@@ -2278,14 +2395,18 @@ export class AcpAgent implements Agent {
 		}
 
 		waiter.acknowledgementPending = true;
+		const promptAdapter = record.adapter;
 		const acknowledgementTask = (async (): Promise<PromptResponse> => {
 			if (waiter.settled || record.activePrompt !== waiter) return await response;
 			const acknowledgement = skillInvocation
-				? await record.adapter.control("skill.invoke", skillInvocation)
-				: await record.adapter.prompt({
+				? await promptAdapter.control("skill.invoke", { ...skillInvocation, clientRef })
+				: await promptAdapter.prompt({
 						text: payload.text,
+						clientRef,
 						...(payload.images.length ? { images: payload.images } : {}),
 					});
+			// A recovered waiter already owns its exact identity; a late ack cannot rebind it.
+			if (waiter.settled && waiter.acknowledged) return await response;
 
 			const acknowledgementCorrelation = promptAcknowledgement(acknowledgement);
 			if (!acknowledgementCorrelation)
@@ -2293,6 +2414,14 @@ export class AcpAgent implements Agent {
 					"invalid_prompt_acknowledgement",
 					"SDK prompt acknowledgement must accept the prompt and include commandId and turnId.",
 				);
+			if (
+				this.#sessions.get(params.sessionId) !== record ||
+				record.adapter !== promptAdapter ||
+				record.activePrompt !== waiter
+			) {
+				this.#rememberSettledPromptCorrelation(params.sessionId, record, acknowledgementCorrelation);
+				return await response;
+			}
 			if (this.#hasRetiredPromptCorrelation(params.sessionId, record, acknowledgementCorrelation)) {
 				try {
 					const abortAcknowledgement = await record.adapter.cancel("turn");
@@ -2427,10 +2556,20 @@ export class AcpAgent implements Agent {
 			}
 			this.#settlePrompt(params.sessionId, record, waiter);
 			return await response;
-		})().finally(() => {
-			waiter.acknowledgementPending = false;
-			this.#retiredPromptAcknowledgements.delete(params.sessionId);
-		});
+		})()
+			.catch(async error => {
+				if (
+					!(error instanceof SdkClientError || error instanceof AcpSdkAdapterError) ||
+					error.code !== "uncertain_after_send"
+				)
+					throw error;
+				if (record.adapter === promptAdapter) this.#startUncertainPromptRecovery(params.sessionId, record, waiter);
+				return await response;
+			})
+			.finally(() => {
+				waiter.acknowledgementPending = false;
+				this.#releaseRetiredPromptAcknowledgement(params.sessionId, waiter);
+			});
 		// Settlement can win before the SDK answers `turn.prompt`; acknowledgement processing
 		// must remain alive to tombstone its eventual correlation without holding the ACP caller.
 		void acknowledgementTask.catch(() => undefined);
@@ -2889,24 +3028,23 @@ export class AcpAgent implements Agent {
 			// a broker-launched SDK host keeps ACP ownership across reconnects.
 			await adapter.start({ activateProviders: false });
 			let capabilities: JsonObject | undefined;
+			// A query that never answered and a host that answered without provenance are
+			// different operator problems, so the failure is retained instead of discarded.
+			let capabilitiesFailure: unknown;
 			try {
 				const response = object(await adapter.query("runtime.capabilities"));
 				const result = object(response?.result) ?? response;
 				// Q18 is a paged query surface: the capability object arrives as the single
 				// page item, so fall back to the envelope only for direct-result hosts.
 				capabilities = object(pageItems(result)[0]) ?? result;
-			} catch {}
-			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 with startup control provenance; restart the session.",
-				);
+			} catch (error) {
+				capabilitiesFailure = error;
+			}
+			const primaryControlSurface = resolveStartupProvenance({
+				sessionId: id,
+				capabilities,
+				queryFailure: capabilitiesFailure,
+			});
 			if (primaryControlSurface === "sdk") {
 				adapter.authorizeProviderActivation();
 				await adapter.ensureProviders();
@@ -3017,7 +3155,11 @@ export class AcpAgent implements Agent {
 
 	#fenceRetiredPromptAcknowledgement(id: string, waiter: PromptWaiter): void {
 		if (waiter.dispatched && waiter.acknowledgementPending && !waiter.acknowledged)
-			this.#retiredPromptAcknowledgements.add(id);
+			this.#retiredPromptAcknowledgements.set(id, waiter);
+	}
+
+	#releaseRetiredPromptAcknowledgement(id: string, waiter: PromptWaiter): void {
+		if (this.#retiredPromptAcknowledgements.get(id) === waiter) this.#retiredPromptAcknowledgements.delete(id);
 	}
 
 	#advanceTerminalGeneration(record: SessionRecord): void {
@@ -3027,6 +3169,15 @@ export class AcpAgent implements Agent {
 	#recoverSessionAfterTransportFailure(id: string, adapter: AcpSdkAdapter, error: Error): void {
 		const record = this.#sessions.get(id);
 		if (!record || record.adapter !== adapter) return;
+		if (error instanceof SdkClientError && error.code === "uncertain_after_send") {
+			// Provider-registration requests share this transport error. Recover only when the
+			// prompt's own dispatched acknowledgement is still pending; an acknowledged turn
+			// must continue until its terminal frame arrives.
+			const waiter = record.activePrompt;
+			if (waiter?.dispatched && waiter.acknowledgementPending && !waiter.acknowledged)
+				this.#startUncertainPromptRecovery(id, record, waiter);
+			return;
+		}
 		if (
 			error instanceof SdkClientError &&
 			error.code !== "reconnect_exhausted" &&
@@ -3041,11 +3192,191 @@ export class AcpAgent implements Agent {
 			logger.warn(`ACP session ${id} non-transport error reached reconnect handler; ignoring terminal recovery.`);
 			return;
 		}
+		const waiter = record.activePrompt;
+		if (waiter?.dispatched) {
+			// A prior uncertainty notification already owns recovery for this waiter. Keep
+			// the in-flight lookup alive; only declined, non-recovering waiters fall through
+			// to the ordinary transport-loss teardown and reattachment path.
+			if (record.statusRecovery === waiter || this.#startUncertainPromptRecovery(id, record, waiter)) return;
+		}
 		const detail = error.message || "SDK transport reconnect failed.";
 		const terminal = new AcpSdkAdapterError("connection_closed", `ACP session transport was lost: ${detail}`);
 		void this.#recoverSessionAfterTransportFailureAsync(id, adapter, record.cwd, terminal);
 	}
 
+	#startUncertainPromptRecovery(id: string, record: SessionRecord, waiter: PromptWaiter): boolean {
+		if (
+			this.#sessions.get(id) !== record ||
+			promptWaiterRetired(record, waiter) ||
+			!waiter.dispatched ||
+			waiter.terminalReserved ||
+			record.statusRecovery === waiter
+		)
+			return false;
+		record.statusRecovery = waiter;
+		clearPromptWatchdog(waiter);
+		void this.#recoverUncertainPrompt(id, record, record.adapter, waiter);
+		return true;
+	}
+
+	async #recoverUncertainPrompt(
+		id: string,
+		record: SessionRecord,
+		adapter: AcpSdkAdapter,
+		waiter: PromptWaiter,
+	): Promise<void> {
+		const ownsRecovery = (): boolean =>
+			this.#sessions.get(id) === record &&
+			record.adapter === adapter &&
+			record.statusRecovery === waiter &&
+			!promptWaiterRetired(record, waiter) &&
+			!waiter.terminalReserved;
+		// Keep the lookup selector's authority even if an ack arrives during the read.
+		const acknowledgedAtLookup = waiter.acknowledged;
+		let detail = "status query unavailable";
+		let timer: NodeJS.Timeout | undefined;
+		let timedOut = false;
+		try {
+			const deadline = Promise.withResolvers<never>();
+			timer = setTimeout(() => {
+				timedOut = true;
+				deadline.reject(new Error("status query timeout"));
+			}, 5_000);
+			const refreshAttachment = async (): Promise<void> => {
+				if (this.#sessions.get(id) !== record || record.adapter !== adapter) return;
+				// A reconnect can revoke the adapter's opaque attachment before Router has
+				// published its replacement. Force an authority pass first, then hand the
+				// exact current capability back to the adapter before issuing the read-only
+				// lookup. This pass does not replay the prompt mutation.
+				await this.#router.reconcile({ waitForReplay: false });
+				if (!ownsRecovery()) return;
+				const refreshed = this.#router.attachment(id);
+				if (!refreshed?.isCurrent())
+					throw new AcpSdkAdapterError(
+						"unavailable",
+						"ACP session has no current Router attachment for recovery.",
+					);
+				if (refreshed !== record.attachment || !record.attachment.isCurrent()) {
+					await adapter.attachmentReady(refreshed);
+					record.attachment = refreshed;
+				}
+			};
+			await Promise.race([refreshAttachment(), deadline.promise]);
+			if (!ownsRecovery()) return;
+			// Bound observation only: the mutation and the read are never replayed or aborted.
+			const response = object(
+				await Promise.race([
+					adapter.query("turn.result", {
+						kind: waiter.invocationKind,
+						...(acknowledgedAtLookup ? waiter.correlation : { clientRef: waiter.clientRef }),
+					}),
+					deadline.promise,
+				]),
+			);
+			if (!ownsRecovery()) return;
+			const status = object(response?.result) ?? response;
+			const correlation = strictCorrelationFrom(response, status);
+			const outcome = status ? terminalOutcome(status) : undefined;
+			const content = object(status?.content);
+			const readableText =
+				content?.version === 1 &&
+				content.type === "text" &&
+				typeof content.text === "string" &&
+				content.text.trim().length > 0;
+			const failure = object(status?.error);
+			const conflictingIdentity = [response, status].some(
+				value =>
+					(value?.kind !== undefined && value.kind !== waiter.invocationKind) ||
+					(value?.sessionId !== undefined && value.sessionId !== id) ||
+					(value?.clientRef !== undefined && value.clientRef !== waiter.clientRef),
+			);
+			if (
+				status?.kind !== waiter.invocationKind ||
+				conflictingIdentity ||
+				(!acknowledgedAtLookup && status.clientRef !== waiter.clientRef) ||
+				!correlation ||
+				!hasCompleteCorrelation(correlation) ||
+				(waiter.acknowledged && !correlationsExactlyMatch(waiter.correlation, correlation)) ||
+				this.#hasRetiredPromptCorrelation(id, record, correlation)
+			) {
+				detail = "status correlation is missing, retired, or mismatched";
+			} else if (
+				status.status === "failed" &&
+				status.outcome === undefined &&
+				(status.receiptState === "present" ||
+					status.receiptState === "missing" ||
+					status.receiptState === "unknown") &&
+				typeof failure?.code === "string" &&
+				/^[a-zA-Z0-9_.-]{1,64}$/.test(failure.code) &&
+				typeof failure.message === "string" &&
+				failure.message.trim().length > 0 &&
+				failure.message.length <= 512
+			) {
+				waiter.correlation = correlation;
+				waiter.acknowledged = true;
+				record.busy = record.backgroundBusy;
+				this.#advanceTerminalGeneration(record);
+				void this.#rejectPrompt(record, id, waiter, new AcpSdkAdapterError(failure.code, failure.message));
+				return;
+			} else if (
+				(status.status === "terminal_ok" &&
+					outcome?.kind === "stopped" &&
+					(status.receiptState === "present" || status.receiptState === "missing") &&
+					(outcome.reason !== "end_turn" || (status.receiptState === "present" && readableText))) ||
+				(status.status === "failed" &&
+					outcome?.kind === "failed" &&
+					(status.receiptState === "present" ||
+						status.receiptState === "missing" ||
+						status.receiptState === "unknown"))
+			) {
+				waiter.correlation = correlation;
+				waiter.acknowledged = true;
+				record.busy = record.backgroundBusy;
+				this.#advanceTerminalGeneration(record);
+				const settledOutcome =
+					record.cancelRequested && outcome.kind === "stopped" && outcome.reason === "end_turn"
+						? { ...outcome, reason: "cancelled" as const, provenance: "client_cancel" as const }
+						: outcome;
+				const publicationBarrier = record.frameTail;
+				waiter.terminal = { outcome: settledOutcome, correlation };
+				// Recovered final text is published on the async terminal tail below. Record it
+				// before settling so a first-turn startup-readiness failure cannot be retried
+				// after this retained answer has already been committed for publication.
+				if (readableText) record.promptObservedAssistantOutput = true;
+				this.#settlePrompt(id, record, waiter);
+				this.#scheduleTerminalUpdates(
+					id,
+					adapter,
+					record.publicationGeneration,
+					{
+						type: settledOutcome.kind === "failed" ? "agent_failed" : "agent_end",
+						outcome: settledOutcome,
+						finalText: readableText ? content.text : undefined,
+						finalTextTruncated: content?.truncated === true,
+					},
+					waiter,
+					publicationBarrier,
+				);
+				return;
+			} else {
+				detail = "status has no usable retained terminal outcome and receipt";
+			}
+		} catch {
+			detail = timedOut ? "status query timed out after 5000ms" : "status query unavailable";
+		} finally {
+			if (timer !== undefined) clearTimeout(timer);
+		}
+		if (!ownsRecovery()) return;
+		await this.#failSession(
+			id,
+			adapter,
+			new AcpSdkAdapterError(
+				"terminal_uncertain",
+				`ACP prompt outcome remains uncertain: ${detail}. No mutation was replayed. Inspect turn.result for kind=${waiter.invocationKind}, clientRef=${waiter.clientRef}, commandId=${waiter.correlation.commandId ?? "unknown"}, turnId=${waiter.correlation.turnId ?? "unknown"} before submitting more work.`,
+			),
+		);
+	}
+
 	async #recoverSessionAfterTransportFailureAsync(
 		id: string,
 		adapter: AcpSdkAdapter,
@@ -3093,13 +3424,15 @@ export class AcpAgent implements Agent {
 			if (attaching) await Promise.allSettled([attaching.task]);
 			// 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));
+			const closesHost = this.#ownedSessionIds.has(id);
+			await this.#teardownSession(id, "closed", closesHost);
 			this.#knownSessionCwds.delete(id);
 			this.#ownedSessionIds.delete(id);
 			this.#knownSessionMcpServers.delete(id);
 			this.#knownSessionMetadata.delete(id);
 			this.#retiredPromptCorrelations.delete(id);
-			this.#retiredPromptAcknowledgements.delete(id);
+			// Detaching locally cannot retire an outstanding host acknowledgement.
+			if (closesHost) this.#retiredPromptAcknowledgements.delete(id);
 			return {};
 		} finally {
 			this.#finishTeardown(id);
@@ -3337,7 +3670,7 @@ export class AcpAgent implements Agent {
 	 * running forever behind a dead session.
 	 */
 	#armPromptWatchdog(id: string, record: SessionRecord, waiter: PromptWaiter): void {
-		if (waiter.settled) return;
+		if (waiter.settled || record.statusRecovery === waiter) return;
 		waiter.cancelWatchdog?.();
 		// No frame can still arrive once the transport is known to be gone, so waiting out
 		// the full bound would only add dead time to an outcome that is already decided.
@@ -3400,7 +3733,13 @@ export class AcpAgent implements Agent {
 	 * turn can no longer be observed, it does not cancel or tear down the session.
 	 */
 	async #expirePromptWatchdog(id: string, record: SessionRecord, waiter: PromptWaiter): Promise<void> {
-		if (record.activePrompt !== waiter || waiter.settled || waiter.terminalReserved) return;
+		if (
+			record.activePrompt !== waiter ||
+			waiter.settled ||
+			waiter.terminalReserved ||
+			record.statusRecovery === waiter
+		)
+			return;
 		const silenceMs = Math.max(0, this.#promptWatchdogClock.now() - waiter.lastFrameAt);
 		// A prompt still in preflight has never reached the host, so "stopped producing frames"
 		// would point the reader at the wrong phase: nothing was ever dispatched to produce them.
@@ -3506,6 +3845,18 @@ export class AcpAgent implements Agent {
 						await this.#settleCancelledPrompt(id, record, waiter);
 						return;
 					}
+					if (waiter.terminalReserved) return;
+					if (record.statusRecovery === waiter || (waiter.dispatched && !waiter.acknowledged)) {
+						await this.#failSession(
+							id,
+							adapter,
+							new AcpSdkAdapterError(
+								"terminal_uncertain",
+								`Prompt owner connection changed before retained evidence was resolved. No mutation was replayed. Inspect turn.result for kind=${waiter.invocationKind}, clientRef=${waiter.clientRef}.`,
+							),
+						);
+						return;
+					}
 					record.activePrompt = undefined;
 					record.busy = record.backgroundBusy;
 					clearPromptWatchdog(waiter);
@@ -3796,13 +4147,15 @@ export class AcpAgent implements Agent {
 		publicationGeneration: number,
 		event: JsonObject,
 		promptOwner: PromptWaiter | undefined,
+		publicationBarrier?: Promise<void>,
 	): void {
 		const failedTerminal = event.type === "agent_failed";
 		if (promptOwner) this.#flushFailureDiagnostics(id, promptOwner, adapter);
-		let decorationStart = Promise.resolve();
+		let decorationStart = publicationBarrier ?? Promise.resolve();
 		const finalText = typeof event.finalText === "string" ? event.finalText : "";
 		if (promptOwner && hasAcpFinalTextContent(finalText)) {
 			const finalTextTask = (async () => {
+				if (publicationBarrier) await publicationBarrier;
 				await Bun.sleep(0);
 				const resolution = resolveAcpFinalText(promptOwner.emittedAssistantText, finalText);
 				if (resolution.kind === "emit") {
@@ -3814,7 +4167,9 @@ export class AcpAgent implements Agent {
 							update: {
 								sessionUpdate: "agent_message_chunk",
 								content: { type: "text", text: resolution.text },
-								...(resolution.final.truncated ? { _meta: { gjcFinalTextTruncated: true } } : {}),
+								...(resolution.final.truncated || event.finalTextTruncated === true
+									? { _meta: { gjcFinalTextTruncated: true } }
+									: {}),
 							},
 						},
 						adapter,
@@ -3829,6 +4184,24 @@ export class AcpAgent implements Agent {
 						finalLength: resolution.final.text.length,
 					});
 				}
+				if (resolution.kind !== "emit" && event.finalTextTruncated === true) {
+					// A retained prefix may already equal the streamed text, leaving no suffix for
+					// `resolveAcpFinalText` to emit. Still publish a metadata-only chunk so the
+					// caller can distinguish an incomplete retained result from a complete answer.
+					await this.#publishSessionUpdate(
+						id,
+						{
+							sessionId: id,
+							update: {
+								sessionUpdate: "agent_message_chunk",
+								content: { type: "text", text: "" },
+								_meta: { gjcFinalTextTruncated: true },
+							},
+						},
+						adapter,
+						publicationGeneration,
+					);
+				}
 			})();
 			let finalTextTail: Promise<void>;
 			finalTextTail = finalTextTask