@bitkyc08/opencodex 2.58.0 → 2.59.0

package/src/server/responses/passthrough-dispatch.ts

@@ -11,6 +11,7 @@ import type { PreparedResponsesRequest } from "./request-prepare";
 import type { ResponsesTransport } from "./request-transport";
 import type { ResponsesEffects } from "./response-effects";
 import type { ResponsesSendBudget } from "./request-send-budget";
+import { transientSendCapFor } from "./request-send-budget";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { codexSafetyBufferingFilterOptions, terminalStatusFromParsed } from "../relay";
 import { imageGenToolCallAliases } from "../responses-image-gen-repair";
@@ -68,6 +69,7 @@ import {
   sealRequestAttemptIdentity,
   recordAttemptCredentialSource,
 } from "../request-log";
+import { noteAttemptRecoveryWithheld } from "../request-log";
 import {
   upstreamHostHealthKey,
   normalizeUpstreamHostCircuitThreshold,
@@ -91,11 +93,15 @@ import {
   usesCodexForwardPoolAuth,
   codexWsQuotaObserver,
   isFixedCodexAccount,
-  shouldRetryCodexPoolAccountModel400,
+  codexPoolAccountModel400Denial,
   shouldRetryCodexPoolAccountQuota,
   shouldRetryCodexPoolAccountTransient,
   retryCodexPoolOnAlternateAccount,
 } from "./core-codex-account";
+import {
+  clearCodexModelDenialEvidence,
+  recordCodexModelDenialEvidence,
+} from "../../codex/model-entitlements";
 import { readCodexWsStage } from "./codex-ws-wire";
 import { linkAbortSignal } from "./core-lifetime";
 import type { CodexAuthContext } from "../../codex/auth-context";
@@ -105,9 +111,8 @@ import {
   SendBudgetExhaustedError,
   fetchWithTransientRetry,
   applyUpstreamRecoveryInit,
-  TRANSIENT_RETRY_MAX_ATTEMPTS,
   isNonReplayableResponse,
-  prepareSameTarget429Wait,
+ prepareSameTarget429Wait,
   sleepWithAbort,
 } from "../../lib/upstream-retry";
 import { mapCodexAuthContextErrorToResponse } from "./codex-auth-error";
@@ -115,7 +120,11 @@ import { classifyTransportFailureKind, transportErrorCode } from "../../lib/upst
 import { recordCodexUpstreamOutcome } from "../../codex/routing";
 import { describeUpstreamConnectFailure } from "./upstream-error";
 import type { OpaqueBlobRecoveryGuard } from "./core-opaque-recovery";
-import { rateLimitRetryPolicyFor, rateLimitRetryDelayMs } from "../../providers/key-failover";
+import {
+  rateLimitRetryPolicyFor,
+  rateLimitRetryDelayMs,
+  transientRetryPolicyFor,
+} from "../../providers/key-failover";
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { resolveWireProtocolOverride } from "../adapter-resolve";
 import { refreshPoolForwardAuth, refreshNativeMainForwardAuth, withClaudeNativeSession } from "./core-auth";
@@ -198,6 +207,7 @@ export async function preparePassthroughExchange(
     | "reserveCredentialHop"
     | "pendingHopPermit"
     | "workflowRootId"
+    | "sendsUsed"
   >,
 ) {
   const { config, logCtx, options, req } = requestContext;
@@ -665,6 +675,33 @@ export async function preparePassthroughExchange(
     linkAbortSignal(upstream, options.abortSignal);
     const connectMs = config.connectTimeoutMs ?? 200_000;
     let upstreamResponse: Response;
+    /**
+     * This leg's transient-5xx ladder cap, from the provider's own `transientRetryOn5xx`.
+     *
+     * The lane used to pass `TRANSIENT_RETRY_MAX_ATTEMPTS` at every call site, so an operator who
+     * configured the option on a key-auth `openai-responses` provider changed nothing in either
+     * direction, while the same provider on `openai-chat` was tuned normally. That asymmetry is
+     * #4893. The gate in `transientRetryPolicyFor` returns null for OAuth and forward providers,
+     * so the ChatGPT pool keeps exactly the ladder it has always had.
+     *
+     * Read per call rather than captured once, for two reasons. `route.provider` is reassigned
+     * inside the recovery loop by credential rotation and transport resolution, so a hoisted
+     * policy could outlive the provider row it came from. And the configured value is a total for
+     * the whole request, so it has to be measured against what the request has already sent at
+     * the moment each leg asks.
+     *
+     * Still bounded by the request: every site feeds this to `remainingTransientSendBudget` or
+     * `recoverySendAllowance`, which intersect it with the request-wide base allowance. So a
+     * provider can narrow this request's sends exactly and cannot widen the bound that exists to
+     * stop per-request amplification (#4546).
+     */
+    const transientSendPolicy = () => transientRetryPolicyFor(route.provider);
+    const transientSendAttempts = (): number => transientSendCapFor(
+      transientSendPolicy()?.attempts,
+      sendBudgetState.sendsUsed,
+    );
+    const configuredTransientSendBudgetExhausted = (): boolean =>
+      transientSendPolicy() !== null && transientSendAttempts() === 0;
     /**
      * Refuse a built body that exceeds the operator's configured ceiling, before it is sent.
      *
@@ -804,7 +841,7 @@ export async function preparePassthroughExchange(
             // retry wrapper replaces — proves the host was reached (#914 review).
             .then(adoptObservedResponse);
         },
-        { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(TRANSIENT_RETRY_MAX_ATTEMPTS), onSendsConsumed: noteTransientSends },
+        { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends },
       );
     } catch (err) {
       return transportFailureResponse(err);
@@ -864,14 +901,15 @@ export async function preparePassthroughExchange(
       recordAttemptCredentialSource(logCtx.activeAttempt, route.providerName, route.provider, retryAdapter.name);
       const rebuiltBodyRefusal = refuseOversizedOutboundBody(request);
       if (rebuiltBodyRefusal) return { failed: rebuiltBodyRefusal };
-      // The base allowance is spent first; once it is gone this leg may still draw the one
-      // shared final-recovery reserve, which is what keeps a validated sanitized rebuild
-      // after a 5xx streak alive at four total sends instead of dying at three. Reserved
-      // outside the try so the finally can hand it back if the leg never reached its send.
+      // The base allowance is spent first. An unconfigured provider may then draw the one shared
+      // final-recovery reserve, which keeps a validated sanitized rebuild after a 5xx streak alive
+      // at four total sends instead of dying at three. An explicit provider total cannot widen.
+      // Reserve outside the try so the finally can hand it back if the leg never reaches its send.
       const allowance = recoverySendAllowance(
-        TRANSIENT_RETRY_MAX_ATTEMPTS,
+        transientSendAttempts(),
         recoveryClassFor(recovery),
         `${route.providerName}|${route.modelId}|${recovery}`,
+        { allowFinalRecoveryReserve: transientSendPolicy() === null },
       );
       try {
         return await fetchWithTransientRetry(
@@ -1033,7 +1071,7 @@ export async function preparePassthroughExchange(
       // Refused here, before the 401 body is cancelled: once it is gone the request can only
       // answer with a synthetic 502, which would report a proxy budget decision as an upstream
       // fault and throw away the credential evidence the client needs.
-      && !sendBudgetExhausted()
+      && !sendBudgetExhausted(transientSendAttempts())
     ) {
       oauth401ReplayAttempted = true;
       try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
@@ -1134,7 +1172,7 @@ export async function preparePassthroughExchange(
               route.provider.authMode === "forward")
               .then(adoptObservedResponse);
           },
-          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(TRANSIENT_RETRY_MAX_ATTEMPTS), onSendsConsumed: noteTransientSends },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends },
         );
       } catch (err) {
         return transportFailureResponse(err);
@@ -1145,13 +1183,13 @@ export async function preparePassthroughExchange(
 
     // Native Responses returns before the generic adapter's OAuth rotation loop. Keep
     // the same quorum, cooldown and request budget here, before any client bytes flow.
-    if (
-      upstreamResponse.status === 429
+   if (
+     upstreamResponse.status === 429
       // Not a provider rate limit when this proxy synthesized it for a refused reset
       // replay; rotating accounts on it would re-send an inference that may already
       // have run and would cool down an account that refused nothing.
       && !isNonReplayableResponse(upstreamResponse)
-      && transportState.genericFailoverAccountId
+     && transportState.genericFailoverAccountId
       && transportState.genericFailovers < GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST
       && isGenericOAuthFailoverEnabled(config, route.providerName)
     ) {
@@ -1167,6 +1205,8 @@ export async function preparePassthroughExchange(
         const nextAccountId = rotateGenericOAuthAccountOn429(
           config, route.providerName, transportState.genericFailoverAccountId,
           upstreamResponse.headers.get("retry-after"),
+          Date.now(),
+          route.modelId,
         );
         let snapshot: OAuthAccessSnapshot | undefined;
         if (nextAccountId) {
@@ -1194,6 +1234,11 @@ export async function preparePassthroughExchange(
         }
         // No credential moved, so the reservation costs nothing.
         hop.permit?.release();
+      } else {
+        // Rotation was available -- the roster cap above admitted it -- and the shared request
+        // budget refused. Recorded so a one-send log is not read as "nothing was eligible",
+        // which is the ambiguity this attribution exists to remove (#5044).
+        noteAttemptRecoveryWithheld(logCtx.activeAttempt, "rotation-send-budget");
       }
     }
 
@@ -1203,15 +1248,15 @@ export async function preparePassthroughExchange(
     // immediately with no same-key replay. Pre-stream only — nothing has been relayed yet, so
     // the replay is lossless (same invariant as the recovery loop). Forward/OAuth providers
     // keep their pool logic below (rateLimitRetryPolicyFor returns null for them).
-    while (
-      upstreamResponse.status === 429
+   while (
+     upstreamResponse.status === 429
       && !isNonReplayableResponse(upstreamResponse)
-      && rateLimitPolicy !== null
+     && rateLimitPolicy !== null
       && rateLimitRetries < rateLimitPolicy.attempts
       // Checked here rather than inside the helper: prepareSameTarget429Wait releases the 429
       // body, so a refusal discovered after the wait can no longer return the real rate-limit
       // answer and would surface a synthetic 502 instead.
-      && !sendBudgetExhausted()
+      && !sendBudgetExhausted(transientSendAttempts())
     ) {
       rateLimitRetries += 1;
       // Release unread body + deliberate wait via the shared same-target helper.
@@ -1259,7 +1304,7 @@ export async function preparePassthroughExchange(
               route.provider.authMode === "forward")
               .then(adoptObservedResponse);
           },
-          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(TRANSIENT_RETRY_MAX_ATTEMPTS), onSendsConsumed: noteTransientSends },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends },
         );
       } catch (err) {
         return transportFailureResponse(err);
@@ -1291,11 +1336,25 @@ export async function preparePassthroughExchange(
 
     if (usesCodexForwardPoolAuth(admissionState.authCtx, route.provider)) {
       let poolRetryOutcome: number | undefined;
-      if (await shouldRetryCodexPoolAccountModel400(
+      // A success is the freshest evidence there is about this pair, and it outranks any earlier
+      // refusal: whatever the entitlement was when upstream declined, it is not that now. Both
+      // ids are cleared because the wire model can differ from the routed one.
+      if (upstreamResponse.ok) {
+        clearCodexModelDenialEvidence(admissionState.authCtx.accountId, route.modelId);
+        clearCodexModelDenialEvidence(admissionState.authCtx.accountId, parsed.modelId);
+      }
+      const model400Denial = await codexPoolAccountModel400Denial(
         upstreamResponse,
         route.modelId,
         options.abortSignal,
-      )) {
+        parsed.modelId,
+      );
+      if (model400Denial !== undefined) {
+        // Spend this refusal on more than one retry. It is the account's own authenticated
+        // answer about this model, and the roster cache that selection otherwise reads expires
+        // five minutes after a catalog sync fills it -- so without remembering this, the next
+        // request selects the same account on quota alone and takes the same 400 (#4906).
+        recordCodexModelDenialEvidence(admissionState.authCtx.accountId, model400Denial);
         poolRetryOutcome = 400;
       } else if (!admissionState.authCtx.fixedAccount && await shouldRetryCodexPoolAccountQuota(
         upstreamResponse,
@@ -1365,18 +1424,20 @@ export async function preparePassthroughExchange(
     // eviction, or an older transcript). Inspect only a bounded clone of a 4xx whose exact outbound
     // Responses body still carries opaque state, then rebuild once through the ordinary adapter
     // sanitation path. A second rejection falls through unchanged because the guard stays armed.
-    const opaqueBlobRecovery = await attemptOpaqueBlobRecovery({
-      response: upstreamResponse,
-      outboundBody: request.body,
-      adapterName: transportState.adapter.name,
-      parsed,
-      guard: opaqueBlobRecoveryGuard,
-      signal: upstream.signal,
-    }, rebuildAndRefetch);
-    if (opaqueBlobRecovery.kind === "failed") return opaqueBlobRecovery.response;
-    if (opaqueBlobRecovery.kind === "recovered") {
-      upstreamResponse = opaqueBlobRecovery.response;
-      continue passthroughRecovery;
+    if (!configuredTransientSendBudgetExhausted()) {
+      const opaqueBlobRecovery = await attemptOpaqueBlobRecovery({
+        response: upstreamResponse,
+        outboundBody: request.body,
+        adapterName: transportState.adapter.name,
+        parsed,
+        guard: opaqueBlobRecoveryGuard,
+        signal: upstream.signal,
+      }, rebuildAndRefetch);
+      if (opaqueBlobRecovery.kind === "failed") return opaqueBlobRecovery.response;
+      if (opaqueBlobRecovery.kind === "recovered") {
+        upstreamResponse = opaqueBlobRecovery.response;
+        continue passthroughRecovery;
+      }
     }
 
     const recoveryContentType = upstreamResponse.headers.get("content-type")?.toLowerCase() ?? "";
@@ -1384,6 +1445,7 @@ export async function preparePassthroughExchange(
       && !!upstreamResponse.body
       && (recoveryContentType.includes("text/event-stream") || (!recoveryContentType && parsed.stream))
       && !opaqueBlobRecoveryGuard.attempted
+      && !configuredTransientSendBudgetExhausted()
       && outboundResponsesBodyCarriesEncryptedFunctionOutput(request.body);
     if (streamedFunctionOutputCandidate) {
       const preflightLog: RequestLogContext = { model: logCtx.model, provider: logCtx.provider };
@@ -1400,19 +1462,21 @@ export async function preparePassthroughExchange(
       if (options.abortSignal?.aborted) return transportFailureResponse(options.abortSignal.reason);
       upstreamResponse = preflight.response;
       if (preflight.kind === "failed") {
-        const streamedOpaqueRecovery = await attemptOpaqueBlobRecovery({
-          response: upstreamResponse,
-          outboundBody: request.body,
-          adapterName: transportState.adapter.name,
-          parsed,
-          guard: opaqueBlobRecoveryGuard,
-          signal: upstream.signal,
-        }, rebuildAndRefetch);
-        if (streamedOpaqueRecovery.kind === "failed") return streamedOpaqueRecovery.response;
-        if (streamedOpaqueRecovery.kind === "recovered") {
-          resetStreamedOpaqueBlobLogContext(logCtx);
-          upstreamResponse = streamedOpaqueRecovery.response;
-          continue passthroughRecovery;
+        if (!configuredTransientSendBudgetExhausted()) {
+          const streamedOpaqueRecovery = await attemptOpaqueBlobRecovery({
+            response: upstreamResponse,
+            outboundBody: request.body,
+            adapterName: transportState.adapter.name,
+            parsed,
+            guard: opaqueBlobRecoveryGuard,
+            signal: upstream.signal,
+          }, rebuildAndRefetch);
+          if (streamedOpaqueRecovery.kind === "failed") return streamedOpaqueRecovery.response;
+          if (streamedOpaqueRecovery.kind === "recovered") {
+            resetStreamedOpaqueBlobLogContext(logCtx);
+            upstreamResponse = streamedOpaqueRecovery.response;
+            continue passthroughRecovery;
+          }
         }
         logCtx.upstreamError = preflightLog.upstreamError;
         logCtx.terminalHttpStatus = preflightLog.terminalHttpStatus;
@@ -1431,6 +1495,7 @@ export async function preparePassthroughExchange(
         upstream.signal,
       );
       if (uploadRejectionBody !== undefined
+        && !configuredTransientSendBudgetExhausted()
         && isTransientConsoleGoUploadRejection({
           status: upstreamResponse.status,
           errorBody: uploadRejectionBody,
@@ -1469,7 +1534,7 @@ export async function preparePassthroughExchange(
             requested: parsed.options.reasoning,
             rejectionText,
           });
-      if (downgrade) {
+      if (downgrade && !configuredTransientSendBudgetExhausted()) {
         reasoningEffortDowngradeGuard.attempted = true;
         parsed.options.reasoning = downgrade.effort;
         try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }

package/src/server/responses/passthrough-execution.ts

@@ -10,6 +10,8 @@ import type { ResponsesEffects } from "./response-effects";
 import type { ResponsesSendBudget } from "./request-send-budget";
 import { preparePassthroughExchange } from "./passthrough-dispatch";
 import { deliverPassthroughResponse } from "./passthrough-delivery";
+import { guardDirectPassthroughBodyInactivity } from "../../lib/response-body-inactivity";
+import { resolveStallTimeoutSec } from "../../stall-timeout";
 import { releaseUpstreamHostAdmission } from "../../codex/upstream-host-health";
 import { releaseCodexAuthContextProbeLease } from "../../codex/auth-context";
 
@@ -36,7 +38,7 @@ export async function executePassthroughResponse(
       sendBudgetState,
     );
     if (nativeExchange instanceof Response) return nativeExchange;
-    return await deliverPassthroughResponse(
+    const response = await deliverPassthroughResponse(
       requestContext,
       admissionState,
       requestState,
@@ -45,6 +47,14 @@ export async function executePassthroughResponse(
       responseEffects,
       nativeExchange,
     );
+    // Delivery has already classified SSE (including a missing upstream content type)
+    // and consumed bounded JSON/errors. Guard only its remaining direct body, outside
+    // the relay/lifetime wrappers so their prefetch cannot arm our inactivity clock.
+    return guardDirectPassthroughBodyInactivity(
+      response,
+      nativeExchange.upstream.signal,
+      resolveStallTimeoutSec(requestContext.config.stallTimeoutSec) * 1000,
+    );
   } finally {
     if (nativeHostState.lease) {
       releaseUpstreamHostAdmission(nativeHostState.lease);

package/src/server/responses/request-prepare.ts

@@ -105,7 +105,9 @@ import { hasUnmappedRoutedCustomToolOutput } from "../../responses/custom-tool-c
 import { PROVIDER_OWNED_CONTINUATION_WIRES, resolvedAdapterWire } from "../../responses/continuation-ownership";
 import {
   isCodexReserveHelperUnsupported,
+  isCodexReserveOptInMissing,
   CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE,
+  CODEX_RESERVE_OPT_IN_REQUIRED_MESSAGE,
 } from "../../codex/loopback-target";
 import { checkComboTargetInputAdmission, checkInputAdmission } from "./input-admission";
 import { nativeContextLimits } from "../../codex/catalog";
@@ -231,6 +233,10 @@ export async function prepareResponsesRequest(
     (body as { input?: unknown } | undefined)?.input,
   );
   const inboundClientThreadId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  // The request's OWN thread, which `x-codex-parent-thread-id` is not: parallel children of one
+  // parent all present the same parent id. `codexConversationIdentity` already reads this header
+  // for the same reason, and a surface that must tell siblings apart needs it too (#5033).
+  const inboundOwnThreadId = req.headers.get("thread-id")?.trim() || undefined;
   const cursorClientThreadId = codexPoolAffinityKey(req.headers);
   const originalBody = body;
   if (options.comboReplaySnapshot) {
@@ -303,6 +309,7 @@ export async function prepareResponsesRequest(
       ? options.comboReplaySnapshot.providerContinuation
       : previousResponseProviderState(parsed.previousResponseId);
     if (providerContinuationCandidate) parsed._providerContinuationCandidate = providerContinuationCandidate;
+    if (inboundOwnThreadId) parsed._codexOwnThreadId = inboundOwnThreadId;
     if (inboundClientThreadId) {
       parsed._clientThreadId = inboundClientThreadId;
     } else if (
@@ -699,6 +706,7 @@ export async function prepareResponsesRequest(
             "_providerContinuationOwner",
             "_cursorConversationId",
             "_clientThreadId",
+            "_codexOwnThreadId",
             "_promptCacheKeyIsSharedCohort",
             "_cursorClientThreadId",
             "_reasoningReplayScope",
@@ -976,6 +984,27 @@ export async function prepareResponsesRequest(
       options.admission, options.visionDescribeTerminal === true)) {
     return formatErrorResponse(400, "invalid_request_error", CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE);
   }
+  // #4940: the opt-in is off, so every Reserve affordance in this process is inert -- no catalog
+  // row, no main-credential substitution, no authorization handshake, and no `luna-reserve` header
+  // on the send. Forwarding `gpt-reserve` as an ordinary native model therefore buys nothing but a
+  // 429 "The usage limit has been reached", which names neither the real cause nor the setting the
+  // operator would have to change. Refuse here instead, on the same terms and in the same place as
+  // the helper refusal above: after alias/combo resolution, before auth, host-circuit budget or any
+  // upstream byte.
+  //
+  // Two narrowings beyond the predicate, both about not answering a question this refusal cannot
+  // answer correctly. A terminal vision/search helper is excluded because enabling the opt-in would
+  // not make it work -- it would produce the helper refusal above instead, so telling that caller to
+  // enable the flag is advice that does not hold. Non-native inbound wires are excluded because a
+  // `gpt-reserve` selector reaching us over Chat or Anthropic Messages is an operator-authored
+  // route (a `claudeCode.modelMap` entry, say), not a Codex client that was forced onto Reserve by
+  // its own usage snapshot, and that route keeps whatever behavior it has today.
+  if (inboundWire === "responses"
+    && options.visionDescribeTerminal !== true
+    && isCanonicalOpenAiForwardProvider(route.provider)
+    && isCodexReserveOptInMissing(options.codexAuthPolicy ?? config, route.modelId, options.admission)) {
+    return formatErrorResponse(400, "invalid_request_error", CODEX_RESERVE_OPT_IN_REQUIRED_MESSAGE);
+  }
   // Refuse an input that cannot plausibly fit the model context window before spending auth,
   // circuit budget, or upstream bandwidth on a turn the provider will reject anyway (#1412).
   //

package/src/server/responses/request-send-budget.ts

@@ -1,9 +1,13 @@
 import type { ResponsesRequestContext } from "./core-options";
 import { createRequestExecutionBudget, isRequestExecutionBudget } from "../../lib/request-execution-budget";
-import { chargeWorkflowSends, workflowSendCeilingReached } from "../../lib/workflow-budget";
+import {
+  chargeWorkflowSends,
+  workflowSendCeilingReached,
+  workflowSpendCeilingReached,
+} from "../../lib/workflow-budget";
 import { workflowRefusalResponse } from "../workflow-refusal";
-import type { AttemptRecoveryKind } from "../../usage/log";
-import { noteAttemptSend } from "../request-log";
+import type { AttemptRecoveryKind, AttemptRecoveryWithheld } from "../../usage/log";
+import { noteAttemptRecoveryWithheld, noteAttemptSend } from "../request-log";
 import { TRANSIENT_RETRY_MAX_ATTEMPTS } from "../../lib/upstream-retry";
 import type {
   DispatchDecision,
@@ -13,6 +17,28 @@ import type {
   SingleUseDispatchPermit,
 } from "../../lib/request-execution-budget";
 
+/**
+ * The transient-5xx ladder cap for ONE leg, given the provider's configured request total.
+ *
+ * `remainingTransientSendBudget(cap)` treats `cap` as a ceiling on what REMAINS, which is the
+ * right shape for the fixed constant: every leg may ask for up to three, and the request-wide
+ * base allowance is what actually bounds the total. A configured `transientRetryOn5xx.attempts`
+ * is documented as the total for one request including the first send, so it has to be reduced
+ * by what the request already sent before it is intersected with that allowance. Passing it
+ * straight through would make it a per-leg ceiling instead, and a request configured at one send
+ * could still reach upstream again on a recovery leg (#4893).
+ *
+ * An absent policy returns the constant unchanged, so a provider that configures nothing behaves
+ * exactly as it does today at every call site.
+ */
+export function transientSendCapFor(
+  configuredAttempts: number | undefined,
+  sendsUsed: number,
+): number {
+  if (configuredAttempts === undefined) return TRANSIENT_RETRY_MAX_ATTEMPTS;
+  return Math.max(0, configuredAttempts - Math.max(0, sendsUsed));
+}
+
 /** Owns the shared request send counter and recovery permits. */
 export function createResponsesSendBudget(
   requestContext: Pick<ResponsesRequestContext, "options" | "req" | "logCtx">,
@@ -45,6 +71,22 @@ export function createResponsesSendBudget(
     // marked synthetic rather than reading as a request that vanished with zero sends.
     return workflowRefusalResponse("workflow-sends-exhausted", logCtx, undefined, workflowRootId);
   }
+  // The token ceiling asked at the same seam, for the same reason the count one is asked here.
+  // Without it a spent root reaches the dispatch ladder, is refused by the ledger at the first
+  // physical send, and answers with the generic send-budget error every exhausted request
+  // returns -- a refusal an operator cannot tell from an ordinary budget exhaustion, on a
+  // ceiling they configured themselves. Asked before dispatch, it names the scope and the
+  // number instead. Returns undefined and touches no ledger when no ceiling is configured.
+  const spentCeiling = workflowSpendCeilingReached(workflowRootId);
+  if (spentCeiling) {
+    return workflowRefusalResponse(
+      "workflow-spend-exhausted",
+      logCtx,
+      undefined,
+      workflowRootId,
+      spentCeiling,
+    );
+  }
   // No floor. Math.max(1, ...) meant an exhausted request still funded one send on every
   // recovery leg, so a bounded per-leg allowance never became a bounded per-request one.
   const remainingTransientSendBudget = (budget: number): number =>
@@ -71,8 +113,28 @@ export function createResponsesSendBudget(
     if (send.ordinal <= 1) return;
     noteAttemptSend(logCtx.activeAttempt, inputTokens, send.recovery);
   };
-  const sendBudgetExhausted = (): boolean =>
-    remainingTransientSendBudget(TRANSIENT_RETRY_MAX_ATTEMPTS) === 0;
+  /**
+   * Records a recovery an adapter was ready to make and the budget refused.
+   *
+   * No send happened, so this deliberately does not touch `sendCount`. It is the other half of
+   * the pair that makes a one-send log readable: no recovery kind AND no withheld reason means
+   * nothing was eligible; a withheld reason means something was (#5044).
+   */
+  const noteAdapterRecoveryWithheld = (withheld: { reason: AttemptRecoveryWithheld }): void => {
+    noteAttemptRecoveryWithheld(logCtx.activeAttempt, withheld.reason);
+  };
+  /**
+   * Whether this request has any base send left under `cap`.
+   *
+   * The cap is a parameter because a lane that reads a provider's configured
+   * `transientRetryOn5xx` ladder has to ask this question at the SAME cap its sends use.
+   * Asking at the constant while dispatching at a configured value lets a provider with
+   * headroom be told it is exhausted, and lets one configured below the constant pass this
+   * check and then be refused at the send (#4893). Defaulted, so every existing caller keeps
+   * the constant it already used.
+   */
+  const sendBudgetExhausted = (cap: number = TRANSIENT_RETRY_MAX_ATTEMPTS): boolean =>
+    remainingTransientSendBudget(cap) === 0;
   /**
    * A credential hop reserves the send its own replay will make, and that replay is a recovery
    * leg. The leg must SPEND the hop's reservation instead of taking a second one: the
@@ -113,16 +175,22 @@ export function createResponsesSendBudget(
    * The base allowance is spent first. Once it is gone a recovery class may still draw the
    * single shared final-recovery reserve -- which is what keeps the validated sanitized rebuild
    * after a 5xx streak alive at four total sends -- but an account move and a rebuild cannot
-   * each take one. `countedExternally` is set because these legs run through the retry helper,
-   * which reports the same send again through `onSendsConsumed`.
+   * each take one. A caller with an exact provider total can suppress that reserve. The
+   * `countedExternally` flag exists because these legs run through the retry helper, which reports
+   * the same send again through `onSendsConsumed`.
    */
   const recoverySendAllowance = (
     cap: number,
     sendClass: SendClass,
     targetKey: string,
+    options: { allowFinalRecoveryReserve?: boolean } = {},
   ): { attempts: number; permit?: SingleUseDispatchPermit } => {
     const base = remainingTransientSendBudget(cap);
     if (base > 0) return { attempts: base };
+    // A provider-configured transient total is an exact physical-send ceiling. Once it is
+    // exhausted, the request-wide recovery reserve must not silently widen it. The default stays
+    // permissive so unconfigured providers retain the guarded profile's fourth recovery send.
+    if (options.allowFinalRecoveryReserve === false) return { attempts: 0 };
     if (pendingHopPermit) {
       const hopPermit = pendingHopPermit;
       pendingHopPermit = undefined;
@@ -178,9 +246,18 @@ export function createResponsesSendBudget(
     workflowRootId,
     noteTransientSends,
     remainingTransientSendBudget,
+    /**
+     * Physical sends this logical request has already made.
+     *
+     * A live getter, not a snapshot: it is read once per dispatch leg to resolve a configured
+     * ladder, and a value frozen at construction would answer for a request that had sent
+     * nothing.
+     */
+    get sendsUsed(): number { return sendBudget.used; },
     adapterSendBudget,
     adapterDispatchBudget,
     noteAdapterPhysicalSend,
+    noteAdapterRecoveryWithheld,
     sendBudgetExhausted,
     get pendingHopPermit(): SingleUseDispatchPermit | undefined {
       return pendingHopPermit;

package/src/server/responses/request-sidecar-auth.ts

@@ -126,18 +126,26 @@ export async function prepareResponsesSidecarAuth(
     });
   const recordSidecarOutcome = openAiSidecar?.recordOutcome;
   if (visionPlan) {
-    await describeImagesInPlace(
-      parsed,
-      visionPlan,
-      openAiSidecar?.headers ?? requestState.selectedForwardHeaders,
-      options.abortSignal,
-      recordSidecarOutcome,
-      translatorBudget,
-    );
+    try {
+      await describeImagesInPlace(
+        parsed,
+        visionPlan,
+        openAiSidecar?.headers ?? requestState.selectedForwardHeaders,
+        options.abortSignal,
+        recordSidecarOutcome,
+        translatorBudget,
+      );
+    } finally {
+      // Local validation can reject every image before the sidecar fetch records an outcome.
+      // Vision-only turns must hand that unused cooldown probe back; when a fetch did run the
+      // outcome already consumed it, so this generation-bound release is a safe no-op.
+      if (!needsOpenAiSearch) openAiSidecar?.releaseProbeLease?.();
+    }
   } else if (requiresVisionPreprocessing(config, route.provider, route.modelId, route.providerName)) {
     // Image capability is not positively proven but no sidecar plan is dispatchable: fail closed.
     // Never forward raw image bytes to an unverified upstream.
     stripImagesInPlace(parsed, translatorBudget);
+    if (!needsOpenAiSearch) openAiSidecar?.releaseProbeLease?.();
   }
 
   return {