@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/codex/auth-context.ts

@@ -8,7 +8,6 @@ import {
   isCodexAccountGenerationLive,
 } from "./account-store";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
-import { isCodexAccountPaused } from "./account-pause";
 import { ConfigMutationLockError } from "../config";
 import { NativeProfileError } from "./native-profile-types";
 import { isCodexAccountUsable } from "./account-usability";
@@ -41,16 +40,30 @@ import {
   isDirectCallerEntitledToCodexModel,
   resolveCodexModelEntitlements,
 } from "./model-entitlements";
-import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./catalog/native-models";
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
 import { formatErrorResponse } from "../bridge";
-import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
+import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import { captureConfigGeneration } from "../lib/state-store-sweeper";
 import { retainedUtf8Bytes } from "../lib/admission";
 import { extractAccountId } from "../oauth/chatgpt";
+import { getMainAccountHardLockStatus, isMainAccountHardLocked } from "./main-account-hard-lock";
+import {
+  captureMainAccountIdentityGeneration,
+  captureMainQuotaWriter,
+  getObservedMainQuotaIdentityKey,
+  isMainQuotaWriterLive,
+  matchesMainQuotaCredential,
+  observeMainQuotaCredential,
+  type MainQuotaWriter,
+} from "./main-account-cache";
+import { CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE, isCodexReserveHelperUnsupported, isCodexReserveRequestEligible } from "./loopback-target";
+import type { DataPlaneAdmission } from "../server/auth-cors";
+import { getMainReserveAuthorization, isMainReserveAuthorizationLive, type MainReserveAuthorization } from "./reserve-availability";
+import { UpstreamRetryEvidenceError } from "../lib/upstream-retry";
 
 const CODEX_AFFINITY_COMPONENT_MAX_BYTES = 512;
 const CODEX_APP_AFFINITY_KEY = randomBytes(32);
@@ -99,7 +112,7 @@ export function codexPoolAffinityKey(headers: Headers): string | undefined {
 }
 
 export type CodexAuthContext =
-  | { kind: "main"; accountId: null }
+  | { kind: "main"; accountId: null; reserveAuthorization?: MainReserveAuthorization }
   | {
       kind: "pool";
       accountId: string;
@@ -128,6 +141,9 @@ export type CodexAuthContext =
       kind: "main-pool";
       accountId: string;
       writerGeneration: number;
+      /** Captured before async credential work; never reconstructed after the upstream response. */
+      mainQuotaWriter?: MainQuotaWriter;
+      reserveAuthorization?: MainReserveAuthorization;
       accessToken: string;
       chatgptAccountId: string;
       /** Bypass Pool selection and suppress quota/transient failover for an exact selector. */
@@ -283,6 +299,182 @@ export class CodexAccountCooldownError extends Error {
   }
 }
 
+export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
+  readonly resetAt?: number;
+
+  constructor(resetAt?: number) {
+    super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
+    this.name = "CodexMainAccountHardLockError";
+    this.resetAt = resetAt;
+    this.message = "Codex main account is blocked by the 99% main-account quota policy."
+      + " Choose another account, wait for quota to reset, or disable codexMainAccountHardLock in Settings.";
+  }
+}
+
+export class CodexReserveUnavailableError extends CodexAccountCooldownError {
+  constructor() {
+    super(MAIN_CODEX_ACCOUNT_ID, 0);
+    this.name = "CodexReserveUnavailableError";
+    this.message = "Codex Reserve is unavailable for this main credential."
+      + " Use the stored main login or its matching caller credential, and retry when OpenAI grants Reserve access."
+      + " Reserve compatibility requires the effective local Desktop authless opt-in; it cannot switch accounts automatically.";
+  }
+}
+
+/** A local unsupported-helper refusal; retain Reserve policy error mapping on delayed sends. */
+export class CodexReserveHelperUnsupportedError extends CodexReserveUnavailableError {
+  constructor() {
+    super();
+    this.name = "CodexReserveHelperUnsupportedError";
+    this.message = CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE;
+  }
+}
+
+export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
+  "codexMainAccountHardLock" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
+>>;
+
+interface CodexAuthMaterializationOptions {
+  substituteMainCredential?: boolean;
+  config?: CodexAuthPolicyConfig;
+  modelId?: string;
+  /** Trusted receiving-listener admission; never inferred from request headers or config. */
+  admission?: Pick<DataPlaneAdmission, "source">;
+  signal?: AbortSignal;
+  nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
+  beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
+}
+
+function requiresReserveAuthorization(
+  config: CodexAuthPolicyConfig | undefined,
+  modelId: string | undefined,
+  admission: Pick<DataPlaneAdmission, "source"> | undefined,
+): boolean {
+  return modelId === NATIVE_RESERVE_MODEL && !!config && isCodexReserveRequestEligible(config, admission);
+}
+
+function assertReserveAdmission(config: CodexAuthPolicyConfig): void {
+  if (config.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID) || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) {
+    throw new CodexReserveUnavailableError();
+  }
+  assertMainAccountPolicy(config);
+  const cooldown = getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, "reserve");
+  if (cooldown?.cooldownUntil) {
+    throw new CodexAccountCooldownError(MAIN_CODEX_ACCOUNT_ID, cooldown.cooldownUntil, cooldown.cooldownSource, cooldown.quotaScope);
+  }
+}
+
+async function authorizeReserveCredential(
+  token: { accessToken: string; chatgptAccountId: string },
+  writer: MainQuotaWriter | undefined,
+  config: CodexAuthPolicyConfig,
+  signal?: AbortSignal,
+  existing?: MainReserveAuthorization,
+  writerGeneration = captureConfigGeneration(),
+): Promise<MainReserveAuthorization> {
+  assertReserveAdmission(config);
+  if (!writer || !isMainQuotaWriterLive(writer)
+    || !matchesMainQuotaCredential(token.accessToken, token.chatgptAccountId)) {
+    throw new CodexReserveUnavailableError();
+  }
+  const authorization = isMainReserveAuthorizationLive(existing, token) ? existing
+    : await getMainReserveAuthorization({
+      token, writer, signal,
+      observeOrdinaryQuota(data, capturedWriter) {
+        setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, parseUsageQuota(data), writerGeneration,
+          capturedWriter, parseMainPolicyUsageQuota(data));
+      },
+    });
+  // The capability read also publishes ordinary quota. A new 99% reading or cooldown wins.
+  assertReserveAdmission(config);
+  if (signal?.aborted) throw signal.reason;
+  if (!authorization || !isMainReserveAuthorizationLive(authorization, token)) throw new CodexReserveUnavailableError();
+  return authorization;
+}
+
+function selectedCodexToken(headers: Headers): { accessToken: string; chatgptAccountId: string } {
+  return {
+    accessToken: headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim() ?? "",
+    chatgptAccountId: headers.get("chatgpt-account-id") ?? "",
+  };
+}
+
+function assertMaterializedReserve(headers: Headers, ctx: CodexAuthContext, options: CodexAuthMaterializationOptions): void {
+  if (!requiresReserveAuthorization(options.config, options.modelId, options.admission)) return;
+  assertReserveAdmission(options.config!);
+  if (ctx.kind === "pool" || !isMainReserveAuthorizationLive(ctx.reserveAuthorization, selectedCodexToken(headers))) {
+    throw new CodexReserveUnavailableError();
+  }
+}
+
+/** A dispatch never renews permission: the next request may obtain a fresh bounded proof. */
+export function createCodexReserveDispatchGuard(
+  ctx: CodexAuthContext,
+  config: CodexAuthPolicyConfig,
+  modelId: string,
+  admission?: Pick<DataPlaneAdmission, "source">,
+  terminalHelper = false,
+): ((headers: Headers) => void) | undefined {
+  // Snapshot the resolved source value, not the caller's mutable admission object. Config stays
+  // live so policy changes remain visible after pacing and retry backoff.
+  const source = admission?.source;
+  if (modelId !== NATIVE_RESERVE_MODEL || source !== "loopback") return undefined;
+  // Only immutable request facts decide whether to install the callback. Flag/role eligibility
+  // is checked inside it, including an opt-in enabled while a send waits for pacing or WS open.
+  const ingress = Object.freeze({ source });
+  return headers => {
+    if (isCodexReserveHelperUnsupported(config, modelId, ingress, terminalHelper)) {
+      throw new CodexReserveHelperUnsupportedError();
+    }
+    assertMaterializedReserve(headers, ctx, { config, modelId, admission: ingress });
+  };
+}
+
+/** Retry history must not turn a later local admission refusal into a network failure. */
+export function unwrapUpstreamRetryEvidenceError(error: unknown): unknown {
+  const seen = new Set<unknown>();
+  while (error instanceof UpstreamRetryEvidenceError && !seen.has(error)) {
+    seen.add(error);
+    error = error.cause;
+  }
+  return error;
+}
+
+function assertMainAccountPolicy(config: Pick<OcxConfig, "codexMainAccountHardLock"> | undefined): void {
+  if (!config) return;
+  const status = getMainAccountHardLockStatus(config);
+  if (status.state === "blocked") throw new CodexMainAccountHardLockError(status.resetAt);
+}
+
+/** No auth-file I/O: an unsigned claim alone never identifies a caller as stored main. */
+function callerMatchesObservedMain(headers: Headers): boolean {
+  const bearer = headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!bearer) return false;
+  const effectiveAccountId = headers.get("chatgpt-account-id")
+    ?? extractAccountId(undefined, bearer);
+  return matchesMainQuotaCredential(bearer, effectiveAccountId);
+}
+
+function captureObservedMainWriter(): MainQuotaWriter | undefined {
+  const identityKey = getObservedMainQuotaIdentityKey();
+  return identityKey === undefined ? undefined : {
+    identityKey,
+    identityGeneration: captureMainAccountIdentityGeneration(),
+  };
+}
+
+function observeSelectedMainCredential(
+  token: { accessToken: string; chatgptAccountId: string },
+  writer: MainQuotaWriter | undefined,
+): MainQuotaWriter | undefined {
+  if (!writer) return undefined;
+  // Carry an explicitly stale writer through to quota's rejection fence; turning it into an
+  // untagged write would instead invalidate the replacement account's trusted observation.
+  if (!isMainQuotaWriterLive(writer)) return writer;
+  const observed = observeMainQuotaCredential(token.accessToken, token.chatgptAccountId);
+  return observed?.identityKey === writer.identityKey ? writer : undefined;
+}
+
 /**
  * Human-readable account label for a client-visible error. NEVER the raw id: the proxy
  * supports non-loopback binds (auth-cors.ts `isApiAuthRequired` requires a token there
@@ -300,12 +492,12 @@ export function cooldownAccountLabel(accountId: string): string {
  * injected `openai_base_url` in config.toml.
  */
 export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSelector?: string): string {
+  if (err instanceof CodexMainAccountHardLockError || err instanceof CodexReserveUnavailableError) return err.message;
   const until = new Date(err.cooldownUntil).toISOString();
-  const scope = err.quotaScope === "spark"
-    ? "Spark quota"
-    : err.quotaScope === "shared"
-      ? "shared native quota"
-      : null;
+  const scopeLabels: Record<CodexQuotaScope, string> = {
+    spark: "Spark quota", shared: "shared native quota", reserve: "Reserve quota",
+  };
+  const scope = err.quotaScope ? scopeLabels[err.quotaScope] : null;
   const selected = accountSelector
     ? `Selected Codex account selector (${accountSelector})`
     : `Selected Codex account (${cooldownAccountLabel(err.accountId)})`;
@@ -325,7 +517,10 @@ export function cooldownErrorResponse(
 ): Response {
   const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err, accountSelector));
   const headers = new Headers(res.headers);
-  headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
+  if (!(err instanceof CodexReserveUnavailableError)
+    && (!(err instanceof CodexMainAccountHardLockError) || err.resetAt !== undefined)) {
+    headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
+  }
   return new Response(res.body, { status: res.status, headers });
 }
 
@@ -340,7 +535,9 @@ export class CodexThreadAffinityExpiredError extends Error {
 }
 
 export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
-  return !(cause instanceof CodexCredentialGenerationConflictError)
+  return !(cause instanceof CodexMainAccountHardLockError)
+    && !(cause instanceof CodexReserveUnavailableError)
+    && !(cause instanceof CodexCredentialGenerationConflictError)
     && !(cause instanceof CodexCredentialRefreshLockTimeoutError)
     && !(cause instanceof CodexCredentialRefreshBusyError)
     && !(cause instanceof CodexCredentialRefreshStaleError)
@@ -352,6 +549,9 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
 }
 
 export interface ResolveCodexAuthContextOptions {
+  admission?: Pick<DataPlaneAdmission, "source">;
+  /** Live policy owner when the routing config is a caller-specific replay snapshot. */
+  codexAuthPolicy?: CodexAuthPolicyConfig;
   excludeAccountId?: string;
   /** Resolve exactly this account without consulting or mutating Pool selection. */
   accountId?: string;
@@ -389,14 +589,21 @@ export async function resolveCodexAuthContext(
   options: ResolveCodexAuthContextOptions = {},
 ): Promise<CodexAuthContext> {
   const writerGeneration = captureConfigGeneration();
+  const policy = options.codexAuthPolicy ?? config;
   const requestScopedMainCredential = options.requestScopedMainCredential === true
     && hasCallerCodexBearer(headers);
-  const fixedAccountId = options.accountId;
+  const reserve = requiresReserveAuthorization(policy, options.modelId, options.admission);
+  if (reserve && (options.excludeAccountId !== undefined
+    || (options.accountId !== undefined && options.accountId !== MAIN_CODEX_ACCOUNT_ID))) {
+    throw new CodexReserveUnavailableError();
+  }
+  const fixedAccountId = reserve ? MAIN_CODEX_ACCOUNT_ID : options.accountId;
   const preserveRequestOwnedMainPin = requestScopedMainCredential
     && fixedAccountId === undefined
     && config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
     && isEffectiveCodexAccountPinned(config)
-    && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
+    && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
+    && !(callerMatchesObservedMain(headers) && isMainAccountHardLocked(policy))
     && requestOwnedMainPinHasQuotaHeadroom(config);
   if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
     throw new Error("Codex auth context cannot select and exclude an account simultaneously");
@@ -405,6 +612,14 @@ export async function resolveCodexAuthContext(
     if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
     const substituteStoredMain = options.substituteMainCredentialForDirect === true;
     if (!substituteStoredMain) {
+      if (callerMatchesObservedMain(headers)) assertMainAccountPolicy(policy);
+      if (reserve) {
+        const selected = materializeCodexUpstreamAuth(headers, { kind: "main", accountId: null }, { config: policy });
+        const token = selectedCodexToken(selected);
+        const reserveAuthorization = await authorizeReserveCredential(token, captureMainQuotaWriter(token.chatgptAccountId),
+          policy, options.signal, undefined, writerGeneration);
+        return { kind: "main", accountId: null, reserveAuthorization };
+      }
       if (options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)) {
         const entitled = await (
           options.isDirectCallerEntitledToCodexModel ?? isDirectCallerEntitledToCodexModel
@@ -413,6 +628,7 @@ export async function resolveCodexAuthContext(
           throw new CodexPoolAuthenticationError("The selected ChatGPT account does not support this model");
         }
       }
+      if (callerMatchesObservedMain(headers)) assertMainAccountPolicy(policy);
       return { kind: "main", accountId: null };
     }
 
@@ -432,6 +648,8 @@ export async function resolveCodexAuthContext(
       ) {
         throw new CodexMainProfileDrainingError();
       }
+      if (policy.codexMainAccountHardLock === true) reconcileMainCodexAccountRuntimeState();
+      assertMainAccountPolicy(policy);
       if (options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)) {
         const entitled = entitledCodexAccountIdsForModel(
           await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config, {
@@ -444,6 +662,7 @@ export async function resolveCodexAuthContext(
           throw new CodexPoolAuthenticationError("The selected ChatGPT account does not support this model");
         }
       }
+      assertMainAccountPolicy(policy);
       return { kind: "main", accountId: null };
     } finally {
       // The short selector reservation ends here. A successful claim remains owned by
@@ -462,13 +681,17 @@ export async function resolveCodexAuthContext(
       || await (
         options.isDirectCallerEntitledToCodexModel ?? isDirectCallerEntitledToCodexModel
       )(headers, options.modelId);
-    if (callerEntitled) return { kind: "main", accountId: null };
+    if (callerEntitled && !(callerMatchesObservedMain(headers) && isMainAccountHardLocked(policy))) {
+      return { kind: "main", accountId: null };
+    }
   }
   // An explicit namespace binding is stronger than the provider's default mode. It must use the
   // selected stored credential even while the canonical OpenAI provider is globally Direct.
   // A request-owned bearer is deliberately not represented as `main-pool`: Pool account ids own
   // durable health, quota, and affinity state, while this credential exists for one request only.
-  if ((mode === "direct" && fixedAccountId === undefined)
+  if ((reserve && hasCallerCodexBearer(headers) && !options.substituteMainCredentialForDirect
+      && (requestScopedMainCredential || mode === "direct"))
+    || (mode === "direct" && fixedAccountId === undefined)
     || (requestScopedMainCredential && fixedAccountId === MAIN_CODEX_ACCOUNT_ID)) {
     return resolveCallerOwnedMainContext();
   }
@@ -523,6 +746,7 @@ export async function resolveCodexAuthContext(
     // A pre-drain selector reserves the native identity while reconciliation and
     // routing inspect it. Selectors arriving after the fence skip reconciliation
     // and may still route to non-main pool accounts without touching switch state.
+    if (reserve && !nativeMainReadsForbidden && !selectionAdmission) throw new CodexMainProfileDrainingError();
     if (!nativeMainReadsForbidden) reconcileMainCodexAccountRuntimeState();
     const resolution = fixedAccountId !== undefined
       ? { status: "selected" as const, accountId: fixedAccountId }
@@ -577,6 +801,11 @@ export async function resolveCodexAuthContext(
       if (nativeMainReadsForbidden && !options.excludeAccountId) {
         throw new CodexMainProfileDrainingError();
       }
+      if (!nativeMainReadsForbidden && options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
+        && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
+        && (!modelEligibleAccountIds || modelEligibleAccountIds.has(MAIN_CODEX_ACCOUNT_ID))) {
+        assertMainAccountPolicy(policy);
+      }
       throw new CodexPoolAuthenticationError(
         modelEligibleAccountIds === undefined
           ? undefined
@@ -586,6 +815,7 @@ export async function resolveCodexAuthContext(
       );
     }
     accountId = selected;
+    if (accountId === MAIN_CODEX_ACCOUNT_ID) assertMainAccountPolicy(policy);
     if (accountId === MAIN_CODEX_ACCOUNT_ID && nativeMainTrafficBlocked) {
       throw new CodexMainProfileDrainingError();
     }
@@ -608,7 +838,7 @@ export async function resolveCodexAuthContext(
       );
     }
     if (fixedAccountId !== undefined) {
-      if (isCodexAccountPaused(config, accountId)) {
+      if (policy.pausedCodexAccountIds?.includes(accountId)) {
         throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
       }
       if (isAccountNeedsReauth(accountId)) {
@@ -662,14 +892,18 @@ export async function resolveCodexAuthContext(
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
     // Main account in rotation: refresh auth.json before upstream I/O and fail closed if it vanished.
     let token: { accessToken: string; chatgptAccountId: string } | null;
+    let mainQuotaWriter = captureObservedMainWriter();
     try {
       token = await (options.getValidMainAccountToken ?? getValidMainAccountToken)({
         signal: options.signal,
         ...(options.nativeMainRefreshDependencies ?? {}),
       });
+      if (token) mainQuotaWriter = observeSelectedMainCredential(token, mainQuotaWriter);
+      assertMainAccountPolicy(policy);
     } catch (cause) {
       if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
       else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
+      if (cause instanceof CodexMainAccountHardLockError) throw cause;
       if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
         markAccountNeedsReauth(accountId, writerGeneration);
       }
@@ -683,10 +917,15 @@ export async function resolveCodexAuthContext(
         fixedAccountId !== undefined ? "Selected Codex account is unavailable" : undefined,
       );
     }
+    const reserveAuthorization = reserve
+      ? await authorizeReserveCredential(token, mainQuotaWriter, policy, options.signal, undefined, writerGeneration)
+      : undefined;
     return {
       kind: "main-pool",
       accountId,
       writerGeneration,
+      mainQuotaWriter,
+      ...(reserveAuthorization ? { reserveAuthorization } : {}),
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
       ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
@@ -772,7 +1011,7 @@ export class CodexMainSubstitutionUnavailableError extends Error {
 export function materializeCodexUpstreamAuth(
   headers: Headers,
   ctx: CodexAuthContext,
-  options: { substituteMainCredential?: boolean } = {},
+  options: CodexAuthMaterializationOptions = {},
 ): Headers {
   const selected = new Headers();
   for (const name of FORWARD_HEADERS) {
@@ -782,6 +1021,11 @@ export function materializeCodexUpstreamAuth(
   if (ctx.kind === "pool" || ctx.kind === "main-pool") {
     selected.set("authorization", `Bearer ${ctx.accessToken}`);
     selected.set("chatgpt-account-id", ctx.chatgptAccountId);
+    if (ctx.kind === "main-pool") {
+      ctx.mainQuotaWriter = observeSelectedMainCredential(ctx, ctx.mainQuotaWriter);
+      assertMainAccountPolicy(options.config);
+    }
+    assertMaterializedReserve(selected, ctx, options);
     return selected;
   }
   if (ctx.kind === "main" && options.substituteMainCredential !== true
@@ -791,6 +1035,8 @@ export function materializeCodexUpstreamAuth(
     if (accountId) selected.set("chatgpt-account-id", accountId);
   }
   if (ctx.kind === "main" && options.substituteMainCredential === true) {
+    if (options.config?.codexMainAccountHardLock === true) reconcileMainCodexAccountRuntimeState();
+    const writer = captureObservedMainWriter();
     const stored = getMainAccountToken();
     // Fail BEFORE any upstream I/O. Falling through here would send the admission secret.
     if (!stored?.accessToken || !isMainAccountTokenLive()) {
@@ -798,20 +1044,66 @@ export function materializeCodexUpstreamAuth(
     }
     selected.set("authorization", `Bearer ${stored.accessToken}`);
     if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
+    observeSelectedMainCredential(stored, writer);
+    assertMainAccountPolicy(options.config);
+    assertMaterializedReserve(selected, ctx, options);
     return selected;
   }
+  if (callerMatchesObservedMain(selected)) assertMainAccountPolicy(options.config);
+  assertMaterializedReserve(selected, ctx, options);
   return selected;
 }
 
+/** The model producer, not an optional context marker, decides whether a grant is required. */
+async function materializeReserveUpstreamAuth(
+  headers: Headers,
+  ctx: CodexAuthContext,
+  options: CodexAuthMaterializationOptions,
+): Promise<Headers> {
+  if (ctx.kind === "pool") throw new CodexReserveUnavailableError();
+  const config = options.config!;
+  assertReserveAdmission(config);
+  const writerGeneration = ctx.kind === "main-pool" ? ctx.writerGeneration : captureConfigGeneration();
+  const storedMain = ctx.kind === "main"
+    && (options.substituteMainCredential === true || !hasCallerCodexBearer(headers));
+  let admission: CodexAccountSelectionAdmission | undefined;
+  let writer = ctx.kind === "main-pool" ? ctx.mainQuotaWriter : undefined;
+  try {
+    if (storedMain) {
+      if (isNativeMainTrafficBlocked()) throw new CodexMainProfileDrainingError();
+      admission = options.beginCodexAccountSelection?.();
+      if (!admission || admission.mainProfileDraining || !admission.claimMainProfile() || isNativeMainTrafficBlocked()) {
+        throw new CodexMainProfileDrainingError();
+      }
+      reconcileMainCodexAccountRuntimeState();
+      writer = captureObservedMainWriter();
+      assertReserveAdmission(config);
+    }
+    // Build the real credential first, without recursively requiring a not-yet-fetched proof.
+    // The ordinary hard lock remains enabled, including the post-refresh check.
+    const selected = await materializeCodexUpstreamAuthAsync(headers, ctx, {
+      ...options, modelId: undefined, substituteMainCredential: storedMain,
+    });
+    const token = selectedCodexToken(selected);
+    if (ctx.kind === "main-pool") writer = ctx.mainQuotaWriter;
+    else if (!storedMain) writer = captureMainQuotaWriter(token.chatgptAccountId);
+    ctx.reserveAuthorization = await authorizeReserveCredential(token, writer, config, options.signal,
+      ctx.reserveAuthorization, writerGeneration);
+    assertMaterializedReserve(selected, ctx, options);
+    return selected;
+  } finally {
+    admission?.release();
+  }
+}
+
 export async function materializeCodexUpstreamAuthAsync(
   headers: Headers,
   ctx: CodexAuthContext,
-  options: {
-    substituteMainCredential?: boolean;
-    signal?: AbortSignal;
-    nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
-  } = {},
+  options: CodexAuthMaterializationOptions = {},
 ): Promise<Headers> {
+  if (requiresReserveAuthorization(options.config, options.modelId, options.admission)) {
+    return materializeReserveUpstreamAuth(headers, ctx, options);
+  }
   if (ctx.kind !== "main" || options.substituteMainCredential !== true) {
     return materializeCodexUpstreamAuth(headers, ctx, options);
   }
@@ -820,6 +1112,8 @@ export async function materializeCodexUpstreamAuthAsync(
     const value = headers.get(name);
     if (value) selected.set(name, value);
   }
+  if (options.config?.codexMainAccountHardLock === true) reconcileMainCodexAccountRuntimeState();
+  const writer = captureObservedMainWriter();
   const stored = await getValidMainAccountToken({
     signal: options.signal,
     ...(options.nativeMainRefreshDependencies ?? {}),
@@ -827,12 +1121,22 @@ export async function materializeCodexUpstreamAuthAsync(
   if (!stored?.accessToken) throw new CodexMainSubstitutionUnavailableError();
   selected.set("authorization", `Bearer ${stored.accessToken}`);
   if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
+  observeSelectedMainCredential(stored, writer);
+  assertMainAccountPolicy(options.config);
+  // An opt-in enabled during token refresh must not turn a proof-less context into Reserve.
+  assertMaterializedReserve(selected, ctx, options);
   return selected;
 }
 
 /** @deprecated Prefer materializeCodexUpstreamAuth; kept for call sites without admission context. */
-export function headersForCodexAuthContext(headers: Headers, ctx: CodexAuthContext): Headers {
-  return materializeCodexUpstreamAuth(headers, ctx);
+export function headersForCodexAuthContext(
+  headers: Headers,
+  ctx: CodexAuthContext,
+  config?: CodexAuthPolicyConfig,
+  modelId?: string,
+  admission?: Pick<DataPlaneAdmission, "source">,
+): Headers {
+  return materializeCodexUpstreamAuth(headers, ctx, { config, modelId, admission });
 }
 
 export function isCodexAuthContextUsable(ctx: CodexAuthContext, config: OcxConfig): boolean {

package/src/codex/catalog/effort.ts

@@ -35,7 +35,8 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { generatedModelMetadata, readCatalog, readCodexCatalogPath } from "./parsing";
 import type { CatalogModel, RawEntry } from "./parsing";
 import { UPSTREAM_NATIVE_ENTRIES } from "./metadata";
-import { nativeOpenAiCapabilitySourceSlug, SELF_DESCRIBED_NATIVE_OPENAI_MODELS } from "./native-models";
+import { nativeOpenAiCapabilitySourceSlug, SELF_DESCRIBED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./native-models";
+import { isReserveCatalogProjection } from "./reserve";
 import { loadBundledCodexCatalog } from "./bundled";
 import type { BundledCatalogDeps, ReadonlyRawCatalog } from "./bundled";
 import { deriveEntry } from "./sync";
@@ -158,11 +159,14 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
     entry.supports_reasoning_summaries = model.supportsReasoningSummaries;
   }
   if (model.supportsServiceTier === true) {
+    const nativeFast = model.codexForwardNativeCapabilityAlias && Array.isArray(entry.service_tiers)
+      ? entry.service_tiers.find(tier => tier?.id === "priority")
+      : undefined;
     entry.default_service_tier = null;
     entry.service_tiers = [{
       id: "priority",
       name: "Fast",
-      description: model.fastTierDescription ?? "1.5x speed, increased usage",
+      description: model.fastTierDescription ?? nativeFast?.description ?? "1.5x speed, increased usage",
     }];
     entry.additional_speed_tiers = ["fast"];
   }
@@ -337,6 +341,10 @@ export function clampedDefaultEffort(original: string, surviving: readonly strin
   return (atOrBelow.at(-1) ?? ranked[0]!).effort;
 }
 
+function requiresExactReserveEfforts(entry: RawEntry): boolean {
+  return entry.slug === NATIVE_RESERVE_MODEL || isReserveCatalogProjection(entry);
+}
+
 export function clampEntryToCodexSupportedEfforts(
   entry: RawEntry,
   supported: ReadonlySet<string> | null,
@@ -347,6 +355,19 @@ export function clampEntryToCodexSupportedEfforts(
     : null;
   if (levels && levels.length > 0) {
     const kept = levels.filter(level => typeof level?.effort === "string" && supported.has(level.effort));
+    if (requiresExactReserveEfforts(entry)) {
+      entry.supported_reasoning_levels = kept;
+      if (kept.length === 0) {
+        // The list-level clamp removes this incompatible row; never invent another ladder.
+        delete entry.default_reasoning_level;
+      } else if (!kept.some(level => level.effort === entry.default_reasoning_level)) {
+        entry.default_reasoning_level = clampedDefaultEffort(
+          typeof entry.default_reasoning_level === "string" ? entry.default_reasoning_level : "",
+          kept.map(level => level.effort!),
+        );
+      }
+      return;
+    }
     entry.supported_reasoning_levels = kept.length > 0
       ? kept
       : CODEX_REASONING_LEVELS
@@ -377,7 +398,9 @@ export function clampCatalogModelsToObservedCodexSupport(
 
   const removed = new Set<string>();
   const affected: string[] = [];
-  for (const entry of models) {
+  for (let index = 0; index < models.length;) {
+    const entry = models[index]!;
+    const hadLadder = Array.isArray(entry.supported_reasoning_levels) && entry.supported_reasoning_levels.length > 0;
     const before = new Set(
       (Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels : [])
         .flatMap(level => typeof (level as { effort?: string })?.effort === "string"
@@ -399,11 +422,14 @@ export function clampCatalogModelsToObservedCodexSupport(
       : null;
     const lost = [...before].filter(effort => !after.has(effort));
     const defaultClamped = Boolean(beforeDefault && beforeDefault !== afterDefault);
-    if (lost.length > 0 || defaultClamped) {
+    const omitted = requiresExactReserveEfforts(entry) && hadLadder && after.size === 0;
+    if (lost.length > 0 || defaultClamped || omitted) {
       for (const effort of lost) removed.add(effort);
       if (defaultClamped && beforeDefault) removed.add(beforeDefault);
       if (typeof entry.slug === "string") affected.push(entry.slug);
     }
+    if (omitted) models.splice(index, 1);
+    else index += 1;
   }
 
   return {