@bitkyc08/opencodex 2.56.0 → 2.57.0

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

@@ -35,6 +35,7 @@ import {
   codexPoolAffinityKey,
   previewCodexPoolLineage,
   applyCodexAuthContextToProvider,
+  hasCallerCodexBearer,
 } from "../../codex/auth-context";
 import {
   copyPreviousResponseReplayProvenance,
@@ -84,7 +85,11 @@ import {
   canPassThroughEncryptedV2AgentTask,
   applyFinalRouteRequestNormalization,
 } from "./core-normalize";
-import { resolveCodexModelEntitlements } from "../../codex/model-entitlements";
+import {
+  cachedDeniedCodexAccountIdsForModel,
+  resolveCodexModelEntitlements,
+} from "../../codex/model-entitlements";
+import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/main-account";
 import {
   previewCodexAccountForRequest,
   codexQuotaScopeForModel,
@@ -101,7 +106,7 @@ import {
   isCodexReserveHelperUnsupported,
   CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE,
 } from "../../codex/loopback-target";
-import { checkInputAdmission } from "./input-admission";
+import { checkComboTargetInputAdmission, checkInputAdmission } from "./input-admission";
 import { nativeContextLimits } from "../../codex/catalog";
 import { streamingContextOverflowResponse } from "./context-overflow";
 import {
@@ -115,6 +120,8 @@ import { codexAuthContextLogLabel } from "../../codex/account-label";
 import {
   conversationStateBindingFromAuth,
   applyAccountChangeConversationStateScrub,
+  accountChangeFileReferenceRefusal,
+  conversationCarriesUploadedFiles,
 } from "./account-change-state";
 
 /** Parses, selects, and admits one request without changing the dispatch policy. */
@@ -365,6 +372,14 @@ export async function prepareResponsesRequest(
   }
   logCtx.requestedModel = parsed.modelId;
   logCtx.requestedEffort = parsed.options.reasoning;
+  // What this request may spend beyond its input, for the durable spend reservation (#4707).
+  // Read from the caller rather than from the adapter's serialized body, because the
+  // reservation has to exist before the body does. A caller that omits it leaves the
+  // provider/model default in charge and reserves only the input estimate; settlement then
+  // books the real figure, so the gap is a looser bound up front, never a wrong one after.
+  if (typeof parsed.options.maxOutputTokens === "number" && parsed.options.maxOutputTokens > 0) {
+    logCtx.spendOutputCeilingTokens = Math.trunc(parsed.options.maxOutputTokens);
+  }
   logCtx.callerServiceTier = sanitizeLogMetadataString(parsed.options.serviceTier);
   logCtx.requestedServiceTier = parsed.options.serviceTier;
   logCtx.requestedSpeedLabel = requestLogSpeedLabel(parsed.options.serviceTier);
@@ -442,12 +457,41 @@ export async function prepareResponsesRequest(
     && (route.codexAccountId === undefined || initialSubagentFallbackChain !== null)
     ? codexAccountSelectionForTurn(options.turnAdmissionLease)?.()
     : undefined;
+  // The credential headers final authentication will be given, resolved once and reused by
+  // everything below that has to predict what final auth decides.
+  const previewAuthHeaders = codexRouteCredentialDomainHeaders(
+    req,
+    route,
+    options,
+    credentialDomainWasRewritten,
+  );
+  // Does the CALLER own the credential this request will authenticate with? Validated exactly
+  // the way final auth validates it: the route ownership predicate AND the caller-bearer check
+  // `resolveCodexAuthContext` re-applies to these same headers.
+  const previewRequestScopedMainCredential = codexRouteCredentialOwnership(
+    previewAuthHeaders,
+    config,
+    route,
+    options,
+  ).requestScopedMainCredential && hasCallerCodexBearer(previewAuthHeaders);
   const nativeMainRecoveryBlocked = isNativeMainTrafficBlocked();
-  const nativeMainReadsForbidden = nativeMainRecoveryBlocked
+  // The same three inputs final auth ORs together (src/codex/auth-context.ts). Request-owned
+  // ownership is first there and has to be first here: computing the preview fence from
+  // recovery and drain state alone let a `thread_spawn` carrying a forwardable caller bearer
+  // read the physical main token it is forbidden to touch, and score main differently than the
+  // resolution this preview exists to predict.
+  const nativeMainReadsForbidden = previewRequestScopedMainCredential
+    || nativeMainRecoveryBlocked
     || previewSelectionAdmission?.mainProfileDraining === true;
+  // Deliberately NOT fenced on ownership: final auth derives `nativeMainSelectionOnly` from the
+  // drain alone, and adding a term here would diverge from it in the other direction.
   const previewSelectionOptions = {
     nativeMainSelectionOnly: !nativeMainRecoveryBlocked
       && previewSelectionAdmission?.mainProfileDraining === true,
+    // Preview must reach the same answer as the final resolution, including the uploaded-file
+    // retention (#4778): a preview that reported a quota move the request will not make would
+    // hand subagent fallback a different account than the one that actually serves.
+    retainAccountForUploadedFiles: conversationCarriesUploadedFiles(parsed._rawBody),
   };
   let selectedForwardHeaders = req.headers;
   let subagentFallbackAccountId = config.activeCodexAccountId ?? null;
@@ -466,22 +510,11 @@ export async function prepareResponsesRequest(
   // deliberately create no affinity at all -- previewing a family binding for one of those would
   // hand model fallback an account this request can never authenticate as. Read-only: the record
   // is written by the resolution that binds, never by a preview that may own no Pool state.
-  const previewAuthHeaders = codexRouteCredentialDomainHeaders(
-    req,
-    route,
-    options,
-    credentialDomainWasRewritten,
-  );
   const poolLineage = previewCodexPoolLineage(previewAuthHeaders, options.codexAuthPolicy ?? config, {
     accountId: route.codexAccountId,
     modelId: route.modelId,
     admission: options.admission,
-    requestScopedMainCredential: codexRouteCredentialOwnership(
-      previewAuthHeaders,
-      config,
-      route,
-      options,
-    ).requestScopedMainCredential,
+    requestScopedMainCredential: previewRequestScopedMainCredential,
   });
 
   try {
@@ -519,7 +552,20 @@ export async function prepareResponsesRequest(
       config,
       previewNow,
       codexQuotaScopeForModel(modelId),
-      { ...previewSelectionOptions, modelEligibleAccountIds },
+      {
+        ...previewSelectionOptions,
+        modelEligibleAccountIds,
+        // Per CANDIDATE model, like the scope and the eligible set above: the preference is
+        // model-specific, so hoisting it out of the closure would score every fallback
+        // candidate against the requested model's evidence and diverge from final auth (#4768).
+        // Under the same native-main read fence final auth applies: the reader validates each
+        // cached roster against the account's current credential, and for main that is a
+        // synchronous read of the stored token. A preview that read it would both cross the
+        // fence and score main differently than the resolution it is supposed to predict.
+        deniedModelAccountIds: cachedDeniedCodexAccountIdsForModel(modelId, previewNow, {
+          excludeAccountIds: nativeMainReadsForbidden ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined,
+        }),
+      },
       modelId,
       poolLineage,
     );
@@ -650,9 +696,31 @@ export async function prepareResponsesRequest(
           const fallback = (() => {
             try {
               const recoveryNativeMainBlocked = isNativeMainTrafficBlocked();
+              // Recompute ownership here rather than reusing the pre-decryption value: a
+              // subagent fallback above may have re-routed, and `requestScopedMainCredential`
+              // is a function of the route as well as the headers.
+              const recoveryAuthHeaders = codexRouteCredentialDomainHeaders(
+                req,
+                route,
+                options,
+                credentialDomainWasRewritten,
+              );
+              const recoveryRequestScopedMainCredential = codexRouteCredentialOwnership(
+                recoveryAuthHeaders,
+                config,
+                route,
+                options,
+              ).requestScopedMainCredential && hasCallerCodexBearer(recoveryAuthHeaders);
               const recoverySelectionOptions = {
                 nativeMainSelectionOnly: !recoveryNativeMainBlocked
                   && recoverySelectionAdmission?.mainProfileDraining === true,
+                // #4778, same reason as `previewSelectionOptions` above: this preview decides
+                // which account subagent fallback scores against, and final auth passes the
+                // retention. Recovery is exactly where the two could diverge -- it re-previews
+                // against the DECRYPTED body, which is the first point at which a file reference
+                // that was ciphertext-only becomes readable, so reconstructing the options
+                // without the bit lets preview report a quota move the request will not make.
+                retainAccountForUploadedFiles: conversationCarriesUploadedFiles(parsed._rawBody),
               };
               const recoveryNow = Date.now();
               // Carry the entitlement filter through recovery too (#2509/#2623). The scope was
@@ -665,7 +733,21 @@ export async function prepareResponsesRequest(
                 config,
                 previewNow,
                 codexQuotaScopeForModel(modelId),
-                { ...recoverySelectionOptions, modelEligibleAccountIds },
+                {
+                  ...recoverySelectionOptions,
+                  modelEligibleAccountIds,
+                  // Same read fence as the first preview, evaluated against recovery's own view
+                  // of the drain AND of credential ownership, rather than the one captured before
+                  // decryption. Omitting ownership here would reopen the fence the first preview
+                  // closes, on the one path that re-previews after the route may have moved.
+                  deniedModelAccountIds: cachedDeniedCodexAccountIdsForModel(modelId, previewNow, {
+                    excludeAccountIds: recoveryRequestScopedMainCredential
+                      || recoveryNativeMainBlocked
+                      || recoverySelectionAdmission?.mainProfileDraining === true
+                      ? new Set([MAIN_CODEX_ACCOUNT_ID])
+                      : undefined,
+                  }),
+                },
                 modelId,
                 poolLineage,
               );
@@ -860,7 +942,12 @@ export async function prepareResponsesRequest(
   // refusing the turn that shrinks the context would deadlock the client against the very
   // limit this gate reports — it would be told to compact and then denied the compaction.
   if (parsed._compactionRequest !== true) {
-    const inputAdmission = checkInputAdmission(parsed, route.provider, route.providerName, parsed.modelId, nativeContextLimits(config));
+    // A combo child is the one caller that can afford a strict gate: skipping a target it
+    // cannot fit is safe before any upstream bytes are sent, and the ladder continues. A
+    // direct request has nowhere to go, so it keeps the loose pathological-input gate.
+    const inputAdmission = options.comboAttempt
+      ? checkComboTargetInputAdmission(parsed, route.provider, route.providerName, parsed.modelId, nativeContextLimits(config))
+      : checkInputAdmission(parsed, route.provider, route.providerName, parsed.modelId, nativeContextLimits(config));
     if (!inputAdmission.admitted) {
       // #1524: this is a LOCAL preflight refusal, not an upstream verdict. A policy or combo
       // fallback must be able to skip this candidate and try one whose context window fits,
@@ -876,9 +963,13 @@ export async function prepareResponsesRequest(
       return formatErrorResponse(
         413,
         "input_admission_refused",
-        `Estimated input (~${inputAdmission.estimatedTokens} tokens) is far past the context window `
-          + `of ${parsed.modelId} (${inputAdmission.ceiling} tokens). Start a new session or choose a `
-          + `model with a larger context window.`,
+        inputAdmission.requiredOutputHeadroom !== undefined
+          ? `Estimated input (~${inputAdmission.estimatedTokens} tokens) plus ${inputAdmission.requiredOutputHeadroom} `
+            + `tokens of requested output headroom cannot fit the context window of ${parsed.modelId} `
+            + `(${inputAdmission.ceiling} tokens).`
+          : `Estimated input (~${inputAdmission.estimatedTokens} tokens) is far past the context window `
+            + `of ${parsed.modelId} (${inputAdmission.ceiling} tokens). Start a new session or choose a `
+            + `model with a larger context window.`,
       );
     }
   }
@@ -897,7 +988,18 @@ export async function prepareResponsesRequest(
   let substituteMainCredential = false;
   let callerAuthHeaders: Headers;
   {
-    const finalAuth = await resolveResponsesCodexAuth(req, config, route, options, credentialDomainWasRewritten);
+    // #4778: uploaded files are scoped to the account that issued them, so a conversation
+    // carrying live references must retain its binding across a voluntary quota move. Answered
+    // from the body alone, by the same predicate the refusal guard uses, so the two can never
+    // disagree about which conversations are in scope.
+    const finalAuth = await resolveResponsesCodexAuth(
+      req,
+      config,
+      route,
+      options,
+      credentialDomainWasRewritten,
+      conversationCarriesUploadedFiles(parsed._rawBody),
+    );
     if (!finalAuth.ok) return finalAuth.response;
     admissionState.authCtx = finalAuth.authCtx;
     selectedForwardHeaders = withClaudeNativeSession(finalAuth.headers, route.provider, options.claudeNativeSessionId);
@@ -921,6 +1023,14 @@ export async function prepareResponsesRequest(
   {
     const binding = conversationStateBindingFromAuth(admissionState.authCtx, poolAffinityKey);
     if (binding) {
+      // Before the scrub, because a file reference is refused rather than removed and the
+      // refusal has to happen while there is still no dispatch to undo.
+      const refusal = accountChangeFileReferenceRefusal({
+        body: parsed._rawBody,
+        bindingKey: binding.bindingKey,
+        servingAccountId: binding.accountId,
+      });
+      if (refusal) return refusal;
       applyAccountChangeConversationStateScrub({
         body: parsed._rawBody,
         parsed,

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

@@ -5,7 +5,13 @@ import { workflowRefusalResponse } from "../workflow-refusal";
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { noteAttemptSend } from "../request-log";
 import { TRANSIENT_RETRY_MAX_ATTEMPTS } from "../../lib/upstream-retry";
-import type { SingleUseDispatchPermit, SendClass } from "../../lib/request-execution-budget";
+import type {
+  DispatchDecision,
+  DispatchIntent,
+  RequestExecutionBudget,
+  SendClass,
+  SingleUseDispatchPermit,
+} from "../../lib/request-execution-budget";
 
 /** Owns the shared request send counter and recovery permits. */
 export function createResponsesSendBudget(
@@ -52,7 +58,7 @@ export function createResponsesSendBudget(
   /**
    * Records an adapter's OWN inner retries against this attempt.
    *
-   * Ordinal 1 is the send each call site already recorded through `noteAttemptSend`, so only
+   * Ordinal 1 is the send each call site already recorded through `noteRoutedAttemptSend`, so only
    * the extra physical sends are added here and an adapter that does not retry internally
    * leaves its log byte-for-byte as it was. Kiro reaches roughly eighteen sends per call and
    * Cursor re-sends a whole turn, and both reported one; a count that cannot be observed
@@ -75,6 +81,32 @@ export function createResponsesSendBudget(
    * was recovering from.
    */
   let pendingHopPermit: SingleUseDispatchPermit | undefined;
+  /**
+   * The budget an adapter's OWN dispatch ladder reserves against.
+   *
+   * Kiro and Cursor reserve once per physical send, and that is right: their ladders are the
+   * layer that actually sends, and counting one adapter call as one send hid up to eighteen
+   * upstream requests. But a credential hop has already booked the replay it is about to make,
+   * and a reservation IS the charge, so an adapter that reserves again turns one physical send
+   * into two charges -- and once the base allowance is spent, into a refusal that answers with
+   * a synthetic error in place of the 429 the hop was recovering from (#4709).
+   *
+   * The hop hands its reservation down through `pendingHopPermit`, the same seam the
+   * passthrough ladder already uses, and this view spends it on the adapter's FIRST
+   * reservation. Every later send in that ladder is a new physical send and is charged
+   * normally. A permit the adapter takes but never sends under is released through the same
+   * call it would have used for a reservation of its own, so an abandoned replay is refunded
+   * rather than left charged.
+   */
+  const adapterDispatchBudget: RequestExecutionBudget | undefined = adapterSendBudget === undefined
+    ? undefined
+    : adapterDispatchBudgetView(adapterSendBudget, {
+      claimHopPermit: () => {
+        const permit = pendingHopPermit;
+        pendingHopPermit = undefined;
+        return permit;
+      },
+    });
   /**
    * How many sends a recovery leg may make, and the permit that authorises the last one.
    *
@@ -147,6 +179,7 @@ export function createResponsesSendBudget(
     noteTransientSends,
     remainingTransientSendBudget,
     adapterSendBudget,
+    adapterDispatchBudget,
     noteAdapterPhysicalSend,
     sendBudgetExhausted,
     get pendingHopPermit(): SingleUseDispatchPermit | undefined {
@@ -162,3 +195,65 @@ export function createResponsesSendBudget(
 }
 
 export type ResponsesSendBudget = Exclude<ReturnType<typeof createResponsesSendBudget>, Response>;
+
+/**
+ * A LIVE delegating view of one request's execution budget, with a credential hop's
+ * reservation spendable through it.
+ *
+ * Every member forwards rather than copying. A spread of the budget would freeze `used`,
+ * `reserveSpent` and the target counters at construction time, handing the adapter a budget
+ * that can never read as exhausted -- the same class of defect as the fresh per-layer
+ * allowances #4546 removed.
+ */
+function adapterDispatchBudgetView(
+  budget: RequestExecutionBudget,
+  hop: { claimHopPermit: () => SingleUseDispatchPermit | undefined },
+): RequestExecutionBudget {
+  return {
+    get used(): number { return budget.used; },
+    set used(next: number) { budget.used = next; },
+    logicalRequestId: budget.logicalRequestId,
+    policyVersion: budget.policyVersion,
+    policy: budget.policy,
+    get reserveSpent(): boolean { return budget.reserveSpent; },
+    get alternateTargetSends(): number { return budget.alternateTargetSends; },
+    get targetTransitions(): number { return budget.targetTransitions; },
+    get lastTargetKey(): string | undefined { return budget.lastTargetKey; },
+    remainingBaseSends: (cap: number): number => budget.remainingBaseSends(cap),
+    reserveDispatch(intent: DispatchIntent): DispatchDecision {
+      // A dispatch whose upstream state is unknown is refused on its own merits. A hop that
+      // already paid does not make an unsafe replay safe, so that check stays with the budget.
+      if (intent.replaySafe !== false) {
+        const hopPermit = hop.claimHopPermit();
+        // Confirmed here rather than in `use()`: the adapter reserves immediately before it
+        // opens the transport, which is the same boundary the hop's own confirmation uses.
+        // A permit some other leg already settled returns false, and this falls through to a
+        // real reservation rather than handing the adapter a dead permit -- an adapter whose
+        // `use()` fails treats the request as exhausted and stops sending entirely.
+        if (hopPermit !== undefined && hopPermit.assumeCharge()) {
+          let spent = false;
+          return {
+            allowed: true,
+            permit: {
+              sendClass: hopPermit.sendClass,
+              use: (): boolean => {
+                if (spent) return false;
+                spent = true;
+                return true;
+              },
+              assumeCharge: (): boolean => {
+                if (spent) return false;
+                spent = true;
+                return true;
+              },
+              // The hop's charge is already settled and belongs to the leg that asked for it,
+              // so there is nothing here to refund.
+              release: (): void => {},
+            },
+          };
+        }
+      }
+      return budget.reserveDispatch(intent);
+    },
+  };
+}

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

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import type { RequestSendObserver } from "../../lib/request-execution-budget";
+import { sharedSpendLedger, type SpendReservationLedger } from "../../lib/spend-reservation-ledger";
+import type { RequestLogContext } from "../request-log";
+
+/** The terminal usage a request reported, in the only two fields the ledger books. */
+export interface TerminalSpendUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+/** Settles one request's durable spend entries once its terminal usage is known. */
+export interface RequestSpendSettlement {
+  settle(usage: TerminalSpendUsage | undefined): void;
+}
+
+export interface RequestSpendTracker extends RequestSendObserver, RequestSpendSettlement {
+  /** Dispatches this request lost to a ledger ceiling. Zero on every ordinary request. */
+  readonly refusals: number;
+}
+
+/**
+ * One request's entries in the durable spend ledger (#4707).
+ *
+ * The ledger has had the whole reserve/dispatch/settle vocabulary since #4546 and no production
+ * caller: `spend-ledger.jsonl` was never created by ordinary traffic, and the ceilings the
+ * feature advertised stayed process-local and count-only, resetting on restart. This is the
+ * caller.
+ *
+ * It books one entry per physical send by observing the request's own send counter rather than
+ * by being called from each dispatch site. That counter moves exactly once per physical send,
+ * so one entry per increment is one entry per send -- and a dispatch path added later cannot
+ * forget to book, which is how the previous wiring attempt ended up with no caller at all.
+ *
+ * Settlement follows what the request actually learned. The terminal usage belongs to the LAST
+ * send that left, so that one settles with the real figure. Every earlier send failed without
+ * reporting usage of its own and may still have been billed, so it becomes unresolved spend
+ * rather than free. A request that ends with no usage at all -- a cancel, a lost stream --
+ * leaves all of them unresolved, which is the conservative answer this ledger exists to give.
+ */
+export function createRequestSpendTracker(
+  logCtx: Pick<
+    RequestLogContext,
+    "provider" | "accountLogLabel" | "usageLogInputTokens" | "spendOutputCeilingTokens"
+  >,
+  rootId: string | undefined,
+  injected?: SpendReservationLedger,
+): RequestSpendTracker {
+  // Resolved on the first CHARGE, not when the request is built. The shared ledger opens a
+  // journal under the OpenCodex home, and a request that never dispatches -- refused at
+  // admission, answered locally, cancelled before its first send -- has no business creating
+  // one. It also means the home in effect at dispatch is the one that gets written.
+  let ledgerRef: SpendReservationLedger | undefined = injected;
+  const ledger = (): SpendReservationLedger => (ledgerRef ??= sharedSpendLedger());
+  // Every send this request still owes the ledger an answer for, oldest first.
+  const live: string[] = [];
+  let refusals = 0;
+  let resolved = false;
+  /**
+   * Confirm the sends this request has already moved past.
+   *
+   * A booking is only marked dispatched once a LATER send exists, because that later send
+   * proves the earlier one left. The newest booking stays open until it is settled, so a
+   * reservation the budget hands back -- a rotation that found no alternate, a rebuild
+   * abandoned before the wire -- can still be released for free while this process is alive.
+   * A crash resolves every surviving reservation as unresolved spend regardless of this mark,
+   * because a journal that lost its tail cannot prove a send never left.
+   */
+  const confirmOlderSends = (): void => {
+    for (let index = 0; index < live.length - 1; index += 1) ledger().markDispatched(live[index] as string);
+  };
+  return {
+    charge(): boolean {
+      const sendId = randomUUID();
+      const decision = ledger().reserve({
+        sendId,
+        scopes: {
+          ...(rootId !== undefined ? { rootId } : {}),
+          // Already the privacy-safe label the request log uses, and the ledger aliases it
+          // again on the way to disk. A raw credential never reaches either.
+          ...(logCtx.accountLogLabel !== undefined ? { identityId: logCtx.accountLogLabel } : {}),
+          ...(logCtx.provider !== undefined ? { poolId: logCtx.provider } : {}),
+        },
+        inputTokens: logCtx.usageLogInputTokens ?? 0,
+        outputCeilingTokens: logCtx.spendOutputCeilingTokens ?? 0,
+      });
+      if (!decision.reserved) {
+        refusals += 1;
+        // Only an operator's configured ceiling refuses a dispatch. Every other denial --
+        // capacity, durability, a journal this process could not prove complete -- means the
+        // ledger cannot ACCOUNT for this send, which is not a reason to refuse one. An
+        // unconfigured install keeps the count caps it already had and is not newly refused,
+        // and a degraded ledger must not become an outage.
+        return decision.denial.reason !== "spend-limit-exceeded";
+      }
+      live.push(sendId);
+      confirmOlderSends();
+      return true;
+    },
+    refund(): void {
+      const sendId = live.pop();
+      if (sendId === undefined) return;
+      // Undispatched, so this returns the tokens. If the send was already confirmed by a later
+      // one, `abandon` refuses and unresolved is the only honest outcome left.
+      if (!ledger().abandon(sendId)) ledger().markLost(sendId);
+    },
+    settle(usage: TerminalSpendUsage | undefined): void {
+      if (resolved) return;
+      resolved = true;
+      const terminal = live.pop();
+      if (terminal !== undefined) {
+        const reported = typeof usage?.inputTokens === "number" || typeof usage?.outputTokens === "number";
+        if (reported) {
+          ledger().settle(terminal, {
+            inputTokens: usage?.inputTokens ?? 0,
+            outputTokens: usage?.outputTokens ?? 0,
+          });
+        } else {
+          // The response never reported usage. It may still have been billed.
+          ledger().markLost(terminal);
+        }
+      }
+      for (const sendId of live.splice(0)) ledger().markLost(sendId);
+    },
+    get refusals(): number { return refusals; },
+  };
+}
+
+/**
+ * Give a request a spend tracker and hand back the observer its budget reports through.
+ *
+ * The tracker is parked on the log context because `addFinalRequestLog` is the one seam every
+ * request passes exactly once, whatever transport served it and however it ended, and it is
+ * where the terminal usage is already known.
+ */
+export function attachRequestSpendTracker(
+  req: Pick<Request, "headers">,
+  logCtx: RequestLogContext,
+  ledger?: SpendReservationLedger,
+): RequestSendObserver {
+  const rootId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const tracker = ledger === undefined
+    ? createRequestSpendTracker(logCtx, rootId)
+    : createRequestSpendTracker(logCtx, rootId, ledger);
+  logCtx.spendTracker = tracker;
+  return tracker;
+}

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

@@ -8,7 +8,7 @@ import {
   credentialGeneration,
 } from "../../oauth/store";
 import type { ProviderAdapter, AdapterRequest } from "../../adapters/base";
-import type { OcxParsedRequest, OcxProviderConfig } from "../../types";
+import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../../types";
 import type { AnthropicAccountSelectionReason } from "../../oauth/anthropic-routing";
 import {
   isAnthropicAccountPoolEnabled,
@@ -33,7 +33,7 @@ import {
   preferredInitialAccount,
   noteGenericPoolSelection,
 } from "../../oauth/generic-account-failover";
-import { stampOAuthAccountLabel } from "../../providers/label";
+import { stampOAuthAccountLabel, usesApiKeyAccount } from "../../providers/label";
 import { resolveProviderTransport } from "../../providers/xai-transport";
 import { resolveCopilotApiBaseUrl } from "../../oauth/github-copilot";
 import {
@@ -59,7 +59,11 @@ import {
   sealRequestAttemptIdentity,
   recordAttemptCredentialSource,
   recordAdapterTierMetadata,
+  noteProviderAttemptSend,
+  recordKeyAttemptFailure,
+  recordKeyAttemptUsage,
 } from "../request-log";
+import type { AttemptRecoveryKind } from "../../usage/log";
 import { resolvePassiveRouteSubjectId } from "../passive-route-linker";
 
 /** Owns live credential selection and adapter bindings for one request. */
@@ -241,6 +245,30 @@ export async function prepareResponsesTransport(
     replayOAuthCredentialSnapshot = { accountId: snapshot.accountId, generation: snapshot.generation };
     return true;
   };
+  // Key sends may be rebuilt while queued. Keep metadata pending until the guarded
+  // physical dispatch binds it to the selection that actually reaches the upstream.
+  let pendingKeySend: { estimate: number | undefined; recovery?: AttemptRecoveryKind } | undefined;
+  const noteRoutedAttemptSend = (estimate: number | undefined, recovery?: AttemptRecoveryKind): void => {
+    if (usesApiKeyAccount(route.provider)) pendingKeySend = { estimate, recovery };
+    else noteProviderAttemptSend(logCtx, route.providerName, route.provider, estimate, recovery);
+  };
+  const commitKeyAttemptSend = (): void => {
+    if (!usesApiKeyAccount(route.provider)) return;
+    noteProviderAttemptSend(logCtx, route.providerName, route.provider,
+      pendingKeySend?.estimate ?? logCtx.usageLogInputTokens, pendingKeySend?.recovery);
+    pendingKeySend = undefined;
+  };
+  const bindKeyUsageFromBridge = (usage: OcxUsage | undefined): void => {
+    logCtx.usageFromBridge = true;
+    if (usesApiKeyAccount(route.provider)) {
+      logCtx.usage = logCtx.activeAttempt?.usage;
+      return;
+    }
+    if (usage) {
+      logCtx.usage = usage;
+      if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
+    }
+  };
   const selectionIsCurrent = (binding: DispatchBinding | undefined): boolean => {
     if (route.provider.authMode === "forward") return true;
     if (!binding) return false;
@@ -260,6 +288,27 @@ export async function prepareResponsesTransport(
         : undefined
       : { kind: "api-key", provider: { ...route.provider } };
     if (binding) adapterBindings.set(resolved, binding);
+    // Observe terminals before search/image loops or continuation guards hide earlier rounds.
+    // Each adapter parser is called once per physical response; bridge totals are client-only.
+    const observedResponses = new WeakSet<object>();
+    const observeUsage = (event: AdapterEvent, response: object): void => {
+      if (usesApiKeyAccount(provider) && "usage" in event && event.usage && !observedResponses.has(response)) {
+        observedResponses.add(response);
+        recordKeyAttemptUsage(logCtx, event.usage);
+      }
+    };
+    const parseStream = resolved.parseStream.bind(resolved);
+    resolved.parseStream = async function* (...args) {
+      for await (const event of parseStream(...args)) { observeUsage(event, args[0]); yield event; }
+    };
+    if (resolved.parseResponse) {
+      const parseResponse = resolved.parseResponse.bind(resolved);
+      resolved.parseResponse = async (...args) => {
+        const events = await parseResponse(...args);
+        events.forEach(event => observeUsage(event, args[0]));
+        return events;
+      };
+    }
     const build = resolved.buildRequest.bind(resolved);
     resolved.buildRequest = async (requestParsed, incoming) => {
       const request = await build(requestParsed, incoming);
@@ -268,7 +317,11 @@ export async function prepareResponsesTransport(
       return request;
     };
     if (resolved.runTurn) {
-      rawRunTurns.set(resolved, resolved.runTurn.bind(resolved));
+      const runTurn = resolved.runTurn.bind(resolved);
+      rawRunTurns.set(resolved, (requestParsed, incoming, emit) => {
+        const response = {};
+        return runTurn(requestParsed, incoming, event => { observeUsage(event, response); emit(event); });
+      });
       resolved.runTurn = (requestParsed, incoming, emit) => runSelectedTurn(resolved, requestParsed, incoming, emit);
     }
     return resolved;
@@ -319,6 +372,7 @@ export async function prepareResponsesTransport(
             refused = true;
             throw new Error("Account selection changed before the first turn dispatch");
           }
+          commitKeyAttemptSend();
           sent = true;
         },
       });
@@ -351,7 +405,9 @@ export async function prepareResponsesTransport(
             && sentHeaders?.get("authorization") === `Bearer ${snapshot.accessToken}`
             && !sentHeaders?.has("x-api-key");
           // Reselection can choose a provider override instead of the supplied executor.
+          commitKeyAttemptSend();
           const response = await fetchImpl(destination, { ...dispatchInit, redirect: "manual" });
+          if (!response.ok) await recordKeyAttemptFailure(logCtx, response, dispatchInit.signal ?? options.abortSignal);
           // Observe each physical response before retries replace it. The binding belongs to
           // this dispatch, so a manual switch cannot file A's headers against B. Header
           // overrides and credential replacement make ownership unprovable: skip those writes.
@@ -736,6 +792,9 @@ export async function prepareResponsesTransport(
     resolveSelectionAdapter,
     refreshRunTurnAdapter,
     oauthDispatch,
+    noteRoutedAttemptSend,
+    commitKeyAttemptSend,
+    bindKeyUsageFromBridge,
     anthropicSessionKey,
     isPassthrough,
   };