@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/codex/auth-context.ts

@@ -1,5 +1,5 @@
 import type { PoolQuotaWriter } from "./quota-types";
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createHash, timingSafeEqual } from "node:crypto";
 import {
   CodexCredentialGenerationConflictError,
   CodexCredentialRefreshLockTimeoutError,
@@ -39,8 +39,20 @@ import {
   pickAlternateCodexAccount,
   resolveCodexAccountForThreadDetailed,
   type CodexAffinityDecision,
+  type CodexThreadResolution,
+  type TransientProbeGrant,
 } from "./routing";
+// The half-open TRANSIENT-HOLD lease (#4701). Not the quota-cooldown probe lease imported from
+// ./routing above -- different module, different domain, and a request never holds both.
+import { releaseTransientProbe } from "../routing/probe-lease";
 import {
+  codexConversationIdentity,
+  recordCodexThreadLineage,
+  resolveCodexThreadLineage,
+  type CodexThreadLineage,
+} from "./lineage";
+import {
+  cachedDeniedCodexAccountIdsForModel,
   entitledCodexAccountIdsForModel,
   isDirectCallerEntitledToCodexModel,
   resolveCodexModelEntitlements,
@@ -53,7 +65,6 @@ import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, parseUsageQuota, parseMainP
 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, extractEmail } from "../oauth/chatgpt";
 import { getMainAccountHardLockStatus, isMainAccountHardLocked } from "./main-account-hard-lock";
 import {
@@ -70,9 +81,6 @@ import type { DataPlaneAdmission } from "../server/auth-cors";
 import { getMainReserveAuthorization, isMainReserveAuthorizationLive, nativeUserIdClaims, 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);
-
 /**
  * A request-owned bearer cannot inspect the physical main credential for its plan, but cached
  * WHAM usage is still valid routing evidence for the same logical main account. Score it with
@@ -88,32 +96,90 @@ function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
   return usage >= CODEX_UNKNOWN_USAGE_SCORE || usage < threshold;
 }
 
-function boundedCodexAffinityComponent(value: string | null): string | undefined {
-  const normalized = value?.trim();
-  if (!normalized) return undefined;
-  if (retainedUtf8Bytes(normalized) > CODEX_AFFINITY_COMPONENT_MAX_BYTES) return undefined;
-  return normalized;
+/**
+ * Every thread keys as ITSELF, never as its parent (#4546, wp8).
+ *
+ * The old rule preferred `x-codex-parent-thread-id`, so every child of one parent bound under
+ * the RAW parent id -- one shared entry, unrelated to the root's own `app:HMAC(session, thread)`
+ * binding -- and a grandchild keyed on its own parent landed on a key nobody had ever bound.
+ * A child therefore started cold while its parent was being served warm somewhere, and no
+ * child could hold a binding of its own.
+ *
+ * Now a request with a `thread-id` keys as HMAC(session ?? parent, thread). A root is
+ * unchanged, a child gets an independent key, and a request naming only a parent rides the
+ * parent's lane under HMAC(parent, parent) -- the same one-to-one lane it always had, minus
+ * the caller-supplied identifier that used to sit in Pool state. Which requests produce no
+ * key at all is unchanged. First placement for a child is what consults the family, through
+ * `recordCodexThreadLineage` below and the placement hook in ./routing.
+ *
+ * The derivation itself lives in ./lineage so a lineage record's conversation key and the key
+ * the thread actually binds under can never drift apart.
+ */
+export function codexPoolAffinityKey(headers: Headers, now = Date.now()): string | undefined {
+  // `now` is threaded rather than read inside because a parent-only turn resolves its key
+  // through the recorded lineage, and that record is TTL-bounded: a caller working against a
+  // fixed clock would otherwise see a live record as expired and fall back to a key the parent
+  // never bound under.
+  return codexConversationIdentity(headers, now)?.conversationKey;
+}
+
+/** What a caller needs to know to answer the Pool-state question below before auth has run. */
+export interface CodexPoolStateEligibility {
+  /** An exact account selector from the route, i.e. `options.accountId` here. */
+  readonly accountId?: string;
+  readonly modelId?: string;
+  readonly admission?: Pick<DataPlaneAdmission, "source">;
+  /** The caller presented its own forwardable ChatGPT credential for this route. */
+  readonly requestScopedMainCredential?: boolean;
+}
+
+/** The one expression both the resolution below and any preview must agree on. */
+function poolStateEligible(
+  fixedAccountId: string | undefined,
+  requestScopedMainCredential: boolean,
+): boolean {
+  return fixedAccountId === undefined && !requestScopedMainCredential;
 }
 
 /**
- * Preserve Codex's parent-thread affinity when present. Desktop App requests can omit that
- * header while retaining a stable session/thread pair, so derive an opaque process-local key
- * only from the complete bounded pair. Raw identifiers and durable hashes never enter Pool state.
+ * May this request own Pool affinity state at all?
+ *
+ * Two credentials authenticate outside the Pool: an exact account selector (including the
+ * Reserve pin) and a request-owned main bearer, which exists for one request and must never
+ * fold into durable account state. Neither may read or write a binding, so neither may read
+ * or write LINEAGE either.
+ *
+ * Exported so that a preview asks the question with the code that answers it, instead of a
+ * restatement that can drift. It drifted once already: preview read a family relation from raw
+ * request headers before this function had decided anything, so it could follow a Pool family
+ * binding while the resolution below deliberately created no affinity -- and model fallback then
+ * evaluated eligibility against an account the request would never be authenticated as.
+ */
+export function codexPoolStateEligible(
+  headers: Headers,
+  policy: CodexAuthPolicyConfig | undefined,
+  options: CodexPoolStateEligibility = {},
+): boolean {
+  const reserve = requiresReserveAuthorization(policy, options.modelId, options.admission);
+  return poolStateEligible(
+    reserve ? MAIN_CODEX_ACCOUNT_ID : options.accountId,
+    options.requestScopedMainCredential === true && hasCallerCodexBearer(headers),
+  );
+}
+
+/**
+ * The lineage a PREVIEW is allowed to see: read-only, and only for a request that may hold Pool
+ * state. Recording is left to the resolution that actually binds, so a preview can never leave a
+ * record behind for a request that turned out to own no Pool state at all.
  */
-export function codexPoolAffinityKey(headers: Headers): string | undefined {
-  const parentThreadId = boundedCodexAffinityComponent(headers.get("x-codex-parent-thread-id"));
-  if (parentThreadId) return parentThreadId;
-
-  const sessionId = boundedCodexAffinityComponent(headers.get("session-id"));
-  const threadId = boundedCodexAffinityComponent(headers.get("thread-id"));
-  if (!sessionId || !threadId) return undefined;
-
-  return `app:${createHmac("sha256", CODEX_APP_AFFINITY_KEY)
-    .update("opencodex-app-pool-affinity-v1\0")
-    .update(sessionId)
-    .update("\0")
-    .update(threadId)
-    .digest("base64url")}`;
+export function previewCodexPoolLineage(
+  headers: Headers,
+  policy: CodexAuthPolicyConfig | undefined,
+  options: CodexPoolStateEligibility = {},
+): CodexThreadLineage | undefined {
+  return codexPoolStateEligible(headers, policy, options)
+    ? resolveCodexThreadLineage(headers)
+    : undefined;
 }
 
 export type CodexAuthContext =
@@ -142,6 +208,12 @@ export type CodexAuthContext =
       affinityDecision?: CodexAffinityDecision;
       /** Scope that owns `probeLeaseId`, when it is a scoped recovery probe. */
       probeQuotaScope?: CodexQuotaScope;
+      /**
+       * Set when this request is the ONE dispatch admitted to test an account held under a
+       * transient 5xx hold (#4701). Echo it into the upstream outcome so the trial is settled
+       * by the request that ran it, and release it on any path that never reaches upstream.
+       */
+      transientProbe?: TransientProbeGrant;
     }
   | {
       // Main Codex account participating in rotation: token injected from ~/.codex/auth.json
@@ -162,6 +234,8 @@ export type CodexAuthContext =
       probeLeaseId?: string;
       quotaScope?: CodexQuotaScope;
       probeQuotaScope?: CodexQuotaScope;
+      /** See `pool.transientProbe`. */
+      transientProbe?: TransientProbeGrant;
     };
 
 /** Probe lease carried by this context, when it holds one. */
@@ -174,11 +248,24 @@ export function codexProbeQuotaScope(ctx: CodexAuthContext | undefined): CodexQu
   return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeQuotaScope : undefined;
 }
 
+/** The transient-hold recovery probe carried by this context, when it holds one (#4701). */
+export function codexTransientProbeGrant(ctx: CodexAuthContext | undefined): TransientProbeGrant | undefined {
+  return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.transientProbe : undefined;
+}
+
 /**
  * Hand back a probe lease for a request that will not reach upstream. Safe to
  * call with a context that holds no lease.
+ *
+ * BOTH leases, deliberately. A context can carry the quota-cooldown probe or the transient-hold
+ * probe, and every one of the ~30 call sites that already hands back the first is a path where
+ * the second would leak too. Releasing them together is what makes those sites correct for the
+ * new lease without re-deriving the discard set by hand -- the failure mode being avoided is a
+ * held account nobody may probe because the request that held the trial went away quietly.
  */
 export function releaseCodexAuthContextProbeLease(ctx: CodexAuthContext | undefined): void {
+  const transientProbe = codexTransientProbeGrant(ctx);
+  if (transientProbe) releaseTransientProbe(transientProbe.lease);
   const leaseId = codexProbeLeaseId(ctx);
   if (!ctx || ctx.kind === "main" || !leaseId) return;
   if (ctx.probeQuotaScope) releaseCodexQuotaScopeProbeLease(ctx.accountId!, ctx.probeQuotaScope, leaseId);
@@ -364,6 +451,44 @@ export class CodexReserveHelperUnsupportedError extends CodexReserveUnavailableE
   }
 }
 
+/**
+ * Every account bound to this conversation is held after upstream failures, the recovery
+ * budget for this window is spent, and there is no detour left -- so this request is refused
+ * BEFORE any upstream I/O (#4701).
+ *
+ * This is not a quota cooldown, and the message below says so. It subclasses
+ * {@link CodexAccountCooldownError} for one reason: the deadline-carrying refusal has exactly
+ * one representation in this codebase, and roughly a dozen transports already map it to a 429
+ * with `Retry-After` and treat it as an expected terminal answer rather than a credential
+ * fault. Introducing a parallel type would mean either re-deriving that handling in every one
+ * of them or silently falling through to a 500 in the ones that were missed.
+ *
+ * What must NOT be inherited is the quota wording -- "cooling down", `ocx account
+ * clear-cooldown` -- because none of it describes a 5xx hold and following it would do
+ * nothing. {@link cooldownErrorMessage} therefore returns this class's own message verbatim,
+ * the same escape hatch {@link CodexMainAccountHardLockError} and
+ * {@link CodexReserveUnavailableError} already use.
+ *
+ * `cooldownUntil` carries the limiter's own change point, which is strictly in the future:
+ * either the moment the held account may next be probed or the moment the recovery window
+ * moves, whichever is later. A refusal that answered `now` would busy-loop the caller into
+ * the same load it just declined.
+ */
+export class CodexRecoveryWithheldError extends CodexAccountCooldownError {
+  /** The sibling still remembered for this thread, when one exists but is itself unusable. */
+  readonly detourAccountId?: string;
+
+  constructor(accountId: string, retryAt: number, detourAccountId?: string) {
+    super(accountId, retryAt);
+    this.name = "CodexRecoveryWithheldError";
+    this.detourAccountId = detourAccountId;
+    this.message = `Codex account (${cooldownAccountLabel(accountId)}) is held after repeated upstream`
+      + ` failures and the pool's recovery budget for this window is spent, so nothing was sent`
+      + ` upstream. Retry after ${new Date(retryAt).toISOString()}.`
+      + " This clears on its own as the account recovers; no cooldown to lift and no account to switch.";
+  }
+}
+
 export type CodexAuthPolicyConfig = Readonly<Pick<OcxConfig,
   "codexMainAccountHardLock" | "codexDesktopAuthless" | "runtimeRole" | "pausedCodexAccountIds"
 >>;
@@ -574,7 +699,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;
+  if (err instanceof CodexMainAccountHardLockError
+    || err instanceof CodexReserveUnavailableError
+    // A transient-hold refusal is not a quota cooldown. Its own wording is the only accurate
+    // one, and the quota recovery advice below would send the operator after a cooldown that
+    // does not exist (#4701).
+    || err instanceof CodexRecoveryWithheldError) return err.message;
   const until = new Date(err.cooldownUntil).toISOString();
   const scopeLabels: Record<CodexQuotaScope, string> = {
     shared: "shared native quota", reserve: "Reserve quota",
@@ -657,6 +787,11 @@ export interface ResolveCodexAuthContextOptions {
   requestScopedMainCredential?: boolean;
   /** Test seam for a Direct request's own forwarded ChatGPT credential. */
   isDirectCallerEntitledToCodexModel?: (headers: Headers, modelId: string) => Promise<boolean>;
+  /**
+   * This request's conversation carries live uploaded-file references (#4778). Retains the bound
+   * account across a VOLUNTARY quota move; involuntary release is untouched.
+   */
+  retainAccountForUploadedFiles?: boolean;
 }
 
 export interface CodexAccountSelectionAdmission {
@@ -798,12 +933,27 @@ export async function resolveCodexAuthContext(
   // A caller bearer can still accompany a request that selects a configured Pool account. Do not
   // let that request read, delete, or create a file-main affinity binding while deciding whether a
   // stored account is available; only the stored credential selected below may own Pool state.
-  const affinityKey = fixedAccountId === undefined && !requestScopedMainCredential
+  const affinityKey = poolStateEligible(fixedAccountId, requestScopedMainCredential)
     ? codexPoolAffinityKey(headers)
     : undefined;
+  // The thread's family relation, recorded under the same condition as the key itself. A
+  // first-placing child consults it; a request-owned or fixed credential never enters Pool
+  // state, so it never enters lineage either.
+  const lineage = affinityKey !== undefined
+    ? recordCodexThreadLineage(headers)
+    : undefined;
   // Why this request is on this account, carried to the request log so a move reads as an event
   // instead of something inferred from account labels across lines (#4546).
   let affinityDecision: CodexAffinityDecision | undefined;
+  // The half-open trial this request was granted, if it is the one allowed to test a held
+  // account. Declared out here because the release paths below and the returned context are on
+  // opposite sides of several throws (#4701).
+  let transientProbe: TransientProbeGrant | undefined;
+  const releaseTransientProbeGrant = (): void => {
+    if (!transientProbe) return;
+    releaseTransientProbe(transientProbe.lease);
+    transientProbe = undefined;
+  };
   // Retained startup recovery makes the physical main identity ineligible. Routing
   // can still preserve service by selecting a healthy configured pool account. A
   // request-owned bearer likewise cannot inspect or reconcile file-main state.
@@ -834,6 +984,23 @@ export async function resolveCodexAuthContext(
     const modelEligibleAccountIds = entitledAccountIds
       ? new Set([...entitledAccountIds].filter(candidate => !excludeAccountIds?.has(candidate)))
       : undefined;
+    // #4768: the flagships stay visible and never fail closed, so this is evidence routing may
+    // ORDER by, not evidence it may refuse on. Read synchronously from rosters discovery has
+    // already gathered -- no upstream fetch joins the request path for the most commonly
+    // requested models in the product -- and passed to selection as a preference that is dropped
+    // whenever honouring it would leave no candidate.
+    //
+    // Under the SAME exclusion the entitlement snapshot above uses. The reader validates each
+    // cached roster against the account's current credential, and for native main that is a
+    // synchronous read of the physical stored token -- exactly what this request is forbidden to
+    // touch while a profile switch drains it or while it is served by a request-owned credential.
+    // Excluding main here costs nothing: the preference is an ordering hint, so main becomes
+    // unknown rather than denied, and unknown leaves selection exactly as it was.
+    const deniedModelAccountIds = cachedDeniedCodexAccountIdsForModel(
+      options.modelId,
+      undefined,
+      { excludeAccountIds },
+    );
     const selectionOptions = {
       // Temporary switch drain keeps the candidate until the atomic claim rejects
       // it. Retained recovery makes main wholly ineligible so pool routing continues.
@@ -845,13 +1012,21 @@ export async function resolveCodexAuthContext(
         ? () => preserveRequestOwnedMainPin
         : options.isMainAccountTokenLive,
       modelEligibleAccountIds,
+      deniedModelAccountIds,
+      // Request-scoped and deliberately absent from `sharedStateSelectionOptions`: one
+      // conversation's attachments say nothing about where unrelated threads should be served.
+      retainAccountForUploadedFiles: options.retainAccountForUploadedFiles === true,
     };
     // 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
+    // Annotated, not inferred. The two literals below carry neither `affinity` nor
+    // `transientProbe`, so an inferred union makes `"k" in resolution` widen those reads to
+    // `unknown` and a discriminant narrowing fail outright. Contextually typing every branch to
+    // the resolver's own union is what lets the reads below stay total.
+    const resolution: CodexThreadResolution = fixedAccountId !== undefined
       ? { status: "selected" as const, accountId: fixedAccountId }
       : options.excludeAccountId
       ? (() => {
@@ -873,10 +1048,20 @@ export async function resolveCodexAuthContext(
           quotaScope,
           selectionOptions,
           options.modelId,
+          lineage,
         );
     if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
+    // THE REFUSAL. Every candidate is held, the recovery budget is spent, and no detour is
+    // left -- so this request must not reach upstream at all. Returning the held account here
+    // is what #4701 is about: under a provider-wide 503 that is every bound request piling
+    // onto an account already known to be failing. Thrown before any credential is read, so
+    // nothing is sent and nothing is spent.
+    if (resolution.status === "withheld") {
+      throw new CodexRecoveryWithheldError(resolution.accountId, resolution.retryAt, resolution.detourAccountId);
+    }
     const selected = resolution.status === "selected" ? resolution.accountId : null;
-    affinityDecision = "affinity" in resolution ? resolution.affinity : undefined;
+    affinityDecision = resolution.affinity;
+    transientProbe = resolution.status === "selected" ? resolution.transientProbe : undefined;
     if (!selected) {
       // A retry that excluded a failed Pool account may still use the validated caller-owned
       // main credential. Treating every exclusion as if main itself had failed strands a healthy
@@ -958,12 +1143,25 @@ export async function resolveCodexAuthContext(
         throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
       }
     }
+  } catch (cause) {
+    // Selection granted a trial and then a later policy check refused the account. The trial
+    // never runs, so hand it back instead of leaving the held account unprobeable until its
+    // deadline lapses (#4701).
+    releaseTransientProbeGrant();
+    throw cause;
   } finally {
     selectionAdmission?.release();
   }
   // Legacy selectors may retain an unusable account for actionable errors. A
   // deferred credential must never become request auth through that fallback.
-  assertCodexAccountValidationReady(accountId);
+  try {
+    assertCodexAccountValidationReady(accountId);
+  } catch (cause) {
+    // Nothing will reach upstream, so give the trial back instead of leaving the held account
+    // unprobeable until the lease deadline lapses (#4701).
+    releaseTransientProbeGrant();
+    throw cause;
+  }
   // Lazy prime: if the selected account has no quota yet, the pool is likely
   // unprimed (dashboard never opened, or startup prime was blocked). Kick a
   // best-effort prime so the NEXT routing decision has real scores. This never
@@ -982,6 +1180,13 @@ export async function resolveCodexAuthContext(
   // a literal Retry-After reads very differently to a user than a reset-derived guess.
   const cooldown = getCodexQuotaHealthSnapshot(accountId, quotaScope);
   const cooldownUntil = cooldown?.cooldownUntil;
+  // A transient-hold trial and a quota cooldown cannot both describe this account:
+  // `isTransientOnlyAffinityBlock` refuses to recognise a transient hold on an account carrying
+  // quota health, so the cooldown branch below is unreachable while a trial is held. That is
+  // also why no request pays two recovery permits for one send. The release is defensive --
+  // should that invariant ever move, the trial is handed back rather than stranded behind a
+  // refusal that belongs to the other domain.
+  if (cooldownUntil && transientProbe) releaseTransientProbeGrant();
   // A cooled-down account never sends traffic, so upstream recovery can never be
   // observed and the cooldown outlives the real limit. Admit one probe per
   // interval; its outcome decides whether the cooldown ends (#433).
@@ -1022,6 +1227,7 @@ export async function resolveCodexAuthContext(
       if (token) mainQuotaWriter = observeSelectedMainCredential(token, mainQuotaWriter);
       assertMainAccountPolicy(policy);
     } catch (cause) {
+      releaseTransientProbeGrant();
       if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
       else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
       if (cause instanceof CodexMainAccountHardLockError) throw cause;
@@ -1032,15 +1238,23 @@ export async function resolveCodexAuthContext(
     }
     if (!token) {
       // Nothing will reach upstream, so give the probe back instead of burning it.
+      releaseTransientProbeGrant();
       if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
       else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
       throw new CodexPoolAuthenticationError(
         fixedAccountId !== undefined ? "Selected Codex account is unavailable" : undefined,
       );
     }
-    const reserveAuthorization = reserve
-      ? await authorizeReserveCredential(token, mainQuotaWriter, policy, options.signal, undefined, writerGeneration)
-      : undefined;
+    let reserveAuthorization: MainReserveAuthorization | undefined;
+    try {
+      reserveAuthorization = reserve
+        ? await authorizeReserveCredential(token, mainQuotaWriter, policy, options.signal, undefined, writerGeneration)
+        : undefined;
+    } catch (cause) {
+      // A Reserve refusal ends the request here, so the trial it was holding never runs.
+      releaseTransientProbeGrant();
+      throw cause;
+    }
     return {
       kind: "main-pool",
       accountId,
@@ -1054,6 +1268,7 @@ export async function resolveCodexAuthContext(
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
+      ...(transientProbe ? { transientProbe } : {}),
     };
   }
 
@@ -1074,8 +1289,10 @@ export async function resolveCodexAuthContext(
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
       ...(affinityDecision ? { affinityDecision } : {}),
+      ...(transientProbe ? { transientProbe } : {}),
     };
   } catch (cause) {
+    releaseTransientProbeGrant();
     if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
     else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
     if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {

package/src/codex/catalog/aggregation.ts

@@ -34,7 +34,7 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 
 import { catalogModelSlug } from "./parsing";
-import type { CatalogModel } from "./parsing";
+import type { CatalogModel, RawEntry } from "./parsing";
 
 export const openAiApiCollisionWarnings = new Set<string>();
 
@@ -222,6 +222,85 @@ export function safeCatalogWarningLabel(value: string): string {
     .slice(0, 200);
 }
 
+/**
+ * Keep the first row of each slug and drop the rest (#4730).
+ *
+ * First-win is the only answer that agrees with the ordering already decided upstream: the merge
+ * ranks rows, so its first occurrence is the row it chose. Distinct slugs are never touched — an
+ * alias row and the canonical routed row of the same provider model are two different public names
+ * and both survive — and a row without a string slug passes through untouched.
+ */
+export function dedupeCatalogEntriesBySlug(models: RawEntry[]): RawEntry[] {
+  const seen = new Set<string>();
+  const out: RawEntry[] = [];
+  for (const entry of models) {
+    if (typeof entry.slug !== "string") {
+      out.push(entry);
+      continue;
+    }
+    if (seen.has(entry.slug)) continue;
+    seen.add(entry.slug);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Every slug this proxy writes into the Codex catalog must appear exactly once (#4730).
+ *
+ * The cost of breaking it is the whole file: a slug-unique validating consumer refuses the catalog
+ * outright, so one duplicated row takes every model with it. A 2.56.0 report carried 507 rows for
+ * 72 unique slugs, every duplicate byte-identical, and Codex rejected the file as `source-invalid`.
+ *
+ * This is a write-boundary invariant rather than a repair of one producer, and that distinction is
+ * deliberate: the reported catalog is evidence that some emit path can double a row, but nothing in
+ * this tree has been shown to be that path, and a guard that only covered the producer someone
+ * guessed at would leave the file corruptible by the next one. Both writers that serialize a merged
+ * catalog call this as their LAST mutation — `writeRetainedCatalogSync` and the management
+ * convergence commit — so uniqueness holds for the exact bytes that land on disk.
+ *
+ * Ordering is load-bearing. Running the guard before the effort clamp would be unsound:
+ * `clampCatalogModelsToObservedCodexSupport` splices whole rows out when an exact-reserve ladder
+ * clamps empty, so dropping a later same-slug row first can leave the slug with no row at all once
+ * the surviving one is spliced.
+ *
+ * @param models - The finished row list, already clamped and finalized.
+ * @param warn - Whether to report on `console.warn`. The convergence path merges under
+ *   `warningPolicy: "suppress"` and stays silent for the same reason.
+ * @returns The original array when it was already unique, so an unchanged catalog stays a no-op
+ *   write; otherwise a first-win copy.
+ */
+export function enforceCatalogSlugUniqueness(models: RawEntry[], warn: boolean): RawEntry[] {
+  const deduped = dedupeCatalogEntriesBySlug(models);
+  if (deduped.length === models.length) return models;
+  if (warn) {
+    // A dropped row that differs from the kept one means two emit paths disagree about the same
+    // slug's content. First-win still stands, but the operator needs to see WHICH slugs diverged
+    // instead of silently losing data. The baseline is the row the dedupe actually keeps — the
+    // FIRST occurrence — so the reported divergence is measured against what lands on disk.
+    const keptBySlug = new Map<string, RawEntry>();
+    for (const entry of models) {
+      if (typeof entry.slug !== "string" || keptBySlug.has(entry.slug)) continue;
+      keptBySlug.set(entry.slug, entry);
+    }
+    const divergentSlugs = new Set<string>();
+    for (const entry of models) {
+      if (typeof entry.slug !== "string") continue;
+      const kept = keptBySlug.get(entry.slug);
+      if (kept && kept !== entry && JSON.stringify(kept) !== JSON.stringify(entry)) {
+        divergentSlugs.add(entry.slug);
+      }
+    }
+    const divergentNote = divergentSlugs.size > 0
+      ? `; divergent content on: ${[...divergentSlugs].slice(0, 5).map(safeCatalogWarningLabel).join(", ")}${divergentSlugs.size > 5 ? ", …" : ""}`
+      : "";
+    console.warn(
+      `[opencodex] catalog sync dropped ${models.length - deduped.length} duplicate slug row(s), keeping the first occurrence of each slug (#4730)${divergentNote}.`,
+    );
+  }
+  return deduped;
+}
+
 export function comboCatalogWarningSignature(
   combo: NormalizedComboConfig,
   members: readonly CatalogModel[],