@centerforagenticai/pi-multi-account 0.1.4 → 0.1.6

package/src/recovery-engine.ts

@@ -10,7 +10,9 @@ import {
 	createAcceptedOutputStream,
 	type AcceptedOutputErrorCode,
 } from "./recovery-output.js";
-import type { RecoveryCandidate } from "./recovery-plan.js";
+import type { RecoveryActionKind, RecoveryCandidate } from "./recovery-plan.js";
+import { classifyCodexRecoverySendEvidence } from "./recovery-send-evidence.js";
+import { isCanonicalManagedProviderId } from "./runtime-state.js";
 
 /** A request-owned timer. Cancelling it must prevent its callback from running. */
 export interface RecoveryTimer {
@@ -33,8 +35,22 @@ export type RecoveryPreDispatchDecision =
 
 export type RecoveryRetrySafety =
 	| {
-			readonly status: "retryable";
-			readonly reason: "generation-only-incomplete" | "definitively-rejected";
+			readonly status: "recoverable";
+			readonly action: "account";
+			readonly reason:
+				| "account-local-quota"
+				| "account-local-auth"
+				| "account-local-rate-limit"
+				/**
+				 * A network or transport failure, or a stall, before the attempt
+				 * produced any output. Only valid while nothing has been observed;
+				 * the engine converts it to `uncertain-external-effects` otherwise.
+				 */
+				| "pre-start-transient";
+	  }
+	| {
+			readonly status: "model-policy";
+			readonly reason: "structured-provider-error";
 	  }
 	| {
 			readonly status: "unsafe";
@@ -42,38 +58,40 @@ export type RecoveryRetrySafety =
 				| "uncertain-external-effects"
 				| "completed-tool"
 				| "completed-call"
-				| "agent-run";
+				| "agent-run"
+				| "invalid-request"
+				| "refusal"
+				| "unknown";
 	  };
 
+export type RecoveryModelDecision =
+	| {
+			readonly status: "recoverable";
+			readonly action: "model";
+			readonly reason: "unsupported-model" | "unsupported-capability";
+	  }
+	| { readonly status: "none" };
+
 /** Request options after recovery has replaced the provider's inner retry allowance. */
 export type RecoveryBoundStreamOptions = SimpleStreamOptions & {
 	readonly maxRetries: number;
 };
 
 /**
- * A pre-send reservation is an upper bound, not an observed charge count.
- *
- * `deliberate` is part of the type so future accounting cannot "tighten" the
- * reservation to an optimistic count. Adaptive Anthropic may use three SDK
- * sends under the provenance-locked adapter. A Codex WebSocket-capable request
- * may send three socket frames and then one SSE request. Recovery reserves all
- * sends that could be charged even though fewer (often one) normally occur.
+ * Every supported bounded provider invocation reserves one possibly charged
+ * send. Pinned Codex non-SSE transport can reconnect or fall back internally,
+ * and the vendored Google Antigravity stream ignores `maxRetries` and loops over
+ * empty-response retries, runtime-model candidates and endpoint fallbacks, so
+ * both counts are explicitly unknown and can never authorize another send.
  */
 export type RecoverySendReservation =
 	| {
 			readonly maximumPossiblyChargedSends: 1;
-			readonly overReservation: "none";
-			readonly basis: "bounded-http";
+			readonly basis: "bounded-provider-invocation";
 	  }
 	| {
-			readonly maximumPossiblyChargedSends: 3;
-			readonly overReservation: "deliberate";
-			readonly basis: "adaptive-anthropic-provenance";
-	  }
-	| {
-			readonly maximumPossiblyChargedSends: 4;
-			readonly overReservation: "deliberate";
-			readonly basis: "codex-websocket-uncertain";
+			readonly maximumPossiblyChargedSends: "unknown";
+			readonly basis: "codex-non-sse-unknown" | "antigravity-inner-unknown";
 	  };
 
 export interface RecoverySendReservationRequest {
@@ -90,18 +108,20 @@ export interface RecoverySendReservationRequest {
 export type RecoveryChargedSendExposure =
 	| {
 			readonly status: "bounded";
-			readonly maximumPossiblyChargedSends: 1 | 3;
+			readonly maximumPossiblyChargedSends: 1;
 	  }
 	| {
 			readonly status: "unknown";
-			readonly reason: "codex-websocket-send";
+			readonly reason: "codex-non-sse-send-count" | "antigravity-inner-sends";
 	  };
 
 /**
  * One supported provider invocation. `retrySafety` must classify the final
  * outbound payload after caller payload replacement and every provider callback.
- * Recovery independently overrides that classification for WebSocket-capable
- * Codex attempts because a completed socket send has uncertain external effects.
+ * Recovery independently overrides that classification for non-SSE Codex
+ * attempts unless `classifyCodexRecoverySendEvidence` proves a single
+ * pre-execution rejection, because a socket send may have reconnected or fallen
+ * back to SSE with uncertain external effects.
  */
 export interface RecoveryPhysicalAttempt {
 	readonly output: AsyncIterable<unknown> | Promise<AsyncIterable<unknown>>;
@@ -113,6 +133,12 @@ export interface RecoveryDispatchRequest {
 	readonly context: unknown;
 	readonly options: RecoveryBoundStreamOptions;
 	readonly signal: AbortSignal;
+	/**
+	 * Report bytes arriving on this attempt's connection, keep-alive pings
+	 * included. It resets only the request's idle limit: transport activity is
+	 * not output and never makes an attempt ineligible for recovery.
+	 */
+	readonly onTransportActivity: () => void;
 }
 
 export type RecoveryUsageCoverage =
@@ -133,7 +159,13 @@ export type RecoveryCostCoverage =
 export interface RecoveryAttemptAccounting {
 	readonly ordinal: number;
 	readonly candidate: RecoveryCandidate;
-	readonly disposition: "failed" | "accepted";
+	/**
+	 * `committed` means the attempt started streaming under
+	 * `stream-after-first-content` publication and now belongs to the caller; its
+	 * usage and cost are unknown here and the caller retains them at the
+	 * physical terminal.
+	 */
+	readonly disposition: "failed" | "accepted" | "committed";
 	readonly failureCode?: AcceptedOutputErrorCode | "dispatch-failure";
 	readonly reservation: RecoverySendReservation;
 	readonly chargedSendExposure: RecoveryChargedSendExposure;
@@ -141,8 +173,37 @@ export interface RecoveryAttemptAccounting {
 	readonly cost: RecoveryCostCoverage;
 }
 
+/**
+ * Content-free structured projection of a failed terminal for model policy.
+ *
+ * The engine copies only these named fields; assistant content, thinking, tool
+ * calls, error text, raw stop reasons, response identifiers, usage and
+ * diagnostic messages/details never reach the hook. A policy must decide from
+ * these structured facts alone and must never scan provider or assistant text.
+ */
+export interface RecoveryModelFailure {
+	readonly stopReason: AssistantMessage["stopReason"];
+	readonly api: string;
+	readonly provider: string;
+	readonly model: string;
+	/** Only whether the terminal carried an error message, never its text. */
+	readonly hasErrorMessage: boolean;
+	/** Diagnostic `type` identifiers only, in terminal order. */
+	readonly diagnosticTypes: readonly string[];
+	/**
+	 * Structured provider stop code, copied only from the two-value allowlist.
+	 * Absent for any other value; never derived from error or assistant text.
+	 */
+	readonly code?: "refusal" | "unknown_stop";
+}
+
 export interface RecoveryEngineDependencies {
 	readonly clock: RecoveryClock;
+	/** #129 owns this structured policy hook. Omission means no model recovery. */
+	readonly classifyModelRecovery?: (
+		failure: RecoveryModelFailure,
+		signal: AbortSignal,
+	) => RecoveryModelDecision | Promise<RecoveryModelDecision>;
 	/** Re-read eligibility, live config authorization and credentials here. */
 	readonly recheck: (
 		candidate: RecoveryCandidate,
@@ -168,8 +229,26 @@ export type RecoveryTimingConfig = Pick<
 	"recoveryIdleTimeoutMs" | "recoveryAbsoluteTimeoutMs"
 >;
 
+/**
+ * How an attempt's output is published.
+ *
+ * `buffered` (the default) holds every event until a successful terminal, so a
+ * failure at any point may still recover. `stream-after-first-content` holds
+ * the attempt's leading `start` events, which a provider pushes as soon as the
+ * response headers arrive and before any content: they are neither published
+ * nor counted as progress. The first content event (text, thinking or a tool
+ * call) commits the attempt and streams one held `start`, that event and the
+ * rest of the attempt live to the caller with no further recovery. A terminal,
+ * malformed or missing event, or a thrown failure, before any content falls
+ * back to the buffered path, so it may still recover and a failed attempt's
+ * held `start` is never published. A committed attempt is never retried, so
+ * output already shown to a consumer is never followed by a second send.
+ */
+export type RecoveryPublication = "buffered" | "stream-after-first-content";
+
 export interface RecoveryRequest {
 	readonly candidates: readonly RecoveryCandidate[];
+	readonly publication?: RecoveryPublication;
 	readonly context: unknown;
 	readonly options?: SimpleStreamOptions;
 	readonly timing: RecoveryTimingConfig;
@@ -192,7 +271,10 @@ export type RecoveryTerminationReason =
 	| "uncertain-external-effects"
 	| "completed-tool"
 	| "completed-call"
-	| "agent-run";
+	| "agent-run"
+	| "invalid-request"
+	| "refusal"
+	| "unknown";
 
 export type RecoveryResult =
 	| {
@@ -202,11 +284,29 @@ export type RecoveryResult =
 			readonly terminal: AssistantMessage;
 			readonly output: AssistantMessageEventStream;
 	  }
-	| { readonly status: "exhausted"; readonly attempts: number }
+	| {
+			/**
+			 * The attempt produced content under `stream-after-first-content`
+			 * publication. `output` yields its one held `start` (when it sent
+			 * one), the first content event and then the rest of the physical
+			 * stream unbuffered; the caller owns its terminal, timers and abort
+			 * from here on.
+			 */
+			readonly status: "committed";
+			readonly candidate: RecoveryCandidate;
+			readonly attempts: number;
+			readonly output: AsyncIterable<unknown>;
+	  }
+	| {
+			readonly status: "exhausted";
+			readonly attempts: number;
+			readonly errorMessage: string;
+	  }
 	| {
 			readonly status: "terminated";
 			readonly reason: RecoveryTerminationReason;
 			readonly attempts: number;
+			readonly errorMessage: string;
 	  };
 
 export interface RecoveryEngine {
@@ -235,15 +335,54 @@ interface ActiveRequest {
 const GAP_USAGE: RecoveryUsageCoverage = Object.freeze({ coverage: "gap" });
 const GAP_COST: RecoveryCostCoverage = Object.freeze({ coverage: "gap" });
 
+/**
+ * One unified logical call owns at most two provider invocations: the initial
+ * invocation plus one recovery invocation. Raising this value allows a third
+ * invocation and must fail the named `RECOVERY-TWO-SEND-CAP` regression.
+ *
+ * For the bounded HTTP/SSE families (Anthropic, OpenAI, Codex SSE) inner
+ * provider retries are forced to zero, so each invocation is one possibly
+ * charged send and the call makes at most two sends. Both Anthropic
+ * paths honour that zero: the adaptive adapter
+ * (`src/anthropic-adaptive-stream.ts`) and the vendored pinned stream
+ * (`packages/pi-anthropic-oauth/src/stream.ts`, local patch 0004) forward a
+ * finite non-negative integer `maxRetries` into `client.messages.create`.
+ *
+ * A Codex non-SSE (auto/WebSocket) invocation has an unknown internal send
+ * count: pinned pi-ai 0.84.4 may reconnect or fall back to SSE inside one
+ * invocation. The engine therefore never uses such an invocation for the
+ * recovery send, but it cannot control the internal count of a non-SSE initial
+ * invocation. Consumers, including the production cutover, must not claim the
+ * at-most-two-sends guarantee for Codex auto/WebSocket calls; only the
+ * two-invocation bound holds there. Routed Codex calls are currently pinned to
+ * SSE by `forceCodexSseOptions` (`src/codex-adapter.ts`), so a caller that
+ * passes the forced options here receives the bounded-HTTP reservation.
+ *
+ * A Google Antigravity invocation also has an unknown internal send count: the
+ * vendored stream (`packages/pi-antigravity/src/stream/stream.ts`) ignores
+ * `maxRetries` and can send once per empty-response retry (up to three), runtime
+ * model candidate, and `ENDPOINT_FALLBACKS` entry
+ * (`packages/pi-antigravity/src/client/client.ts`, three endpoints). The engine
+ * reserves it as unknown, never uses it for the recovery send, and terminates
+ * with `uncertain-external-effects` after a failed initial Antigravity
+ * invocation. Consumers must not claim the at-most-two-sends guarantee for
+ * Antigravity calls; only the two-invocation bound holds there.
+ */
+export const RECOVERY_MAX_PROVIDER_SENDS_PER_CALL = 2 as const;
+
 /**
  * Supported request-local retry controls. Keep every managed family's entry
  * separate: each provider path has its own compile-valid mutation control and
- * regression test. The provenance-locked adaptive Anthropic adapter ignores
- * this option, so its possible three SDK sends are over-reserved instead of
- * assumed away. Google Antigravity has no supported inner-retry behavior yet,
- * so it gets the same conservative zero the other non-Anthropic families use.
+ * regression test. Anthropic's zero bounds both Anthropic paths: the adaptive
+ * adapter (`ANTHROPIC-MAX-RETRIES-ZERO`) and the vendored pinned stream
+ * (`ANTHROPIC-PINNED-MAX-RETRIES`) each forward this request-local `maxRetries`
+ * into `client.messages.create`, so the SDK's two default retries never run.
+ * Google Antigravity receives the same fail-closed zero, but its vendored stream
+ * ignores it; its unknown inner send count is handled by the
+ * `antigravity-inner-unknown` reservation instead (see
+ * {@link RECOVERY_MAX_PROVIDER_SENDS_PER_CALL}).
  */
-const RECOVERY_INNER_RETRY_LIMITS = Object.freeze({
+export const RECOVERY_INNER_RETRY_LIMITS = Object.freeze({
 	anthropic: 0,
 	openai: 0,
 	"openai-codex": 0,
@@ -264,40 +403,63 @@ function sendReservationFor(
 	candidate: RecoveryCandidate,
 	options: RecoveryBoundStreamOptions,
 ): RecoverySendReservation {
-	if (candidate.family === "anthropic") {
-		// Recovery cannot see the model compat selector. Reserve the provenance-locked
-		// adaptive SDK's initial send plus two retries for every Anthropic candidate.
+	if (candidate.family === "openai-codex" && options.transport !== "sse") {
+		// Pinned pi-ai 0.84.4 can resend `response.create` once for
+		// previous_response_not_found, once for a connection-limit error, then fall
+		// back to one SSE send (`dist/api/openai-codex-responses.js:214-245`), so one
+		// invocation may make up to four sends. The supported terminal carries no
+		// trustworthy complete count, so this invocation can never authorize a send.
+		// Recovery cannot bound the internal sends of an initial non-SSE invocation
+		// and never forces SSE; that measured limit remains open for the cutover.
 		return Object.freeze({
-			maximumPossiblyChargedSends: 3,
-			overReservation: "deliberate",
-			basis: "adaptive-anthropic-provenance",
+			maximumPossiblyChargedSends: "unknown",
+			basis: "codex-non-sse-unknown",
 		});
 	}
-	if (candidate.family === "openai-codex" && options.transport !== "sse") {
-		// Pinned Codex can reconnect twice after socket.send, then fall back to one
-		// bounded SSE send. The supported API exposes no narrower send observation.
+	if (candidate.family === "google-antigravity") {
+		// The vendored stream ignores `maxRetries` and loops over empty-response
+		// retries, runtime-model candidates and endpoint fallbacks inside one
+		// invocation, so it can make several sends with no trustworthy count.
 		return Object.freeze({
-			maximumPossiblyChargedSends: 4,
-			overReservation: "deliberate",
-			basis: "codex-websocket-uncertain",
+			maximumPossiblyChargedSends: "unknown",
+			basis: "antigravity-inner-unknown",
 		});
 	}
 	return Object.freeze({
 		maximumPossiblyChargedSends: 1,
-		overReservation: "none",
-		basis: "bounded-http",
+		basis: "bounded-provider-invocation",
 	});
 }
 
 function chargedSendExposureFor(
 	reservation: RecoverySendReservation,
 ): RecoveryChargedSendExposure {
-	return reservation.basis === "codex-websocket-uncertain"
-		? Object.freeze({ status: "unknown", reason: "codex-websocket-send" })
-		: Object.freeze({
-				status: "bounded",
-				maximumPossiblyChargedSends: reservation.maximumPossiblyChargedSends,
-			});
+	switch (reservation.basis) {
+		case "codex-non-sse-unknown":
+			return Object.freeze({ status: "unknown", reason: "codex-non-sse-send-count" });
+		case "antigravity-inner-unknown":
+			return Object.freeze({ status: "unknown", reason: "antigravity-inner-sends" });
+		case "bounded-provider-invocation":
+			return Object.freeze({ status: "bounded", maximumPossiblyChargedSends: 1 });
+	}
+}
+
+/**
+ * Content-free terminal error text for an exhausted or terminated recovery.
+ *
+ * Host retries count toward the same two-send cap. Pinned pi-coding-agent 0.84.4
+ * `AgentSession._isRetryableError` (`dist/core/agent-session.js:2241-2246`)
+ * restarts the turn when `isRetryableAssistantError` from
+ * `@earendil-works/pi-ai/compat` matches the final `errorMessage`
+ * (`pi-ai/dist/utils/retry.js:166-173`, patterns at `:4-77`), and its overflow
+ * path compact-and-retries when `isContextOverflow` matches
+ * (`agent-session.js:1652-1690`, `pi-ai/dist/utils/overflow.js:130-156`). A
+ * production caller must surface this message, never a provider's own text, so
+ * neither host path can add a third send. The named `HOST-RETRY-BOUNDARY`
+ * regression checks both classifiers directly.
+ */
+export function buildBoundedRecoveryFinalErrorMessage(): string {
+	return "Unified recovery stopped after its bounded provider attempt.";
 }
 
 function finiteNonNegative(value: unknown): number | undefined {
@@ -352,8 +514,26 @@ function terminalFromEvent(event: unknown): unknown {
 	return undefined;
 }
 
+function assistantTerminal(value: unknown): AssistantMessage | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const terminal = value as Partial<AssistantMessage>;
+	return terminal.role === "assistant" &&
+		Array.isArray(terminal.content) &&
+		typeof terminal.api === "string" &&
+		typeof terminal.provider === "string" &&
+		typeof terminal.model === "string" &&
+		typeof terminal.stopReason === "string" &&
+		typeof terminal.timestamp === "number"
+		? (terminal as AssistantMessage)
+		: undefined;
+}
+
+/**
+ * Assistant content a consumer would see. A provider's `start` event is not
+ * here: it only reports that the response headers arrived, so it is held, never
+ * counted as progress or output, and a failure after it is still pre-output.
+ */
 const PROGRESS_EVENT_TYPES = new Set([
-	"start",
 	"text_start",
 	"text_delta",
 	"text_end",
@@ -373,9 +553,27 @@ function isProgressEvent(event: unknown): boolean {
 	);
 }
 
+/**
+ * Whether an event is assistant content (text, thinking or a tool call). Only
+ * content counts as output for in-call recovery; a `start` never does.
+ */
+export function isRecoveryContentEvent(event: unknown): boolean {
+	return isProgressEvent(event);
+}
+
+/** Whether an event is the provider's `start`, held until the first content. */
+export function isRecoveryStartEvent(event: unknown): boolean {
+	return (
+		typeof event === "object" &&
+		event !== null &&
+		(event as { type?: unknown }).type === "start"
+	);
+}
+
 function observedOutput(
 	upstream: AsyncIterable<unknown> | Promise<AsyncIterable<unknown>>,
 	onProgress: () => void,
+	onTerminal: (terminal: AssistantMessage) => void,
 	onFacts: (facts: AttemptFacts) => void,
 ): AsyncIterable<unknown> {
 	return {
@@ -383,8 +581,12 @@ function observedOutput(
 			const source = await upstream;
 			for await (const event of source) {
 				if (isProgressEvent(event)) onProgress();
-				const facts = projectAttemptFacts(terminalFromEvent(event));
-				if (facts !== undefined) onFacts(facts);
+				const terminal = assistantTerminal(terminalFromEvent(event));
+				if (terminal !== undefined) {
+					onTerminal(terminal);
+					const facts = projectAttemptFacts(terminal);
+					if (facts !== undefined) onFacts(facts);
+				}
 				yield event;
 			}
 		},
@@ -450,11 +652,25 @@ function validCandidate(candidate: RecoveryCandidate): boolean {
 		// future family addition cannot silently fall out of recovery consideration
 		// the way the prior hand-listed three-family check did for Google Antigravity.
 		isManagedFamily(candidate.family) &&
+		// A caller-built candidate must name a canonical account of its own family,
+		// so a mislabelled id can never borrow another family's send reservation.
+		isCanonicalManagedProviderId(candidate.providerId, candidate.family) &&
 		typeof candidate.modelId === "string" &&
-		candidate.modelId.length > 0
+		candidate.modelId.length > 0 &&
+		(candidate.recoveryAction === "account" || candidate.recoveryAction === "model")
 	);
 }
 
+function changesOnlyAuthorizedDimension(
+	initial: RecoveryCandidate,
+	candidate: RecoveryCandidate,
+	action: RecoveryActionKind,
+): boolean {
+	return action === "account"
+		? candidate.providerId !== initial.providerId && candidate.modelId === initial.modelId
+		: candidate.modelId !== initial.modelId;
+}
+
 function observeLatePhysicalAttempt(
 	pending: RecoveryPhysicalAttempt | Promise<RecoveryPhysicalAttempt>,
 	signal: AbortSignal,
@@ -478,6 +694,163 @@ function observeLatePhysicalAttempt(
 	);
 }
 
+/**
+ * An attempt read up to its first event that is not a `start`. At most one
+ * `start` is kept: a provider sends one, and a repeat carries nothing a
+ * consumer needs.
+ */
+interface HeldPrefix {
+	readonly iterator: AsyncIterator<unknown>;
+	readonly held: readonly unknown[];
+	/** The step after the held events; absent when reading it failed. */
+	readonly next?: IteratorResult<unknown>;
+	readonly failure?: { readonly error: unknown };
+}
+
+type PeekResult =
+	| { readonly status: "aborted" }
+	| { readonly status: "content"; readonly prefix: HeldPrefix }
+	| { readonly status: "replay"; readonly prefix: Promise<HeldPrefix> };
+
+/**
+ * Read an attempt past its leading `start` events. A held `start` is not
+ * progress, so it never resets the request's idle limit. A rejection while
+ * opening the stream or before any `start` rejects; a rejection after a held
+ * `start` is kept so the replay can rethrow it at the same point.
+ */
+function readHeldPrefix(
+	output: AsyncIterable<unknown> | Promise<AsyncIterable<unknown>>,
+): Promise<HeldPrefix> {
+	const pending = (async (): Promise<HeldPrefix> => {
+		const source = await output;
+		const iterator = source[Symbol.asyncIterator]();
+		const held: unknown[] = [];
+		let sawStart = false;
+		for (;;) {
+			let step: IteratorResult<unknown>;
+			try {
+				step = await iterator.next();
+			} catch (error) {
+				if (!sawStart) throw error;
+				return { iterator, held, failure: { error } };
+			}
+			if (step.done !== true && isRecoveryStartEvent(step.value)) {
+				if (!sawStart) held.push(step.value);
+				sawStart = true;
+				continue;
+			}
+			return { iterator, held, next: step };
+		}
+	})();
+	void pending.catch(() => {});
+	return pending;
+}
+
+function closeIterator(iterator: AsyncIterator<unknown>): void {
+	try {
+		void Promise.resolve(iterator.return?.()).catch(() => {});
+	} catch {
+		// A throwing `return` is contained like any other callback failure.
+	}
+}
+
+/**
+ * The attempt's output, resumed after the engine read its held prefix. The
+ * held `start` replays first, then the step that ended the prefix; a failure
+ * the read observed rethrows at the same point, so the buffered path sees
+ * exactly what an unread stream would have produced.
+ */
+function resumedOutput(prefix: Promise<HeldPrefix>): AsyncIterable<unknown> {
+	return {
+		async *[Symbol.asyncIterator]() {
+			const { iterator, held, next, failure } = await prefix;
+			let finished = false;
+			try {
+				for (const event of held) yield event;
+				if (failure !== undefined) {
+					finished = true;
+					throw failure.error;
+				}
+				if (next === undefined || next.done === true) {
+					finished = true;
+					return;
+				}
+				yield next.value;
+				for (;;) {
+					const step = await iterator.next();
+					if (step.done === true) {
+						finished = true;
+						return;
+					}
+					yield step.value;
+				}
+			} finally {
+				if (!finished) closeIterator(iterator);
+			}
+		},
+	};
+}
+
+async function peekFirstContent(
+	output: AsyncIterable<unknown> | Promise<AsyncIterable<unknown>>,
+	request: ActiveRequest,
+): Promise<PeekResult> {
+	const prefix = readHeldPrefix(output);
+	const settled = await awaitRequest(prefix, request);
+	if (settled.status === "aborted") {
+		void prefix.then(({ iterator }) => closeIterator(iterator), () => {});
+		return { status: "aborted" };
+	}
+	if (
+		settled.status === "value" &&
+		settled.value.next !== undefined &&
+		settled.value.next.done !== true &&
+		isRecoveryContentEvent(settled.value.next.value)
+	) {
+		return { status: "content", prefix: settled.value };
+	}
+	return { status: "replay", prefix };
+}
+
+/**
+ * The first send must use the call's selected model on an account candidate.
+ * A model change happens only through `classifyModelRecovery` after a
+ * structured failure, never because recheck skipped every exact-model account.
+ */
+function eligibleInitialCandidate(candidate: RecoveryCandidate): boolean {
+	return (
+		candidate.recoveryAction === "account" &&
+		candidate.modelId === candidate.selectedModelId
+	);
+}
+
+function projectModelFailure(terminal: AssistantMessage): RecoveryModelFailure {
+	const diagnostics: readonly unknown[] = Array.isArray(terminal.diagnostics)
+		? terminal.diagnostics
+		: [];
+	const diagnosticTypes: string[] = [];
+	for (const diagnostic of diagnostics) {
+		const type =
+			typeof diagnostic === "object" && diagnostic !== null
+				? (diagnostic as { type?: unknown }).type
+				: undefined;
+		if (typeof type === "string") diagnosticTypes.push(type);
+	}
+	const rawCode = (terminal as { code?: unknown }).code;
+	const code =
+		rawCode === "refusal" || rawCode === "unknown_stop" ? rawCode : undefined;
+	return Object.freeze({
+		stopReason: terminal.stopReason,
+		api: terminal.api,
+		provider: terminal.provider,
+		model: terminal.model,
+		hasErrorMessage:
+			typeof terminal.errorMessage === "string" && terminal.errorMessage.length > 0,
+		diagnosticTypes: Object.freeze(diagnosticTypes),
+		...(code === undefined ? {} : { code }),
+	});
+}
+
 function validPreDispatchDecision(value: unknown): value is RecoveryPreDispatchDecision {
 	if (typeof value !== "object" || value === null) return false;
 	const decision = value as Record<string, unknown>;
@@ -492,18 +865,39 @@ function validPreDispatchDecision(value: unknown): value is RecoveryPreDispatchD
 function validRetrySafety(value: unknown): value is RecoveryRetrySafety {
 	if (typeof value !== "object" || value === null) return false;
 	const safety = value as Record<string, unknown>;
-	if (safety.status === "retryable") {
+	if (safety.status === "recoverable") {
 		return (
-			safety.reason === "generation-only-incomplete" ||
-			safety.reason === "definitively-rejected"
+			safety.action === "account" &&
+			(safety.reason === "account-local-quota" ||
+				safety.reason === "account-local-auth" ||
+				safety.reason === "account-local-rate-limit" ||
+				safety.reason === "pre-start-transient")
 		);
 	}
+	if (safety.status === "model-policy") {
+		return safety.reason === "structured-provider-error";
+	}
 	return (
 		safety.status === "unsafe" &&
 		(safety.reason === "uncertain-external-effects" ||
 			safety.reason === "completed-tool" ||
 			safety.reason === "completed-call" ||
-			safety.reason === "agent-run")
+			safety.reason === "agent-run" ||
+			safety.reason === "invalid-request" ||
+			safety.reason === "refusal" ||
+			safety.reason === "unknown")
+	);
+}
+
+function validModelDecision(value: unknown): value is RecoveryModelDecision {
+	if (typeof value !== "object" || value === null) return false;
+	const decision = value as Record<string, unknown>;
+	return (
+		decision.status === "none" ||
+		(decision.status === "recoverable" &&
+			decision.action === "model" &&
+			(decision.reason === "unsupported-model" ||
+				decision.reason === "unsupported-capability"))
 	);
 }
 
@@ -558,16 +952,34 @@ async function runRecovery(
 	onProgress: () => void,
 ): Promise<RecoveryResult> {
 	let attempts = 0;
+	let initialCandidate: RecoveryCandidate | undefined;
+	let recoveryAction: RecoveryActionKind | undefined;
 	const terminated = (): RecoveryResult => ({
 		status: "terminated",
 		reason: request.reason ?? "callback-failure",
 		attempts,
+		errorMessage: buildBoundedRecoveryFinalErrorMessage(),
+	});
+	const exhausted = (): RecoveryResult => ({
+		status: "exhausted",
+		attempts,
+		errorMessage: buildBoundedRecoveryFinalErrorMessage(),
 	});
 	const consideredPairs = new Set<string>();
 
 	for (const candidate of [...input.candidates]) {
 		if (request.controller.signal.aborted) return terminated();
+		if (attempts >= RECOVERY_MAX_PROVIDER_SENDS_PER_CALL) return exhausted();
 		if (!validCandidate(candidate)) continue;
+		if (initialCandidate === undefined && !eligibleInitialCandidate(candidate)) continue;
+		if (
+			recoveryAction !== undefined &&
+			(initialCandidate === undefined ||
+				candidate.recoveryAction !== recoveryAction ||
+				!changesOnlyAuthorizedDimension(initialCandidate, candidate, recoveryAction))
+		) {
+			continue;
+		}
 		const pair = `${candidate.providerId}\u0000${candidate.modelId}`;
 		if (consideredPairs.has(pair)) continue;
 		consideredPairs.add(pair);
@@ -608,8 +1020,16 @@ async function runRecovery(
 			abortRequest(request, "callback-failure");
 			return terminated();
 		}
+		if (attempts > 0 && reservation.maximumPossiblyChargedSends === "unknown") {
+			// The recovery send is the call's last send. A pinned Codex non-SSE or a
+			// vendored Antigravity invocation can make several internal sends, so it
+			// cannot fit a one-send remainder.
+			continue;
+		}
+		// A reservation keeps its ordinal even when the request aborts before dispatch.
+		const ordinal = attempts + 1;
 		const reserved = await reserveAttempt(deps, request, {
-			ordinal: attempts + 1,
+			ordinal,
 			candidate,
 			reservation,
 		});
@@ -625,7 +1045,10 @@ async function runRecovery(
 			| { readonly terminal: AssistantMessage; readonly output: AssistantMessageEventStream }
 			| undefined;
 		let safety: RecoveryRetrySafety | undefined;
+		let terminal: AssistantMessage | undefined;
 		let callbackFailed = false;
+		let sawProgress = false;
+		let committed: { readonly output: AsyncIterable<unknown> } | undefined;
 		const attemptController = new AbortController();
 		const abortAttempt = (): void => attemptController.abort();
 		request.controller.signal.addEventListener("abort", abortAttempt, { once: true });
@@ -635,12 +1058,17 @@ async function runRecovery(
 		if (!request.controller.signal.aborted) {
 			try {
 				// A physical attempt begins exactly when this callback is invoked.
+				initialCandidate ??= candidate;
 				attempts += 1;
 				physicalValue = deps.dispatch({
 					candidate,
 					context: input.context,
 					options: streamOptions,
 					signal: attemptController.signal,
+					onTransportActivity: () => {
+						// Liveness, not output: only the idle limit is reset.
+						if (!attemptController.signal.aborted) onProgress();
+					},
 				});
 			} catch {
 				callbackFailed = true;
@@ -661,51 +1089,82 @@ async function runRecovery(
 						}
 						const safetyPromise = Promise.resolve(physical.retrySafety);
 						void safetyPromise.catch(() => {});
-						const output = createAcceptedOutputStream(
-							observedOutput(
-								physical.output,
-								onProgress,
-								(observed) => {
-									facts = observed;
-								},
-							),
-							{ signal: request.controller.signal },
-						);
-						const outputResult = await awaitRequest(output.result(), request);
-						if (outputResult.status === "value") {
-							accepted = { terminal: outputResult.value, output };
-							facts = projectAttemptFacts(outputResult.value) ?? facts;
-						} else if (outputResult.status === "rejected") {
-							try {
-								await output.result();
-							} catch (error) {
-								failureCode =
-									error instanceof AcceptedOutputError
-										? error.code
-										: "dispatch-failure";
+						let upstream: AsyncIterable<unknown> | Promise<AsyncIterable<unknown>> =
+							physical.output;
+						let peekAborted = false;
+						if (input.publication === "stream-after-first-content") {
+							const peek = await peekFirstContent(physical.output, request);
+							if (peek.status === "aborted") {
+								peekAborted = true;
+							} else if (peek.status === "content") {
+								onProgress();
+								sawProgress = true;
+								committed = { output: resumedOutput(Promise.resolve(peek.prefix)) };
+							} else {
+								upstream = resumedOutput(peek.prefix);
 							}
 						}
-						if (accepted === undefined) {
-							if (reservation.basis === "codex-websocket-uncertain") {
-								// No supported hook distinguishes an unsent connection failure from
-								// a failure after socket.send. The latter may already be executing,
-								// so recovery must never dispatch another candidate.
-								safety = {
-									status: "unsafe",
-									reason: "uncertain-external-effects",
-								};
-							} else {
-								const safetyResult = await awaitRequest(safetyPromise, request);
+						if (committed === undefined && !peekAborted) {
+							const output = createAcceptedOutputStream(
+								observedOutput(
+									upstream,
+									() => {
+										sawProgress = true;
+										onProgress();
+									},
+									(observed) => {
+										terminal = observed;
+									},
+									(observed) => {
+										facts = observed;
+									},
+								),
+								{ signal: request.controller.signal },
+							);
+							const outputResult = await awaitRequest(output.result(), request);
+							if (outputResult.status === "value") {
+								accepted = { terminal: outputResult.value, output };
+								facts = projectAttemptFacts(outputResult.value) ?? facts;
+							} else if (outputResult.status === "rejected") {
+								try {
+									await output.result();
+								} catch (error) {
+									failureCode =
+										error instanceof AcceptedOutputError
+											? error.code
+											: "dispatch-failure";
+								}
+							}
+							if (accepted === undefined) {
 								if (
-									safetyResult.status === "value" &&
-									validRetrySafety(safetyResult.value)
+									reservation.basis === "antigravity-inner-unknown" ||
+									(reservation.basis === "codex-non-sse-unknown" &&
+										(terminal === undefined ||
+											classifyCodexRecoverySendEvidence(terminal) !==
+												"pre-execution-rejected"))
 								) {
-									safety = safetyResult.value;
-								} else if (
-									safetyResult.status === "rejected" ||
-									safetyResult.status === "value"
-								) {
-									callbackFailed = true;
+									// A non-SSE Codex invocation may have reconnected or fallen back
+									// to SSE after socket.send; only structured proof of a single
+									// pre-execution rejection may consult the caller's classifier.
+									// An Antigravity invocation may already have sent to several
+									// endpoints or runtime models; no supported evidence bounds it.
+									safety = {
+										status: "unsafe",
+										reason: "uncertain-external-effects",
+									};
+								} else {
+									const safetyResult = await awaitRequest(safetyPromise, request);
+									if (
+										safetyResult.status === "value" &&
+										validRetrySafety(safetyResult.value)
+									) {
+										safety = safetyResult.value;
+									} else if (
+										safetyResult.status === "rejected" ||
+										safetyResult.status === "value"
+									) {
+										callbackFailed = true;
+									}
 								}
 							}
 						}
@@ -716,22 +1175,46 @@ async function runRecovery(
 			}
 
 		const accounting = await accountAttempt(deps, request, {
-			ordinal: attempts,
+			ordinal,
 			candidate,
-			disposition: accepted === undefined ? "failed" : "accepted",
-			...(accepted === undefined ? { failureCode } : {}),
+			disposition:
+				committed !== undefined ? "committed" : accepted === undefined ? "failed" : "accepted",
+			...(accepted === undefined && committed === undefined ? { failureCode } : {}),
 			reservation,
 			chargedSendExposure: chargedSendExposureFor(reservation),
 			usage: facts.usage,
 			cost: facts.cost,
 		});
 		request.controller.signal.removeEventListener("abort", abortAttempt);
+		if (
+			committed !== undefined &&
+			accounting === "recorded" &&
+			!request.controller.signal.aborted
+		) {
+			// The live attempt now belongs to the caller: its signal stays open and
+			// no later send exists for this call.
+			return { status: "committed", candidate, attempts, output: committed.output };
+		}
 		if (!attemptController.signal.aborted) abortAttempt();
+		if (committed !== undefined) {
+			// Close the started stream; a committed attempt is never retried.
+			void (async () => {
+				try {
+					for await (const _event of committed.output) break;
+				} catch {
+					// The attempt was already aborted.
+				}
+			})();
+		}
 		if (request.controller.signal.aborted) return terminated();
 		if (accounting === "rejected") {
 			abortRequest(request, "accounting-rejected");
 			return terminated();
 		}
+		if (committed !== undefined) {
+			abortRequest(request, "callback-failure");
+			return terminated();
+		}
 		if (accepted !== undefined) {
 			return {
 				status: "accepted",
@@ -745,12 +1228,52 @@ async function runRecovery(
 			abortRequest(request, "callback-failure");
 			return terminated();
 		}
+		if (safety.status === "recoverable" && safety.reason === "pre-start-transient" && sawProgress) {
+			// A transient failure is retried only while nothing was produced.
+			abortRequest(request, "uncertain-external-effects");
+			return terminated();
+		}
+		if (safety.status === "recoverable") {
+			recoveryAction = safety.action;
+			continue;
+		}
 		if (safety.status === "unsafe") {
 			abortRequest(request, safety.reason);
 			return terminated();
 		}
+		// The recovery send was the last send; do not consult model policy for a
+		// third send that the call can never make.
+		if (attempts >= RECOVERY_MAX_PROVIDER_SENDS_PER_CALL) return exhausted();
+		if (terminal === undefined || deps.classifyModelRecovery === undefined) {
+			abortRequest(request, "unknown");
+			return terminated();
+		}
+		let modelValue: ReturnType<NonNullable<RecoveryEngineDependencies["classifyModelRecovery"]>>;
+		try {
+			modelValue = deps.classifyModelRecovery(
+				projectModelFailure(terminal),
+				request.controller.signal,
+			);
+		} catch {
+			abortRequest(request, "callback-failure");
+			return terminated();
+		}
+		const modelDecision = await awaitRequest(modelValue, request);
+		if (modelDecision.status === "aborted") return terminated();
+		if (
+			modelDecision.status === "rejected" ||
+			!validModelDecision(modelDecision.value)
+		) {
+			abortRequest(request, "callback-failure");
+			return terminated();
+		}
+		if (modelDecision.value.status === "none") {
+			abortRequest(request, "unknown");
+			return terminated();
+		}
+		recoveryAction = modelDecision.value.action;
 	}
-	return { status: "exhausted", attempts };
+	return exhausted();
 }
 
 export function createRecoveryEngine(
@@ -767,14 +1290,24 @@ export function createRecoveryEngine(
 	return {
 		async recover(input): Promise<RecoveryResult> {
 			if (shutdown) {
-				return { status: "terminated", reason: "shutdown", attempts: 0 };
+				return {
+					status: "terminated",
+					reason: "shutdown",
+					attempts: 0,
+					errorMessage: buildBoundedRecoveryFinalErrorMessage(),
+				};
 			}
 			if (
 				!validTiming(input.timing) ||
 				(input.deadlineMs !== undefined &&
 					(!Number.isFinite(input.deadlineMs) || input.deadlineMs < 0))
 			) {
-				return { status: "terminated", reason: "malformed-config", attempts: 0 };
+				return {
+					status: "terminated",
+					reason: "malformed-config",
+					attempts: 0,
+					errorMessage: buildBoundedRecoveryFinalErrorMessage(),
+				};
 			}
 
 			const activeRequest: ActiveRequest = { controller: new AbortController() };
@@ -784,8 +1317,11 @@ export function createRecoveryEngine(
 			let absoluteTimer: RecoveryTimer | undefined;
 			let callerAbort: (() => void) | undefined;
 			let idleGeneration = 0;
+			let settled = false;
 			const resetIdle = (): void => {
-				if (activeRequest.controller.signal.aborted) return;
+				// A committed attempt's connection outlives the invocation; its late
+				// transport activity must not arm a timer for a settled request.
+				if (settled || activeRequest.controller.signal.aborted) return;
 				const generation = ++idleGeneration;
 				cancelTimer(idleTimer);
 				try {
@@ -833,10 +1369,12 @@ export function createRecoveryEngine(
 						status: "terminated",
 						reason: activeRequest.reason ?? "callback-failure",
 						attempts: 0,
+						errorMessage: buildBoundedRecoveryFinalErrorMessage(),
 					};
 				}
 				return await runRecovery(deps, input, activeRequest, resetIdle);
 			} finally {
+				settled = true;
 				idleGeneration += 1;
 				cancelTimer(deadlineTimer);
 				cancelTimer(idleTimer);