lidge-jun · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
@@ -407,6 +407,12 @@ with the lock status; Direct provider quota omits an unpublished response and it
 identities and stale 401/403 replies retain the current
 cached info and cannot clear or set the current account's reauthentication state.
 
+Responses to requests sent with the identified main credential refresh its cached
+usage from their quota headers, whether the proxy substituted the stored credential or
+the caller sent the same credential itself. A response is applied only if that
+credential is still the observed main credential when it arrives; a caller-owned
+credential for another account or workspace never updates the main account's usage.
+
 The persisted option is `"codexMainAccountHardLock"` in OpenCodex's `config.json`. An absent key or
 `true` means on; only an explicit `false` turns it off, and that is what switching the setting off
 stores. The default changed here: the policy used to be opt-in and the old switch removed the key

@@ -1313,6 +1313,7 @@
     "openai-provider-option.test.ts": "adapters/openai",
     "responses-forward-client-headers.test.ts": "responses",
     "openai-responses-passthrough.test.ts": "responses",
+    "responses-main-quota-observation.test.ts": "responses",
     "external-task-input-repair.test.ts": "responses",
     "openai-responses-summary-none.test.ts": "responses",
     "responses-forward-output-cap.test.ts": "responses",

@@ -81,11 +81,13 @@ import {
 import {
   captureMainAccountIdentityGeneration,
   captureMainQuotaWriter,
+  captureMainQuotaDispatch,
   getObservedMainQuotaIdentityKey,
   isMainQuotaWriterLive,
   matchesMainQuotaCredential,
   observeMainQuotaCredential,
   type MainQuotaWriter,
+  type MainQuotaDispatch,
 } from "./main-account-cache";
 import { CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE, isCodexReserveHelperUnsupported, isCodexReserveRequestEligible } from "./loopback-target";
 import type { DataPlaneAdmission } from "../server/auth-cors";
@@ -275,7 +277,11 @@ export function previewCodexPoolLineage(
 }
 
 export type CodexAuthContext =
-  | { kind: "main"; accountId: null; reserveAuthorization?: MainReserveAuthorization }
+  | {
+      kind: "main"; accountId: null; reserveAuthorization?: MainReserveAuthorization;
+      /** Captured for the observed main credential actually selected for upstream. */
+      mainQuotaDispatch?: MainQuotaDispatch;
+    }
   | {
       kind: "pool";
       accountId: string;
@@ -1635,6 +1641,14 @@ export class CodexMainSubstitutionUnavailableError extends Error {
   }
 }
 
+/** Dispatch identity comes only from an owned observation of the selected credential. */
+function selectedMainQuotaDispatch(selected: Headers): MainQuotaDispatch | undefined {
+  const bearer = selected.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!bearer) return undefined;
+  const accountId = selected.get("chatgpt-account-id") ?? extractAccountId(undefined, bearer);
+  return captureMainQuotaDispatch(bearer, accountId, captureConfigGeneration());
+}
+
 /**
  * Build the upstream auth headers for one Codex turn.
  *
@@ -1654,6 +1668,7 @@ export function materializeCodexUpstreamAuth(
   ctx: CodexAuthContext,
   options: CodexAuthMaterializationOptions = {},
 ): Headers {
+  if (ctx.kind === "main") ctx.mainQuotaDispatch = undefined;
   const selected = new Headers();
   for (const name of FORWARD_HEADERS) {
     const value = headers.get(name);
@@ -1695,10 +1710,12 @@ export function materializeCodexUpstreamAuth(
     observeSelectedMainCredential(stored, writer);
     assertMainAccountPolicy(options.config);
     assertMaterializedReserve(selected, ctx, options);
+    ctx.mainQuotaDispatch = selectedMainQuotaDispatch(selected);
     return selected;
   }
   if (callerMatchesObservedMain(selected)) assertMainAccountPolicy(options.config);
   assertMaterializedReserve(selected, ctx, options);
+  if (ctx.kind === "main") ctx.mainQuotaDispatch = selectedMainQuotaDispatch(selected);
   return selected;
 }
 
@@ -1749,6 +1766,7 @@ export async function materializeCodexUpstreamAuthAsync(
   ctx: CodexAuthContext,
   options: CodexAuthMaterializationOptions = {},
 ): Promise<Headers> {
+  if (ctx.kind === "main") ctx.mainQuotaDispatch = undefined;
   if (requiresReserveAuthorization(options.config, options.modelId, options.admission)) {
     return materializeReserveUpstreamAuth(headers, ctx, options);
   }
@@ -1776,6 +1794,7 @@ export async function materializeCodexUpstreamAuthAsync(
   assertMainAccountPolicy(options.config);
   // An opt-in enabled during token refresh must not turn a proof-less context into Reserve.
   assertMaterializedReserve(selected, ctx, options);
+  ctx.mainQuotaDispatch = selectedMainQuotaDispatch(selected);
   return selected;
 }
 

@@ -1,4 +1,5 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { codexCredentialMutationEpoch } from "./credential-mutation-epoch";
 import type { StoredAccountQuota } from "./quota-types";
 import { truncateRetainedUtf8 } from "../lib/admission";
 
@@ -73,6 +74,48 @@ export function isMainQuotaWriterLive(writer: MainQuotaWriter): boolean {
     && writer.identityGeneration === mainAccountIdentityGeneration;
 }
 
+/** Proof that a dispatch used the observed main credential; process-local, never persisted. */
+export type MainQuotaDispatch = Readonly<{
+  writer: MainQuotaWriter;
+  credentialGeneration: number;
+  credentialMutationEpoch: number;
+  configGeneration: number;
+}>;
+
+// WS quota frames publish through their observer; prelude quota can only come from those frames.
+// A real HTTP fallback after a failed upgrade never invokes the observer and stays unclaimed.
+const wsObservedMainDispatches = new WeakSet<MainQuotaDispatch>();
+
+export function claimMainQuotaDispatchForWs(dispatch: MainQuotaDispatch): void {
+  wsObservedMainDispatches.add(dispatch);
+}
+
+export function isMainQuotaDispatchWsClaimed(dispatch: MainQuotaDispatch): boolean {
+  return wsObservedMainDispatches.has(dispatch);
+}
+
+/** Give a replacement physical attempt its own quota ownership without recapturing credential fences. */
+export function renewMainQuotaDispatchForAttempt(dispatch: MainQuotaDispatch): MainQuotaDispatch {
+  return { ...dispatch };
+}
+
+export function captureMainQuotaDispatch(
+  accessToken: string, accountId: string | undefined, configGeneration: number,
+): MainQuotaDispatch | undefined {
+  if (!accountId || !matchesMainQuotaCredential(accessToken, accountId)) return undefined;
+  const writer = captureMainQuotaWriter(accountId);
+  return writer ? { writer, credentialGeneration: mainQuotaCredentialGeneration,
+    credentialMutationEpoch: codexCredentialMutationEpoch(), configGeneration } : undefined;
+}
+
+export function isMainQuotaDispatchLive(dispatch: MainQuotaDispatch): boolean {
+  // Other OpenCodex-owned credential publications also advance this epoch;
+  // dropping a main quota update after any such publication is the intended safe direction.
+  return isMainQuotaWriterLive(dispatch.writer)
+    && dispatch.credentialGeneration === mainQuotaCredentialGeneration
+    && dispatch.credentialMutationEpoch === codexCredentialMutationEpoch();
+}
+
 export function getObservedMainQuotaIdentityKey(): string | undefined {
   return observedMainQuotaIdentityKey;
 }

@@ -9,7 +9,7 @@ import { CODEX_RESPONSES_HTTP_URL, type PreparedCodexWsRequest } from "./codex-w
 import { CodexWsCorrelation } from "./codex-ws-correlation";
 import type { CodexWsSession } from "./codex-ws-session";
 import { UPGRADE_DEADLINE_MS, CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES,
-  MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage,
+  MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, markCodexWsPreludeProjection, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage,
   codexWsCreateFrameExceedsLimit, codexWsFailureDetail, codexWsPreResponseFailure, markCodexWsStage, codexWsOcxVersion,
   markCodexWsSocketDeath, type CodexWsFailureStage, type CodexWsStageRecord } from "./codex-ws-wire";
 
@@ -45,7 +45,8 @@ function rejectionHeaders(source: Record<string, unknown>, prelude: Headers): He
     }
   }
   // Reuse the metadata owner's count/value/family budgets and window freshness
-  // rules, without publishing quota twice. The unmarked HTTP response owns it.
+  // rules, without publishing quota twice. Pool bookkeeping consumes the HTTP
+  // projection; plain-main publication belongs only to the WS observer.
   const projected = new CodexWsMetadata();
   try {
     for (const values of [Object.fromEntries(prelude), source]) {
@@ -241,6 +242,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         // are left out: their channel may already have sent continuation frames on this socket, so
         // the create frame alone no longer describes the turn.
         if (socketDied && !nativeControl) markCodexWsSocketDeath(failureResponse, stage);
+        markCodexWsPreludeProjection(failureResponse);
         resolve(failureResponse);
         return;
       }
@@ -513,6 +515,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
             cleanup();
             try { controller.close(); } catch { /* unused stream already closed */ }
             session.dispose();
+            markCodexWsPreludeProjection(rejection);
             resolve(rejection);
             return;
           }

@@ -49,6 +49,7 @@ const WS_CLOSE_MESSAGE_TOO_BIG = 1009;
 
 const codexWsUpstreamResponses = new WeakSet<Response>();
 const quotaObservedResponses = new WeakSet<Response>();
+const codexWsPreludeProjections = new WeakSet<Response>();
 
 /** Quota arrived directly at its captured account; do not replay old HTTP prelude headers. */
 export function isCodexWsQuotaObservedResponse(response: Response): boolean {
@@ -60,6 +61,14 @@ export function isCodexWsUpstreamResponse(response: Response): boolean {
   return codexWsUpstreamResponses.has(response);
 }
 
+/** Pre-response projection; its headers retain the exchange's prelude snapshot. */
+export function markCodexWsPreludeProjection(response: Response): void {
+  codexWsPreludeProjections.add(response);
+}
+
+export function isCodexWsPreludeProjection(response: Response): boolean {
+  return codexWsPreludeProjections.has(response);
+}
 
 export function markCodexWsResponse(response: Response, observed: boolean): void {
   codexWsUpstreamResponses.add(response);

@@ -6,6 +6,7 @@ import {
   computeQuotaCooldown,
   formatCodexProviderForLog,
 } from "../../codex/routing";
+import { claimMainQuotaDispatchForWs, isMainQuotaDispatchLive, renewMainQuotaDispatchForAttempt, type MainQuotaDispatch } from "../../codex/main-account-cache";
 import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { isCodexAccountGenerationLive } from "../../codex/account-store";
@@ -121,8 +122,28 @@ export function usesCodexForwardPoolAuth(
 }
 
 
+/** Live proof that this plain-main response used the observed main credential. */
+export function liveMainQuotaDispatch(
+  authCtx: CodexAuthContext, provider: OcxProviderConfig,
+): MainQuotaDispatch | undefined {
+  if (authCtx.kind !== "main" || !authCtx.mainQuotaDispatch) return undefined;
+  if (!isCanonicalOpenAiForwardProvider(provider)
+    || provider.authMode !== "forward" || provider.adapter !== "openai-responses") return undefined;
+  return isMainQuotaDispatchLive(authCtx.mainQuotaDispatch) ? authCtx.mainQuotaDispatch : undefined;
+}
+
 export function codexWsQuotaObserver(authCtx: CodexAuthContext, provider: OcxProviderConfig, modelId?: string): CodexWsQuotaObserver | undefined {
-  if (!isCanonicalOpenAiForwardProvider(provider) || !usesCodexForwardPoolAuth(authCtx, provider)) return undefined;
+  if (!isCanonicalOpenAiForwardProvider(provider)) return undefined;
+  if (!usesCodexForwardPoolAuth(authCtx, provider)) {
+    const captured = liveMainQuotaDispatch(authCtx, provider);
+    if (!captured || authCtx.kind !== "main") return undefined;
+    const dispatch = authCtx.mainQuotaDispatch = renewMainQuotaDispatchForAttempt(captured);
+    return headers => {
+      claimMainQuotaDispatchForWs(dispatch);
+      if (!isMainQuotaDispatchLive(dispatch)) return;
+      applyCapturedCodexQuota(MAIN_CODEX_ACCOUNT_ID, headers, dispatch.configGeneration, dispatch.writer, { modelId });
+    };
+  }
   const { accountId, writerGeneration } = authCtx;
   const credentialGeneration = authCtx.kind === "pool" ? authCtx.generation : undefined;
   const mainWriter = authCtx.kind === "main-pool" ? authCtx.mainQuotaWriter : undefined;

@@ -24,13 +24,16 @@ import { teeWithBoundedInspection } from "../inspection-tee";
 import {
   codexForwardTerminalOutcomeRecorder,
   usesCodexForwardPoolAuth,
+  liveMainQuotaDispatch,
   codexQuotaOutcomeMeta,
   codexDenialOutcomeMeta,
   isFixedCodexAccount,
   shouldDeferCodexResetDerivedCooldown,
 } from "./core-codex-account";
+import { isMainQuotaDispatchLive, isMainQuotaDispatchWsClaimed } from "../../codex/main-account-cache";
+import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/account-id";
 import type { ResponsesTerminalStatus } from "../../bridge";
-import { isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./ws-upstream";
+import { isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse, isCodexWsPreludeProjection } from "./ws-upstream";
 import { recordSubagentQuotaFailureForThreadSpawn } from "../../codex/subagent-model-fallback";
 import { recordCodexUpstreamOutcome } from "../../codex/routing";
 import { codexProbeLeaseId, codexProbeQuotaScope, codexTransientProbeGrant, releaseCodexAuthContextProbeLease } from "../../codex/auth-context";
@@ -406,6 +409,9 @@ export async function deliverPassthroughResponse(
     | "localUpstream"
   >,
 ): Promise<Response> {
+  const { route } = requestState;
+  // The proof must belong to the response whose headers are published.
+  const arrivalMainDispatch = liveMainQuotaDispatch(admissionState.authCtx, route.provider);
   const { logCtx, config, options, req } = requestContext;
   const {
     codexSafetyBufferingOptions,
@@ -429,7 +435,7 @@ export async function deliverPassthroughResponse(
     normalizeFunctionCompletionJson,
   } = nativeExchange;
   const { commitReasoningReplayServingRoute, recordTerminalOutcomes } = responseEffects;
-  const { parsed, route, subagentQuotaFailureModel, clientRequestedStream, translatorBudget, inboundWire } = requestState;
+  const { parsed, subagentQuotaFailureModel, clientRequestedStream, translatorBudget, inboundWire } = requestState;
   const enforceDeclaredToolNames = inboundWire !== "chat" && inboundWire !== "anthropic";
   const { openAiSidecar } = sidecarState;
   const { requestBindings } = transportState;
@@ -535,6 +541,20 @@ export async function deliverPassthroughResponse(
           ...(admissionState.authCtx.kind === "pool" ? { credentialGeneration: admissionState.authCtx.generation } : {}),
         });
       }
+    } else {
+      // The WS observer is the only plain-main publisher for a WebSocket exchange;
+      // a prelude projection carries the prelude snapshot, not fresh evidence.
+      // The dispatch claim is authoritative because downstream wrappers can replace the Response.
+      if (arrivalMainDispatch && !isMainQuotaDispatchWsClaimed(arrivalMainDispatch)
+        && !(isCodexWsUpstreamResponse(upstreamResponse) || isCodexWsPreludeProjection(upstreamResponse))) {
+        const { applyAccountQuotaFromUpstreamHeaders } = await import("../../codex/auth-api");
+        // Import yields; same-account token replacement leaves the identity writer live.
+        // Re-check the credential fence with no await before publication.
+        if (isMainQuotaDispatchLive(arrivalMainDispatch)) {
+          applyAccountQuotaFromUpstreamHeaders(MAIN_CODEX_ACCOUNT_ID, upstreamResponse.headers,
+            arrivalMainDispatch.configGeneration, arrivalMainDispatch.writer, { modelId: route.modelId });
+        }
+      }
     }
 
     // Non-2xx passthrough failures must never reach Codex as an empty body —

@@ -12,6 +12,7 @@ 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 { renewMainQuotaDispatchForAttempt } from "../../codex/main-account-cache";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { isLocalUpstream } from "../../lib/local-upstream";
 import { codexSafetyBufferingFilterOptions, terminalStatusFromParsed } from "../relay";
@@ -802,6 +803,9 @@ export async function preparePassthroughExchange(
     const sendAmbiguousReplacement = (
       signal: AbortSignal = upstream.signal,
     ): Promise<Response> => {
+      if (admissionState.authCtx.kind === "main" && admissionState.authCtx.mainQuotaDispatch) {
+        admissionState.authCtx.mainQuotaDispatch = renewMainQuotaDispatchForAttempt(admissionState.authCtx.mainQuotaDispatch);
+      }
       const report = transientSendReporter();
       let started = false;
       const run = () => fetchWithHeaderTimeout(

@@ -26,7 +26,7 @@ import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
 import { isLoopbackUrl, rewriteWebSocketDial } from "../../plugins/upstream-hooks";
 export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
   MAX_CODEX_WS_CREATE_FRAME_BYTES, CODEX_WS_CREATE_FRAME_LIMIT_BYTES, codexWsCreateFrameExceedsLimit,
-  isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./codex-ws-wire";
+  isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse, isCodexWsPreludeProjection } from "./codex-ws-wire";
 export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
 
 /**