@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/server/relay.ts

@@ -32,6 +32,8 @@ import {
 } from "./sse-frame-buffer";
 import { replaceSseDataPayload, sseDataPayload } from "./sse-payload-rewrite";
 import { createBoundedResponseLogBody } from "./response-log-body";
+import { clientWireLogOf } from "./inference/client-wire";
+import { recordClientWireRequestLog } from "./inference/client-wire-log";
 
 const nativePassthroughSseResponses = new WeakSet<Response>();
 const eagerRelaySseResponses = new WeakSet<Response>();
@@ -817,6 +819,13 @@ export function responseWithDeferredRequestLog(
   if (isNativePassthroughSseResponse(response)) {
     return response;
   }
+  // A body already in the client's wire is not Responses SSE or JSON; its producer reports the
+  // facts the tap below would read (PF-09 direct encoders).
+  const clientWireLog = clientWireLogOf(response);
+  if (clientWireLog) {
+    recordClientWireRequestLog(clientWireLog, requestId, start, logCtx, addLog);
+    return response;
+  }
   if (!response.body || !contentType.includes("text/event-stream")) {
     if (response.body && (contentType.includes("application/json") || response.status >= 400)) {
       const body = createBoundedResponseLogBody(response.body, {

package/src/server/request-log-filter.ts

@@ -0,0 +1,92 @@
+/**
+ * `/api/logs` query filters over the in-memory request log. Split out of `request-log.ts`
+ * (which sits at its file-size threshold) so query clauses can grow here.
+ */
+import type { RequestLogEntry } from "./request-log";
+import { matchesLogConversationId } from "./request-log-conversation";
+import { isDeliveryMode } from "../protocols/contract";
+
+/** Capacity of the in-memory request log ring; also the upper bound of `tail` and `limit`. */
+export const MAX_LOG_SIZE = 2000;
+
+/** `protocolMode=none` selects rows with no observed protocol trace. */
+export const REQUEST_LOG_PROTOCOL_MODE_NONE = "none";
+
+/**
+ * Whether a row matches a `protocolMode` query value: the final trace mode, or `none` for a row
+ * without a trace. An unrecognised value matches nothing rather than being ignored, for the
+ * reason #2704 gives for `model`.
+ */
+export function matchesProtocolMode(entry: Pick<RequestLogEntry, "protocolTrace">, mode: string): boolean {
+  if (mode === REQUEST_LOG_PROTOCOL_MODE_NONE) return entry.protocolTrace === undefined;
+  return isDeliveryMode(mode) && entry.protocolTrace?.mode === mode;
+}
+
+export function filterRequestLogs(logs: RequestLogEntry[], params: URLSearchParams): RequestLogEntry[] {
+  let filtered = logs;
+  const provider = params.get("provider")?.trim();
+  if (provider) {
+    filtered = filtered.filter(entry => entry.provider === provider
+      || entry.attempts?.some(attempt => attempt.provider === provider));
+  }
+  const conversationId = params.get("conversationId")?.trim() || params.get("conversation")?.trim();
+  if (conversationId) {
+    filtered = filtered.filter(entry => matchesLogConversationId(entry.conversationId, conversationId));
+  }
+  // #2704: there was no `model` clause at all, so `?model=x` was ACCEPTED and silently
+  // ignored -- worse than an error, because it yields wrong conclusions from output that
+  // looks correct. Attempts are matched for the same reason `provider` matches them: a
+  // request that failed over should be findable by the model that actually served it.
+  const model = params.get("model")?.trim();
+  if (model) {
+    filtered = filtered.filter(entry => entry.model === model
+      || entry.attempts?.some(attempt => attempt.model === model));
+  }
+  // #4057: "which account served this request" is the first question asked when one provider
+  // holds several accounts, and until now the only way to answer it was to grep usage.jsonl by
+  // hand. Attempts are matched for the same reason `provider` and `model` match them: when a
+  // request failed over between pool accounts, a search for the account that finally served it
+  // has to find that request, not only the account that first refused it.
+  const account = params.get("account")?.trim();
+  if (account) {
+    filtered = filtered.filter(entry => entry.accountLogLabel === account
+      || entry.attempts?.some(attempt => attempt.accountLogLabel === account));
+  }
+  const protocolMode = params.get("protocolMode")?.trim().toLowerCase();
+  if (protocolMode) filtered = filtered.filter(entry => matchesProtocolMode(entry, protocolMode));
+  const status = params.get("status")?.trim().toLowerCase();
+  if (status) {
+    filtered = /^[1-5]xx$/.test(status)
+      ? filtered.filter(entry => Math.floor(entry.status / 100) === Number(status[0]))
+      : filtered.filter(entry => String(entry.status) === status);
+  }
+  const tailRaw = params.get("tail")?.trim();
+  if (tailRaw) {
+    const tail = Number.parseInt(tailRaw, 10);
+    if (Number.isFinite(tail) && tail > 0) filtered = filtered.slice(-Math.min(tail, MAX_LOG_SIZE));
+  }
+  const offsetRaw = params.get("offset")?.trim();
+  const limitRaw = params.get("limit")?.trim();
+  if (limitRaw) {
+    const limit = Number.parseInt(limitRaw, 10);
+    const offset = offsetRaw ? Number.parseInt(offsetRaw, 10) : 0;
+    if (Number.isFinite(limit) && limit > 0) {
+      const capped = Math.min(limit, MAX_LOG_SIZE);
+      const startOffset = Number.isFinite(offset) && offset > 0 ? offset : 0;
+      const end = filtered.length - startOffset;
+      if (end <= 0) filtered = [];
+      else {
+        const begin = Math.max(0, end - capped);
+        filtered = filtered.slice(begin, end);
+      }
+    }
+  }
+  return filtered;
+}
+
+export function filteredRequestLogCount(logs: RequestLogEntry[], params: URLSearchParams): number {
+  const withoutPagination = new URLSearchParams(params);
+  withoutPagination.delete("limit");
+  withoutPagination.delete("offset");
+  return filterRequestLogs(logs, withoutPagination).length;
+}

package/src/server/request-log.ts

@@ -22,6 +22,8 @@ import type { CodexAffinityMove, CodexAffinityReason } from "../codex/routing";
 import { readCodexCatalogPath } from "../codex/catalog";
 import type { AttemptTierOutcome, OcxProviderConfig, OcxUsage } from "../types";
 import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
+import { parseProtocolTraceV1, type ProtocolTraceV1 } from "../protocols/dto";
+import { protocolTraceForRequest } from "../protocols/trace";
 import type { AdapterRequest } from "../adapters/base";
 import type { RequestSpendSettlement } from "./responses/request-spend";
 import type { AdapterTierMetadata } from "../providers/fastwire";
@@ -70,13 +72,18 @@ import {
   USAGE_DEBUG_BODY_SAMPLE_BYTES,
   type UsageDebugBodyKind,
 } from "../usage/debug";
-import { matchesLogConversationId } from "./request-log-conversation";
+import { MAX_LOG_SIZE } from "./request-log-filter";
+export { filterRequestLogs, filteredRequestLogCount } from "./request-log-filter";
 import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
 import { capEstimateAtContextWindow } from "../lib/token-estimate";
 import { inferCursorContextWindow } from "../adapters/cursor/discovery";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
 import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
 import { modelRecordValue } from "../reasoning-effort";
+import {
+  normalizePersistedJevDecision,
+  type PersistedJevDecisionV1,
+} from "../usage/jev-stats";
 import type { RequestMetricsRecorder } from "./request-metrics";
 import type {
   CacheDiagnosticDraft,
@@ -239,6 +246,8 @@ export interface RequestLogContext {
   terminalSource?: "upstream" | "synthetic";
   /** Bounded route-decision trace (RI-01); never contains secrets. */
   routeDecision?: RouteDecisionTraceV1;
+  /** Privacy-bounded JEV selection metadata; downstream usage is recorded on attempts[]. */
+  jevDecision?: PersistedJevDecisionV1;
   /** Opt-in shadow evidence, normalized again at the logging boundary. */
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
 }
@@ -349,6 +358,8 @@ export interface RequestLogEntry {
   terminalSource?: "upstream" | "synthetic";
   /** Bounded route-decision trace (RI-01); never contains secrets. */
   routeDecision?: RouteDecisionTraceV1;
+  /** Privacy-bounded JEV selection metadata; downstream usage is recorded on attempts[]. */
+  jevDecision?: PersistedJevDecisionV1;
   /** Closed Claude protocol codes; no request or header values. */
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
   /**
@@ -358,11 +369,12 @@ export interface RequestLogEntry {
    */
   failureStage?: RequestFailureStage;
   failureCause?: RequestFailureCause;
+  /** Observed protocol path (PF-02, `src/protocols/trace.ts`); absent when nothing was observed. */
+  protocolTrace?: ProtocolTraceV1;
 }
 
 const requestLog: RequestLogEntry[] = [];
 const requestLogObserversForTests = new Set<(entry: RequestLogEntry) => void>();
-const MAX_LOG_SIZE = 2000;
 const requestLogEntryBytes = new WeakMap<RequestLogEntry, number>();
 let requestLogBytes = 0;
 /** True after hydrateRequestLogsFromDisk ran once in this process. */
@@ -427,8 +439,10 @@ export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): R
   const terminalStatus = asTerminalStatus(entry.terminalStatus);
   const closeReason = asCloseReason(entry.closeReason);
   const routeDecision = normalizeRouteDecisionTraceForLog(entry.routeDecision);
+  const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
   const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
   const spend = normalizeRequestSpend(entry.spend);
+  const protocolTrace = parseProtocolTraceV1(entry.protocolTrace);
   return {
     requestId: entry.requestId,
     ...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
@@ -479,11 +493,13 @@ export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): R
     ...(isKnownTransportPhase(entry.transportPhase) ? { transportPhase: entry.transportPhase } : {}),
     ...(isKnownTerminalSource(entry.terminalSource) ? { terminalSource: entry.terminalSource } : {}),
     ...(routeDecision ? { routeDecision } : {}),
+    ...(jevDecision ? { jevDecision } : {}),
     ...(claudeCompatibility ? { claudeCompatibility } : {}),
     ...(entry.conversationStateScrub === "account-change"
       ? { conversationStateScrub: "account-change" }
       : {}),
     ...normalizeRequestFailureAttribution(entry),
+    ...(protocolTrace ? { protocolTrace } : {}),
   };
 }
 
@@ -574,8 +590,11 @@ export function addRequestLog(entry: RequestLogEntry) {
   const shadowCallRewrittenFrom = sanitizeLogMetadataString(entry.shadowCallRewrittenFrom);
   const servedModel = modelIdentityLogFields(entry).servedModel;
   const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
+  const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
   const retained: RequestLogEntry = shadowCallRewrittenFrom === entry.shadowCallRewrittenFrom
-    && servedModel === entry.servedModel && entry.claudeCompatibility === undefined
+    && servedModel === entry.servedModel
+    && entry.claudeCompatibility === undefined
+    && entry.jevDecision === undefined
     ? entry
     : { ...entry, ...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}) };
   if (!shadowCallRewrittenFrom && retained !== entry) delete retained.shadowCallRewrittenFrom;
@@ -585,6 +604,8 @@ export function addRequestLog(entry: RequestLogEntry) {
   }
   if (claudeCompatibility) retained.claudeCompatibility = claudeCompatibility;
   else if (retained !== entry) delete retained.claudeCompatibility;
+  if (jevDecision) retained.jevDecision = jevDecision;
+  else if (retained !== entry) delete retained.jevDecision;
   entry = retained;
   retainRequestLogEntry(entry);
   for (const observer of requestLogObserversForTests) {
@@ -661,7 +682,9 @@ export function addRequestLog(entry: RequestLogEntry) {
       // usage.jsonl, which is the surface the derived failure projection reads.
       ...normalizeRequestFailureAttribution(entry),
       ...(entry.routeDecision ? { routeDecision: entry.routeDecision } : {}),
+      ...(entry.jevDecision ? { jevDecision: entry.jevDecision } : {}),
       ...(entry.claudeCompatibility ? { claudeCompatibility: entry.claudeCompatibility } : {}),
+      ...(entry.protocolTrace ? { protocolTrace: entry.protocolTrace } : {}),
       ...(entry.conversationStateScrub === "account-change"
         ? { conversationStateScrub: "account-change" }
         : {}),
@@ -1504,6 +1527,9 @@ export function addFinalRequestLog(
   // the in-memory /api/logs row matches what usage.jsonl already stores.
   const shadowCallRewrittenFrom = sanitizeLogMetadataString(logCtx.shadowCallRewrittenFrom);
   const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(logCtx.claudeCompatibility);
+  const jevDecision = normalizePersistedJevDecision(logCtx.jevDecision);
+  // Keyed by the live attempt objects, not the detached copies above.
+  const protocolTrace = protocolTraceForRequest(logCtx, logCtx.attempts);
   addLog({
     requestId,
     ...(isLogicalRequestId(logicalRequestId) ? { logicalRequestId } : {}),
@@ -1563,7 +1589,9 @@ export function addFinalRequestLog(
     ...(logCtx.transportPhase ? { transportPhase: logCtx.transportPhase } : {}),
     ...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
     ...(logCtx.routeDecision ? { routeDecision: logCtx.routeDecision } : {}),
+    ...(jevDecision ? { jevDecision } : {}),
     ...(claudeCompatibility ? { claudeCompatibility } : {}),
+    ...(protocolTrace ? { protocolTrace } : {}),
     ...attribution,
   });
   // Formatted from the finalized snapshot, so the ring shows exactly what the ledger holds.
@@ -1583,73 +1611,6 @@ export function addFinalRequestLog(
   }
 }
 
-export function filterRequestLogs(logs: RequestLogEntry[], params: URLSearchParams): RequestLogEntry[] {
-  let filtered = logs;
-  const provider = params.get("provider")?.trim();
-  if (provider) {
-    filtered = filtered.filter(entry => entry.provider === provider
-      || entry.attempts?.some(attempt => attempt.provider === provider));
-  }
-  const conversationId = params.get("conversationId")?.trim() || params.get("conversation")?.trim();
-  if (conversationId) {
-    filtered = filtered.filter(entry => matchesLogConversationId(entry.conversationId, conversationId));
-  }
-  // #2704: there was no `model` clause at all, so `?model=x` was ACCEPTED and silently
-  // ignored -- worse than an error, because it yields wrong conclusions from output that
-  // looks correct. Attempts are matched for the same reason `provider` matches them: a
-  // request that failed over should be findable by the model that actually served it.
-  const model = params.get("model")?.trim();
-  if (model) {
-    filtered = filtered.filter(entry => entry.model === model
-      || entry.attempts?.some(attempt => attempt.model === model));
-  }
-  // #4057: "which account served this request" is the first question asked when one provider
-  // holds several accounts, and until now the only way to answer it was to grep usage.jsonl by
-  // hand. Attempts are matched for the same reason `provider` and `model` match them: when a
-  // request failed over between pool accounts, a search for the account that finally served it
-  // has to find that request, not only the account that first refused it.
-  const account = params.get("account")?.trim();
-  if (account) {
-    filtered = filtered.filter(entry => entry.accountLogLabel === account
-      || entry.attempts?.some(attempt => attempt.accountLogLabel === account));
-  }
-  const status = params.get("status")?.trim().toLowerCase();
-  if (status) {
-    filtered = /^[1-5]xx$/.test(status)
-      ? filtered.filter(entry => Math.floor(entry.status / 100) === Number(status[0]))
-      : filtered.filter(entry => String(entry.status) === status);
-  }
-  const tailRaw = params.get("tail")?.trim();
-  if (tailRaw) {
-    const tail = Number.parseInt(tailRaw, 10);
-    if (Number.isFinite(tail) && tail > 0) filtered = filtered.slice(-Math.min(tail, MAX_LOG_SIZE));
-  }
-  const offsetRaw = params.get("offset")?.trim();
-  const limitRaw = params.get("limit")?.trim();
-  if (limitRaw) {
-    const limit = Number.parseInt(limitRaw, 10);
-    const offset = offsetRaw ? Number.parseInt(offsetRaw, 10) : 0;
-    if (Number.isFinite(limit) && limit > 0) {
-      const capped = Math.min(limit, MAX_LOG_SIZE);
-      const startOffset = Number.isFinite(offset) && offset > 0 ? offset : 0;
-      const end = filtered.length - startOffset;
-      if (end <= 0) filtered = [];
-      else {
-        const begin = Math.max(0, end - capped);
-        filtered = filtered.slice(begin, end);
-      }
-    }
-  }
-  return filtered;
-}
-
-export function filteredRequestLogCount(logs: RequestLogEntry[], params: URLSearchParams): number {
-  const withoutPagination = new URLSearchParams(params);
-  withoutPagination.delete("limit");
-  withoutPagination.delete("offset");
-  return filterRequestLogs(logs, withoutPagination).length;
-}
-
 interface FinalizedUsageResult {
   usage?: OcxUsage;
   status: UsageStatus;

package/src/server/responses/adapter-delivery.ts

@@ -20,6 +20,7 @@ import {
   ResponseBodyInactivityError,
 } from "../../lib/response-body-inactivity";
 import { resolveStallTimeoutSec } from "../../stall-timeout";
+import { clientEncoderForDelivery, deliverClientEncodedResponse } from "../inference/client-encoder-delivery";
 
 /** One responsibility of the Responses request pipeline; state owners are explicit. */
 export async function deliverAdapterResponse(
@@ -114,6 +115,47 @@ export async function deliverAdapterResponse(
         })
       : eventStream;
     const { toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, toolSearchToolNames } = toolBridgeMaps;
+    // One completion owner for both deliveries: the bridge calls it from its terminal, the
+    // direct client encoder from the fold of the same events.
+    const onCompletedResponse = (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => {
+      commitReasoningReplayServingRoute();
+      rememberKiroDeliveredFinalAnswer(transportState.activeAdapter.name, response);
+      // Compaction turns must NOT enter the continuation cache: _rawBody still holds the full
+      // PRE-compaction history, and a later previous_response_id expansion would rehydrate the
+      // giant stale chain Codex just replaced.
+      if (!routedCompaction) {
+        rememberResponseState(
+          parsed._rawBody,
+          response,
+          continuationStateForResponse(providerState),
+          responseStateOptions(transportState.activeAdapter.name === "kiro"),
+        );
+      }
+      notifyResponseComplete(response);
+    };
+    const clientEncoder = clientEncoderForDelivery(options, logCtx, !!routedCompaction, transportState.activeAdapter.name);
+    if (clientEncoder) {
+      return deliverClientEncodedResponse({
+        encoder: clientEncoder,
+        events: guardedEventStream,
+        logCtx,
+        translatorBudget,
+        responseModelId: parsed._responseModelId ?? parsed.modelId,
+        adapterName: transportState.activeAdapter.name,
+        fold: {
+          replayCacheScope: parsed._reasoningReplayScope,
+          hideThinkingSummary: parsed.options.hideThinkingSummary,
+          toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, toolSearchToolNames,
+        },
+        stallTimeoutSec: config.stallTimeoutSec,
+        turnAdmissionLease: options.turnAdmissionLease,
+        ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
+        stopUpstream: () => { cancelResponseCompletion(); upstream.abort(); },
+        onStreamDone: cleanupUpstreamAbort,
+        onCompletedResponse,
+        bindUsage: usage => transportState.bindKeyUsageFromBridge(usage),
+      });
+    }
     const sseStream = bridgeToResponsesSSE(
       guardedEventStream, parsed._responseModelId ?? parsed.modelId, toolNsMap, freeformToolNames, toolSearchToolNames,
       () => { cancelResponseCompletion(); upstream.abort(); }, 2_000,
@@ -134,22 +176,7 @@ export async function deliverAdapterResponse(
           // Raw adapter usage, pre wire-normalization (see the runTurn branch above).
           transportState.bindKeyUsageFromBridge(usage);
         },
-        onCompletedResponse: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => {
-          commitReasoningReplayServingRoute();
-          rememberKiroDeliveredFinalAnswer(transportState.activeAdapter.name, response);
-          // Compaction turns must NOT enter the continuation cache: _rawBody still holds the full
-          // PRE-compaction history, and a later previous_response_id expansion would rehydrate the
-          // giant stale chain Codex just replaced.
-          if (!routedCompaction) {
-            rememberResponseState(
-              parsed._rawBody,
-              response,
-              continuationStateForResponse(providerState),
-              responseStateOptions(transportState.activeAdapter.name === "kiro"),
-            );
-          }
-          notifyResponseComplete(response);
-        },
+        onCompletedResponse,
       },
     );
     const bridgeTurnAc = new AbortController();

package/src/server/responses/agent-task-recovery.ts

@@ -2,6 +2,7 @@ import { createHash, createHmac, randomBytes } from "node:crypto";
 import { decodeJwtPayload, extractAccountId } from "../../oauth/chatgpt";
 import type { OcxConfig } from "../../types";
 import { boundedBodyDecodeFailure, readBoundedResponseBody } from "../../lib/bounded-body";
+import { isTransientUpstreamStatus, retryBackoffDelayMs, sleepWithAbort } from "../../lib/upstream-retry";
 import { isApiAuthRequired, isProxyAdmissionSecret } from "../auth-cors";
 import { MAX_AGENT_TASK_CIPHERTEXT_BYTES, MAX_AGENT_TASK_ENCRYPTED_PARTS, structurallyValidFernetTokens } from "./encrypted-payload";
 import {
@@ -34,12 +35,18 @@ const OPENAI_TOKEN_AUDIENCE = "https://api.openai.com/v1";
 const MAX_ASSIGNMENT_BYTES = 2 * 1024 * 1024;
 const MAX_RECOVERY_RESPONSE_BYTES = 4 * 1024 * 1024;
 const CACHE_SCOPE_KEY = randomBytes(32);
+// 1 initial send + up to 2 retries matches TRANSIENT_RETRY_MAX_ATTEMPTS; retries stay inside
+// the caller's deadline, admission scope, and shared flight (#3661).
+const MAX_RECOVERY_RETRIES = 2;
+const RECOVERY_RETRY_BASE_DELAY_MS = 500;
+const RECOVERY_RETRY_MAX_DELAY_MS = 2_000;
 
 export interface AgentTaskRecoveryOptions {
   enabled?: boolean;
   model?: string;
   timeoutMs?: number;
   cacheEntries?: number;
+  retries?: number;
 }
 
 export type AgentTaskRecoveryFailureReason =
@@ -67,6 +74,9 @@ export function agentTaskRecoveryConfig(config: OcxConfig): AgentTaskRecoveryOpt
     cacheEntries: Number.isFinite(raw.cacheEntries) && (raw.cacheEntries ?? 0) >= 1
       ? Math.min(512, Math.floor(raw.cacheEntries!))
       : 200,
+    retries: Number.isFinite(raw.retries) && (raw.retries ?? 0) >= 0
+      ? Math.min(MAX_RECOVERY_RETRIES, Math.floor(raw.retries!))
+      : 0,
   };
 }
 
@@ -448,20 +458,24 @@ function assignmentFromRecoverySse(raw: string, envelope: AgentEnvelope): string
     : null;
 }
 
-async function requestRecovery(
+interface RecoveryAttempt {
+  resolution: AgentTaskRecoveryResolution;
+  retryable: boolean;
+  retryHeaders?: Headers;
+}
+
+async function attemptRecovery(
   admission: RecoveryAdmission,
   envelope: AgentEnvelope,
   options: AgentTaskRecoveryOptions,
-  abortSignal?: AbortSignal,
-): Promise<AgentTaskRecoveryResolution> {
-  const controller = new AbortController();
-  const timeout = setTimeout(
-    () => controller.abort(new DOMException("Agent task recovery timed out", "TimeoutError")),
-    options.timeoutMs ?? 45_000,
-  );
-  const signal = abortSignal
-    ? AbortSignal.any([abortSignal, controller.signal])
-    : controller.signal;
+  signal: AbortSignal,
+  abortSignal: AbortSignal | undefined,
+  deadlineSignal: AbortSignal,
+): Promise<RecoveryAttempt> {
+  const terminal = (resolution: AgentTaskRecoveryResolution): RecoveryAttempt => ({
+    resolution,
+    retryable: false,
+  });
   try {
     const response = await fetch(RECOVERY_ENDPOINT, {
       method: "POST",
@@ -473,9 +487,13 @@ async function requestRecovery(
     if (!response.ok) {
       // A rejected or never-settling cancellation must not extend the recovery deadline.
       try { void response.body?.cancel().catch(() => undefined); } catch { /* already closed */ }
-      if (abortSignal?.aborted) return { recovered: false, reason: "recovery_aborted" };
-      if (controller.signal.aborted) return { recovered: false, reason: "recovery_timeout" };
-      return { recovered: false, reason: "recovery_http_rejected" };
+      if (abortSignal?.aborted) return terminal({ recovered: false, reason: "recovery_aborted" });
+      if (deadlineSignal.aborted) return terminal({ recovered: false, reason: "recovery_timeout" });
+      return {
+        resolution: { recovered: false, reason: "recovery_http_rejected" },
+        retryable: isTransientUpstreamStatus(response.status),
+        retryHeaders: response.headers,
+      };
     }
     const body = await readBoundedResponseBody(response, {
       signal,
@@ -485,18 +503,68 @@ async function requestRecovery(
       inactivityTimeoutMs: options.timeoutMs ?? 45_000,
       firstByteTimeoutMs: options.timeoutMs ?? 45_000,
     });
-    if (abortSignal?.aborted) return { recovered: false, reason: "recovery_aborted" };
-    if (controller.signal.aborted || body.timedOut) return { recovered: false, reason: "recovery_timeout" };
-    if (body.truncated || body.oversized || !body.displaySafe) return { recovered: false, reason: "recovery_invalid_output" };
+    if (abortSignal?.aborted) return terminal({ recovered: false, reason: "recovery_aborted" });
+    if (deadlineSignal.aborted || body.timedOut) return terminal({ recovered: false, reason: "recovery_timeout" });
+    if (body.truncated || body.oversized || !body.displaySafe) return terminal({ recovered: false, reason: "recovery_invalid_output" });
     const assignment = assignmentFromRecoverySse(body.text, envelope);
-    return assignment === null
+    return terminal(assignment === null
       ? { recovered: false, reason: "recovery_invalid_output" }
-      : { recovered: true, assignment };
+      : { recovered: true, assignment });
   } catch (error) {
-    if (abortSignal?.aborted) return { recovered: false, reason: "recovery_aborted" };
+    if (abortSignal?.aborted) return terminal({ recovered: false, reason: "recovery_aborted" });
     const decodeFailure = boundedBodyDecodeFailure(error);
-    if (controller.signal.aborted || decodeFailure === "timeout") return { recovered: false, reason: "recovery_timeout" };
-    return { recovered: false, reason: decodeFailure === "invalid_utf8" ? "recovery_invalid_output" : "recovery_transport_error" };
+    if (deadlineSignal.aborted || decodeFailure === "timeout") return terminal({ recovered: false, reason: "recovery_timeout" });
+    return decodeFailure === "invalid_utf8"
+      ? terminal({ recovered: false, reason: "recovery_invalid_output" })
+      : { resolution: { recovered: false, reason: "recovery_transport_error" }, retryable: true };
+  }
+}
+
+async function requestRecovery(
+  admission: RecoveryAdmission,
+  envelope: AgentEnvelope,
+  options: AgentTaskRecoveryOptions,
+  abortSignal?: AbortSignal,
+): Promise<AgentTaskRecoveryResolution> {
+  const controller = new AbortController();
+  const timeoutMs = options.timeoutMs ?? 45_000;
+  const deadline = Date.now() + timeoutMs;
+  const timeout = setTimeout(
+    () => controller.abort(new DOMException("Agent task recovery timed out", "TimeoutError")),
+    timeoutMs,
+  );
+  const signal = abortSignal
+    ? AbortSignal.any([abortSignal, controller.signal])
+    : controller.signal;
+  try {
+    // The configured bound is re-clamped here: callers may pass options that never went
+    // through agentTaskRecoveryConfig, and a larger value must not widen the outage window.
+    const retries = Number.isFinite(options.retries)
+      ? Math.max(0, Math.min(MAX_RECOVERY_RETRIES, Math.floor(options.retries!)))
+      : 0;
+    for (let attempt = 0; ; attempt += 1) {
+      const { resolution, retryable, retryHeaders } = await attemptRecovery(
+        admission, envelope, options, signal, abortSignal, controller.signal,
+      );
+      if (resolution.recovered || !retryable || attempt >= retries) return resolution;
+      // Retry-After is the provider's floor, not something our backoff cap may shorten.
+      // If honouring it would outlive the shared deadline, end with this failure rather
+      // than resend early into a refusal.
+      const delayMs = retryBackoffDelayMs(attempt, {
+        baseDelayMs: RECOVERY_RETRY_BASE_DELAY_MS,
+        maxDelayMs: RECOVERY_RETRY_MAX_DELAY_MS,
+        headers: retryHeaders,
+        retryAfterIsLowerBound: true,
+      });
+      if (delayMs >= deadline - Date.now()) return resolution;
+      try {
+        await sleepWithAbort(delayMs, signal);
+      } catch {
+        return abortSignal?.aborted
+          ? { recovered: false, reason: "recovery_aborted" }
+          : { recovered: false, reason: "recovery_timeout" };
+      }
+    }
   } finally {
     clearTimeout(timeout);
   }

package/src/server/responses/codex-ws-exchange.ts

@@ -114,6 +114,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     let pongs = 0;
     let sentAt: number | null = null;
     let firstFrameAt: number | null = null;
+    let firstResponseAt: number | null = null;
     // Numeric close code for the durable stage record; the reason string stays
     // out of it on purpose (#4191 content-free contract).
     let closeCode: number | null = null;
@@ -170,6 +171,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       controlFrames,
       relayedEvents,
       firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null,
+      firstResponseMs: sentAt !== null && firstResponseAt !== null ? Math.max(0, firstResponseAt - sentAt) : null,
       elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null,
       pings,
       pongs,
@@ -188,6 +190,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       controlFrames,
       relayedEvents,
       firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null,
+      firstResponseMs: sentAt !== null && firstResponseAt !== null ? Math.max(0, firstResponseAt - sentAt) : null,
       elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null,
       pings,
       pongs,
@@ -481,6 +484,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       if (!controlFrame && !type.startsWith("response.") && type !== "error") return;
       let steeringEnded = false;
       if (!controlFrame) {
+        firstResponseAt ??= Date.now();
         try {
           if (nativeControl) steeringEnded = nativeControl.observe(normalized.payload);
           else correlation?.accept(normalized.payload);

package/src/server/responses/codex-ws-wire.ts

@@ -176,6 +176,14 @@ export type CodexWsFailureStage = {
   relayedEvents: number;
   /** Milliseconds from send to the first upstream frame; null when none arrived. */
   firstFrameMs: number | null;
+  /**
+   * Milliseconds from send to the first non-control Responses event (a
+   * `response.*` or `error` frame the relay would hand downstream); null when
+   * none arrived. `firstFrameMs` alone cannot separate "the peer answered with
+   * quota metadata and went quiet" from "the peer was still working": the
+   * first measures any frame, this one measures the turn's own start (#4191).
+   */
+  firstResponseMs: number | null;
   /** Milliseconds from send to this failure; null when the failure predates the send. */
   elapsedMs: number | null;
   /** Liveness pings the exchange sent while waiting for the first response event. */
@@ -271,7 +279,8 @@ export function codexWsFailureDetail(stage: CodexWsFailureStage): string {
   return ` [cause=${classifyCodexWsFailure(stage)} request=${stage.requestBytes}B`
     + ` sent=${stage.sent ? "yes" : "no"} frames=${stage.upstreamFrames}`
     + ` control=${stage.controlFrames} relayed=${stage.relayedEvents}`
-    + ` first-frame=${duration(stage.firstFrameMs)} elapsed=${duration(stage.elapsedMs)}`
+    + ` first-frame=${duration(stage.firstFrameMs)} first-response=${duration(stage.firstResponseMs)}`
+    + ` elapsed=${duration(stage.elapsedMs)}`
     + ` pings=${stage.pings} pongs=${stage.pongs}]`;
 }