@gajae-code/coding-agent 0.17.1 → 0.17.4

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

@@ -46,15 +46,25 @@ import {
 	AcpSdkAdapterError,
 	acpMcpLaunchFailure,
 } from "../../sdk/acp";
-import { resolveAcpFinalText } from "../../sdk/acp/final-text";
+import { hasAcpFinalTextContent, resolveAcpFinalText } from "../../sdk/acp/final-text";
 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 {
+	failedPromptOutcome,
+	isSafePromptFailureCode,
+	isSdkPromptFailurePhase,
+	promptFailureRetryability,
+	rephaseFailedOutcome,
+} from "../../sdk/prompt-failure";
+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";
@@ -68,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";
@@ -153,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. */
@@ -177,6 +191,8 @@ interface PromptWaiter {
 	lastFrameAt: number;
 	/** Type of that prompt-owned frame, reported when the watchdog expires. */
 	lastFrameType: string;
+	/** True while the prompt is blocked in provider preflight, before the turn is dispatched. */
+	awaitingProviderPreflight: boolean;
 	/** Cancels the armed inactivity watchdog; re-armed by prompt-owned frames. */
 	cancelWatchdog?: () => void;
 	/** What the host is observably doing — a tool running, a model call unanswered — and the bound that follows from it. */
@@ -185,6 +201,12 @@ interface PromptWaiter {
 	observedTurnActivity: boolean;
 	/** True once a prompt-owned tool execution frame was observed; vetoes a first-turn retry that would re-run it. */
 	observedToolExecution: boolean;
+	/**
+	 * Newest `plan` update published for this prompt, retained so an abandoned turn can report
+	 * what it had left to do (issue #5669). Absent means no plan was ever observed, which is
+	 * evidence of nothing — distinct from an observed plan whose entries are all `completed`.
+	 */
+	planSnapshot?: AcpPlanSnapshot;
 	/** Coordinates a prompt-control rejection racing an acknowledged ACP cancellation. */
 	cancelAttempt?: Promise<boolean>;
 	/** Whether ANY overlapping cancel attempt for this prompt was acknowledged:
@@ -239,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. */
@@ -618,7 +642,7 @@ type SdkPromptFailedOutcome = Extract<SdkPromptTerminalOutcome, { kind: "failed"
  * category — so settlement carries that classification instead of discarding it into a bare
  * `AcpSdkAdapterError` (review P1, issue #5574).
  */
-class AcpPromptFailureError extends AcpSdkAdapterError {
+export class AcpPromptFailureError extends AcpSdkAdapterError {
 	readonly failure: SdkPromptFailedOutcome;
 	constructor(failure: SdkPromptFailedOutcome) {
 		super(failure.code, failure.message);
@@ -626,6 +650,202 @@ 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).
+ *
+ * `super(failure.code, failure.message)` above narrows the error to the generic
+ * `prompt_failed` plus its fixed redacted message, so the classification the
+ * terminal already computed used to die at the JSON-RPC boundary: an ACP client
+ * saw only `-32603 {code, details}` and could not tell a transient provider blip
+ * from a dead session without parsing English. These fields carry it across.
+ *
+ * `providerCode` is re-checked against the safe-token rule rather than trusted:
+ * `terminalOutcome` accepts the host's `providerCode` on a `typeof` check alone,
+ * and this is the first path that puts it on the wire, so an unbounded value is
+ * 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 }),
+	};
+}
+
+/**
+ * What an ACP `plan` update said the turn intended to do. Structural rather than the SDK's
+ * `PlanEntry` so only the fields this evidence reads are depended on.
+ */
+type AcpPlanSnapshot = Array<{
+	content: string;
+	status: "pending" | "in_progress" | "completed";
+	_meta?: { gjcTodoStatus?: unknown } | null;
+}>;
+
+/**
+ * An abandoned prompt that still carries the plan its turn was working through (issue #5669).
+ *
+ * The watchdog settles a prompt whose host stopped producing frames, and that rejection used to
+ * be a bare `AcpSdkAdapterError`: `{code, details}` and nothing else. A wrapper could not tell
+ * "the agent finished" from "the agent stopped with work left", so an abandoned turn's unverified
+ * diff was published as if it were complete. The last observed plan is the evidence that settles
+ * that question, so settlement carries it instead of dropping it at the JSON-RPC boundary.
+ */
+export class AcpPromptAbandonedError extends AcpSdkAdapterError {
+	readonly plan: AcpPlanSnapshot | undefined;
+	constructor(code: string, message: string, plan: AcpPlanSnapshot | undefined) {
+		super(code, message);
+		this.plan = plan;
+	}
+}
+
+/** Most pending plan entries that may reach the wire. */
+const ACP_ABANDON_PLAN_MAX_ENTRIES = 10;
+/** Longest one pending entry's text may be on the wire. */
+const ACP_ABANDON_PLAN_MAX_CONTENT_CHARS = 200;
+
+/**
+ * Whether a plan entry describes work the turn never finished (issue #5669).
+ *
+ * An entry whose ACP status is `completed` can still be unfinished: ACP's `PlanEntryStatus` has no
+ * `abandoned` member, so a task dropped via `/todo drop` is projected as `completed` for the
+ * client's plan UI while the mapper keeps the internal status in `_meta.gjcTodoStatus`. Completion
+ * evidence has to read that internal truth — reading the wire status alone would report a plan of
+ * nothing but dropped tasks as a finished turn. `_meta` crosses a JSON boundary, so the internal
+ * status is compared as `unknown` rather than asserted into a type.
+ */
+function planEntryUnfinished(entry: AcpPlanSnapshot[number]): boolean {
+	return entry.status !== "completed" || entry._meta?.gjcTodoStatus === "abandoned";
+}
+
+/**
+ * The wire projection of an abandoned prompt's plan (issue #5669).
+ *
+ * Plan text is model-authored, so it is bounded the same way `promptFailureWireData` bounds a
+ * provider classifier: a capped number of entries, each capped in length, and never restated in
+ * the human message. The counts are what a wrapper actually gates on; the contents are there so
+ * the reader can name the unfinished steps without a log dive.
+ *
+ * An absent plan yields no keys at all. "No plan was ever observed" is not the same claim as
+ * "the plan was complete", and a client must be able to tell them apart, so the fields are
+ * omitted rather than nulled or reported as unknown.
+ */
+function promptAbandonWireData(plan: AcpPlanSnapshot | undefined): Record<string, string> {
+	if (!plan) return {};
+	const pending = plan.filter(planEntryUnfinished);
+	return {
+		planIncomplete: pending.length > 0 ? "true" : "false",
+		planPendingCount: String(pending.length),
+		planTotalCount: String(plan.length),
+		planPending: JSON.stringify(
+			pending
+				.slice(0, ACP_ABANDON_PLAN_MAX_ENTRIES)
+				.map(entry => entry.content.slice(0, ACP_ABANDON_PLAN_MAX_CONTENT_CHARS)),
+		),
+	};
+}
+
 /**
  * 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
@@ -1251,9 +1471,22 @@ 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;
+	// 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:
+	// this enriches `data`, it does not restate the redacted message.
+	const promptFailure = promptFailureFromDirectError(error);
+	const data =
+		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
+	// that observed no plan adds no keys, so its payload stays byte-identical to before.
+	if (error instanceof AcpPromptAbandonedError) Object.assign(data, promptAbandonWireData(error.plan));
 	switch (code) {
 		case "authentication_failed":
-			return RequestError.authRequired({ code, details: message }, message);
+			return RequestError.authRequired(data, message);
 		// `not_found` stays -32603 with its discriminator in `data`: ACP's
 		// `resourceNotFound` (-32002) is a URI-addressed resource error, and an unknown
 		// session id is not a resource URI. Pinned ACP core-v1 conformance also requires
@@ -1261,12 +1494,15 @@ export function acpRequestFailure(error: unknown): unknown {
 		case "invalid_input":
 		case "unsupported":
 		case "unsupported_content":
-			return RequestError.invalidParams({ code, details: message }, message);
+			return RequestError.invalidParams(data, message);
 		default:
 			// The remaining internal codes (conflict, unavailable, busy, …) have no ACP
 			// counterpart and stay -32603. Keep the discriminator in `data` so a client can
-			// branch on retry/reconnect instead of parsing an English message.
-			return RequestError.internalError({ code, details: message }, message);
+			// branch on retry/reconnect instead of parsing an English message. `prompt_failed`
+			// and `prompt_deadline_exceeded` land here and keep -32603 by design: pinned ACP
+			// core-v1 conformance expects -32603/-32000 for this class, so the added
+			// classification travels in `data` rather than in a renumbered code.
+			return RequestError.internalError(data, message);
 	}
 }
 
@@ -1384,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. */
@@ -1986,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,
@@ -2020,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 } : {}),
@@ -2042,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,
@@ -2055,6 +2294,7 @@ export class AcpAgent implements Agent {
 			deferredActivityFrames: [],
 			lastFrameAt: this.#promptWatchdogClock.now(),
 			lastFrameType: "prompt_dispatch",
+			awaitingProviderPreflight: true,
 			activity: new PromptActivity(),
 			observedTurnActivity: false,
 			observedToolExecution: false,
@@ -2066,38 +2306,60 @@ export class AcpAgent implements Agent {
 		// pending. Retain the original promise for the caller, but mark that delayed rejection
 		// as observed until prompt() can resume and await it.
 		void response.catch(() => undefined);
+		// Silence has to be bounded from the moment the prompt owns the session: a host that
+		// dies before it ever answers is exactly the failure that leaves the client running.
+		// Provider preflight is part of that window — it awaits a lease the host may never win
+		// — so the bound is armed before it, not after (issue #5658). The arm below re-arms
+		// this same waiter once preflight clears, and #armPromptWatchdog cancels the previous
+		// timer first, so only one timer is ever live.
+		this.#armPromptWatchdog(params.sessionId, record, waiter);
+		// The watchdog settles `response`, not this await, so a preflight that never returns
+		// would pin session/prompt open with the caller's promise already rejected. Racing the
+		// settlement lets the re-checks below hand that rejection back to the caller.
+		const settlement = response.then(
+			() => undefined,
+			() => undefined,
+		);
 		try {
-			await record.adapter.ensureProviders();
+			await Promise.race([record.adapter.ensureProviders(), settlement]);
 		} 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;
 			}
 			if (record.activePrompt === waiter) {
 				record.activePrompt = undefined;
 				record.busy = record.backgroundBusy;
-				this.#retiredPromptAcknowledgements.delete(params.sessionId);
+				clearPromptWatchdog(waiter);
+				// #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;
 		}
 
-		// Silence has to be bounded from the moment the prompt owns the session: a host that
-		// dies before it ever answers is exactly the failure that leaves the client running.
+		// Re-arm now that preflight is behind us: the bound armed before it already covered
+		// this prompt's ownership window, and this call replaces that timer rather than
+		// racing it, so the dispatched turn gets the full inactivity bound of its own.
 		this.#armPromptWatchdog(params.sessionId, record, waiter);
 		// Echo the user's own message back as `user_message_chunk`. Clients render their
 		// transcript from session/update, so without this a prompt's text and any attached
@@ -2133,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)
@@ -2148,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");
@@ -2282,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);
@@ -2744,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();
@@ -2872,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 {
@@ -2882,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" &&
@@ -2896,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,
@@ -2948,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);
@@ -3192,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.
@@ -3255,17 +3733,40 @@ 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);
-		const cause = this.#promptTransportGone(id, record) ?? "the SDK session host stopped producing frames";
+		// 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.
+		const cause =
+			this.#promptTransportGone(id, record) ??
+			(waiter.awaitingProviderPreflight
+				? "the SDK session host never finished provider preflight"
+				: "the SDK session host stopped producing frames");
+		// Counts only: the plan's contents are model-authored and belong on the bounded wire
+		// projection, not in the log line (issue #5669).
+		const plan = waiter.planSnapshot;
 		logger.error("acp_prompt_watchdog_expired", {
 			sessionId: id,
 			cause,
 			silenceMs,
 			lastFrameType: waiter.lastFrameType,
+			awaitingProviderPreflight: waiter.awaitingProviderPreflight,
 			inactivityBoundMs: waiter.activity.inactivityBoundMs,
 			toolRunning: waiter.activity.running,
 			awaitingModel: waiter.activity.awaitingModel,
+			...(plan
+				? {
+						planIncomplete: plan.some(planEntryUnfinished),
+						planPendingCount: plan.filter(planEntryUnfinished).length,
+						planTotalCount: plan.length,
+					}
+				: {}),
 			...(waiter.correlation.commandId ? { commandId: waiter.correlation.commandId } : {}),
 			...(waiter.correlation.turnId ? { turnId: waiter.correlation.turnId } : {}),
 		});
@@ -3273,11 +3774,12 @@ export class AcpAgent implements Agent {
 			record,
 			id,
 			waiter,
-			new AcpSdkAdapterError(
+			new AcpPromptAbandonedError(
 				"prompt_abandoned",
 				`ACP prompt was abandoned after ${Math.round(silenceMs / 1_000)}s of silence: ${cause}. Last frame was ` +
 					`"${waiter.lastFrameType}" (${describeCorrelation(waiter.correlation)}). The turn was settled so the ` +
 					`client stops waiting; the session still accepts the next prompt.`,
+				plan,
 			),
 		);
 	}
@@ -3343,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);
@@ -3467,7 +3981,11 @@ export class AcpAgent implements Agent {
 			// 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;
+			// Whitespace-only final text carries no assistant content. `hasAcpFinalTextContent` is the
+			// single presence predicate shared with the terminal publication gate below, so a terminal
+			// this gate treats as "no output" can never publish a chunk alongside the retry's answer.
+			if (typeof event.finalText === "string" && hasAcpFinalTextContent(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.
@@ -3534,6 +4052,12 @@ export class AcpAgent implements Agent {
 				notification.update.content.type === "text"
 			)
 				promptOwner.emittedAssistantText += notification.update.content.text;
+			// The newest plan REPLACES the retained one: a plan update is the whole list, not a
+			// delta, so `todo_auto_clear`'s empty `entries` correctly leaves no pending work behind
+			// (issue #5669). Retained here rather than at frame ingress because this is where the
+			// mapper has already decided what the client is being told the plan is.
+			if (promptOwner && notification.update.sessionUpdate === "plan")
+				promptOwner.planSnapshot = notification.update.entries;
 			// 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).
@@ -3623,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 && 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") {
@@ -3641,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,
@@ -3656,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