@bitkyc08/opencodex 2.54.0-preview.20260914 → 2.55.0-preview.20260914

package/src/codex/auth-context.ts

@@ -38,6 +38,7 @@ import {
   tryAcquireCodexQuotaScopeProbeLease,
   pickAlternateCodexAccount,
   resolveCodexAccountForThreadDetailed,
+  type CodexAffinityDecision,
 } from "./routing";
 import {
   entitledCodexAccountIdsForModel,
@@ -137,6 +138,8 @@ export type CodexAuthContext =
       probeLeaseId?: string;
       /** Native model quota group selected for this request, when known. */
       quotaScope?: CodexQuotaScope;
+      /** What happened to this thread's binding on this request (#4546). */
+      affinityDecision?: CodexAffinityDecision;
       /** Scope that owns `probeLeaseId`, when it is a scoped recovery probe. */
       probeQuotaScope?: CodexQuotaScope;
     }
@@ -798,6 +801,9 @@ export async function resolveCodexAuthContext(
   const affinityKey = fixedAccountId === undefined && !requestScopedMainCredential
     ? codexPoolAffinityKey(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;
   // 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.
@@ -870,6 +876,7 @@ export async function resolveCodexAuthContext(
         );
     if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
     const selected = resolution.status === "selected" ? resolution.accountId : null;
+    affinityDecision = "affinity" in resolution ? resolution.affinity : 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
@@ -1066,6 +1073,7 @@ export async function resolveCodexAuthContext(
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
+      ...(affinityDecision ? { affinityDecision } : {}),
     };
   } catch (cause) {
     if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);

package/src/codex/autostart-health.ts

@@ -2,6 +2,7 @@ import { codexAutoStartEnabled } from "../config";
 import { diagnoseService, type ServiceDiagnostic } from "../service";
 import type { OcxConfig } from "../types";
 import { getCodexRoutingKind, type CodexRoutingKind } from "./inject";
+import { collectRoutingAdoption, type RoutingAdoptionEvidence } from "./routing-adoption";
 import { diagnoseCodexShim, type CodexShimDiagnostic } from "./shim";
 
 export type StartupProtection = "service" | "shim" | "none";
@@ -22,6 +23,7 @@ export interface StartupHealthInputs {
   shimHealthy: boolean;
   platform: NodeJS.Platform;
   diagnosticStale?: boolean;
+  routingAdoption?: RoutingAdoptionEvidence;
 }
 
 export interface StartupHealth {
@@ -51,6 +53,7 @@ export interface StartupHealth {
     installShim: string;
     restoreNative: string;
   };
+  routingAdoption?: RoutingAdoptionEvidence;
 }
 
 const COMMANDS = {
@@ -115,6 +118,7 @@ export interface StartupHealthDiagnostics {
   routingKind?: CodexRoutingKind;
   service?: ServiceDiagnostic;
   shim?: CodexShimDiagnostic;
+  routingAdoption?: RoutingAdoptionEvidence;
 }
 
 /** Collect current machine state without mutating config, services, or shims. */
@@ -124,8 +128,11 @@ export function collectStartupHealth(
 ): StartupHealth {
   const shim = diagnostics.shim ?? diagnoseCodexShim();
   const service = diagnostics.service ?? diagnoseService();
+  const routingKind = diagnostics.routingKind ?? getCodexRoutingKind();
+  const routingAdoption = diagnostics.routingAdoption
+    ?? (routingKind === "opencodex-local" ? collectRoutingAdoption({ routingKind }) : undefined);
   return deriveStartupHealth({
-    routingKind: diagnostics.routingKind ?? getCodexRoutingKind(),
+    routingKind,
     autostartEnabled: codexAutoStartEnabled(config),
     serviceInstalled: service.installed,
     serviceViable: service.viable,
@@ -137,10 +144,17 @@ export function collectStartupHealth(
     shimInstalled: shim.installed,
     shimHealthy: shim.healthy,
     platform: process.platform,
+    ...(routingAdoption ? { routingAdoption } : {}),
   });
 }
 
 export function startupHealthSummary(health: StartupHealth): string {
+  const summary = classifyStartupHealthSummary(health);
+  const action = pendingClientRestartAction(health);
+  return action ? `${summary}; ${action}` : summary;
+}
+
+function classifyStartupHealthSummary(health: StartupHealth): string {
   if (health.status === "native") return health.routingKind === "custom-remote"
     ? "custom remote Codex routing (no local restart dependency)"
     : "native Codex routing (no opencodex restart dependency)";
@@ -155,6 +169,24 @@ export function startupHealthSummary(health: StartupHealth): string {
   return `AT RISK after restart (no viable background service; run '${command}')`;
 }
 
+function pendingClientRestartAction(health: StartupHealth): string | null {
+  const adoption = health.routingAdoption;
+  if (adoption?.adoption !== "pending-client-restart") return null;
+  const pids = adoption.staleClients.map(client => client.pid);
+  if (pids.length === 0) return null;
+  const pidList = pids.join(", ");
+  return pids.length === 1
+    ? `restart Codex client pid ${pidList} so it adopts the injected proxy route`
+    : `restart Codex clients pid ${pidList} so they adopt the injected proxy route`;
+}
+
+function pendingClientRestartDetail(adoption: RoutingAdoptionEvidence | undefined): string | null {
+  if (adoption?.adoption !== "pending-client-restart") return null;
+  const pids = adoption.staleClients.map(client => client.pid);
+  if (pids.length === 0) return null;
+  return `clients=pending-restart(pid ${pids.join(", ")})`;
+}
+
 /**
  * The routing/service/shim token `ocx doctor` prints under restart safety.
  * Extracted so `ocx status` can show the same string rather than growing a
@@ -168,5 +200,7 @@ export function formatStartupRoutingDetail(health: StartupHealth): string {
   const shim = health.shimHealthy
     ? "healthy"
     : health.shimInstalled ? "stale" : "absent";
-  return `routing=${health.routingKind}, service=${service}, shim=${shim}`;
+  const base = `routing=${health.routingKind}, service=${service}, shim=${shim}`;
+  const token = pendingClientRestartDetail(health.routingAdoption);
+  return token ? `${base}, ${token}` : base;
 }

package/src/codex/catalog/provider-fetch.ts

@@ -418,6 +418,40 @@ function captureModelsRequest(
   });
 }
 
+/**
+ * Fill the registry seed's per-model numeric capability maps beneath the provider's own
+ * values, mutating `prov` in place. The merge is per key — an operator's entry always
+ * wins; a model the persisted map never mentions picks up its seed value — matching
+ * `mergeRecordFill` in src/router.ts exactly.
+ *
+ * Routing already performs this fill at resolve time (routedProviderConfig in
+ * src/router.ts) and the catalog did not, and that divergence is #4570:
+ * zhipu-bigmodel-coding/glm-5.3-flash reached the live catalog with correct modalities
+ * but no context window, because an install persisted before Flash joined the seed map
+ * held a truthy partial `modelContextWindows` that shadowed the whole seed.
+ *
+ * This lives here and not in enrichProviderFromRegistry because enrichment output is
+ * persisted on a management POST, and #1409 (pinned by
+ * tests/server/management-provider-validation.test.ts) requires that a save never write
+ * registry seed keys into the operator's config. The gather clone is detached and
+ * frozen, never saved, so the catalog can see the seed without the config gaining it.
+ */
+export function applyRegistryCapabilitySeedFill(name: string, prov: OcxProviderConfig): void {
+  // router.ts resolves the canonical OpenAI API provider's token maps with
+  // mergePositiveNumberCaps (user values cap the seed rather than replace it), so a
+  // plain fill here would give that one provider catalog semantics routing never has.
+  if (name === OPENAI_API_PROVIDER_ID) return;
+  if (!providerMatchesRegistryTransport(name, prov)) return;
+  const entry = getProviderRegistryEntry(name);
+  if (!entry) return;
+  if (entry.modelContextWindows || prov.modelContextWindows) {
+    prov.modelContextWindows = { ...(entry.modelContextWindows ?? {}), ...(prov.modelContextWindows ?? {}) };
+  }
+  if (entry.modelMaxOutputTokens || prov.modelMaxOutputTokens) {
+    prov.modelMaxOutputTokens = { ...(entry.modelMaxOutputTokens ?? {}), ...(prov.modelMaxOutputTokens ?? {}) };
+  }
+}
+
 function captureProviderGather(
   name: string,
   configured: OcxProviderConfig,
@@ -427,6 +461,7 @@ function captureProviderGather(
 ): CapturedProviderGather {
   const enriched = detachedClone(withCanonicalOpenAiForwardAuthDefault(name, configured));
   enrichProviderFromRegistry(name, enriched);
+  applyRegistryCapabilitySeedFill(name, enriched);
   const registryTransportMatch = providerMatchesRegistryTransport(name, enriched);
   const provider = recursivelyFreeze(enriched);
   const fastPolicyAuthority = captureFastPolicyAuthority(
@@ -1745,6 +1780,12 @@ async function fetchProviderModelsWithAuth(
           // away, and every client that keys an effort control off this field —
           // the Pi-shaped exports — renders no control at all.
           ...(liveResult.efforts[id]?.length ? { reasoningEfforts: liveResult.efforts[id] } : {}),
+          // The account catalog's per-base supportsImages vote collapses to one
+          // modalities value. It spreads before the hints so exact
+          // modelCapabilities declarations, the legacy modelInputModalities
+          // record and the vision-sidecar rewrite keep winning — the live
+          // value survives only when none of them applies.
+          ...(liveResult.inputModalities[id]?.length ? { inputModalities: liveResult.inputModalities[id] } : {}),
           ...catalogHintsFromProviderConfig(name, prov, id, contextCap, metadataModelIdCaseFold, captured.effectiveAlias),
         } as CatalogModel;
       });

package/src/codex/catalog-auto-refresh.ts

@@ -0,0 +1,182 @@
+/**
+ * Opt-in periodic catalog refresh so newly released models appear without a
+ * manual `ocx sync` (issue #3630).
+ *
+ * This is load-bearing, not a convenience. The served model set is otherwise
+ * only rewritten by an explicit sync, a management mutation, or startup
+ * convergence, so an overnight provider release stays invisible until someone
+ * happens to run one of those. The overnight case is the whole reason the
+ * scheduler exists.
+ *
+ * Shape follows src/quota/reset-poller.ts: a module-singleton unref'd interval
+ * whose config gate lives in the callee, so toggling `enabled` or changing the
+ * cadence takes effect on the next tick without a restart (the rationale
+ * spelled out at src/oauth/token-guardian.ts:276). Importing this module at
+ * startup must cost nothing — src/server/background-lifecycle.ts loads it
+ * statically — so the config barrel, the admission snapshot, and the
+ * convergence funnel are all dynamic import()s inside the tick.
+ */
+
+/**
+ * Keep these numeric literals aligned with CATALOG_AUTO_REFRESH_* in src/config.ts.
+ * They cannot be imported from there: this module is a static edge from
+ * background-lifecycle, and the config barrel is a heavy import reserved for the tick.
+ */
+const DEFAULT_INTERVAL_MS = 60 * 60_000;
+const MIN_INTERVAL_MS = 15 * 60_000;
+/**
+ * Commit-lock wait only. Gather already has per-provider timeouts, and automatic
+ * callers fail fast and defer (ConvergeRequest.mode) rather than holding the
+ * write lock across a slow tick.
+ */
+const TICK_DEADLINE_MS = 1_000;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let detachShutdownHook: (() => void) | null = null;
+/** The bounded cadence the live timer was created with, so a tick can notice config drift. */
+let liveIntervalMs: number | null = null;
+/**
+ * Bumped by every start and stop. A tick captures it on entry and re-checks before publishing,
+ * so a converge still in flight when the timer stops cannot publish into the next generation.
+ */
+let generation = 0;
+/** setInterval does not skip a firing while the previous callback is still awaiting. */
+let inFlight = false;
+
+/** Number of ticks that have run. Test-only observability; carries no catalog data. */
+let tickCount = 0;
+
+function boundedInterval(value: number): number {
+  return Math.max(MIN_INTERVAL_MS, Math.floor(value));
+}
+
+/** Re-arm the timer when the operator changed the cadence since it was created. */
+function restartIfCadenceChanged(configured: number): void {
+  if (timer === null || boundedInterval(configured) === liveIntervalMs) return;
+  stopCatalogAutoRefresh();
+  startCatalogAutoRefresh(configured);
+}
+
+async function tick(): Promise<void> {
+  // An interval firing while the previous converge is still awaiting would stack
+  // provider fetches precisely when a slow /models call is already in flight.
+  if (inFlight) return;
+  inFlight = true;
+  const entryGeneration = generation;
+  try {
+    const {
+      loadConfig,
+      isCatalogAutoRefreshEnabled,
+      resolveCatalogAutoRefreshIntervalMs,
+    } = await import("../config");
+    const config = loadConfig();
+    if (!isCatalogAutoRefreshEnabled(config)) return;
+    const configured = resolveCatalogAutoRefreshIntervalMs(config);
+    // 0 is dormant: the section stays configured but this tick must not converge,
+    // and the unref'd timer is left running so flipping the minutes back on is
+    // picked up without a process restart.
+    if (configured === 0) return;
+    // A stop or restart landed while the config resolved: this tick no longer owns the timer,
+    // so it must neither count as a refresh nor adopt a cadence for a generation that is gone.
+    if (entryGeneration !== generation) return;
+    // Adopt a changed cadence without a restart, which is why the config gate lives in the
+    // callee at all. Only while this tick still owns the timer.
+    restartIfCadenceChanged(configured);
+    tickCount += 1;
+    const [{ createManagementConvergeCodex }, { createCatalogConvergeRequest }] = await Promise.all([
+      import("./management-convergence"),
+      import("./catalog-admission"),
+    ]);
+    // A stop or restart landed while the funnel was loading: the result belongs to a
+    // generation that no longer owns the timer, so it must not publish.
+    if (entryGeneration !== generation) return;
+    const converge = createManagementConvergeCodex(config);
+    const outcome = await converge(createCatalogConvergeRequest({ deadlineMs: TICK_DEADLINE_MS }));
+    if (entryGeneration !== generation) return;
+    // createManagementConvergeCodex always projects catalog-only. Any other kind is a
+    // funnel contract break, not something this scheduler should re-classify.
+    if (outcome.kind !== "catalog-only") return;
+    const { recordCatalogAutoRefreshOutcome } = await import("./catalog-refresh-status");
+    recordCatalogAutoRefreshOutcome(outcome.catalogRefresh, outcome.changed);
+    if (outcome.changed) {
+      // Privacy scan: no provider names, model ids, paths, or account identifiers.
+      console.info("[catalog-auto-refresh] served model set changed");
+    }
+  } catch {
+    // A failed refresh is not an error worth surfacing: the next tick tries again.
+  } finally {
+    inFlight = false;
+  }
+}
+
+/** Idempotent. A second call while running is a no-op, matching startQuotaResetPoller. */
+export function startCatalogAutoRefresh(intervalMs = DEFAULT_INTERVAL_MS): void {
+  if (timer) return;
+  const bounded = boundedInterval(intervalMs);
+  generation += 1;
+  liveIntervalMs = bounded;
+  timer = setInterval(() => void tick(), bounded);
+  // Never keep the process alive for a catalog refresh.
+  timer.unref?.();
+  void import("../lib/optional-shutdown-hooks")
+    .then(hooks => {
+      detachShutdownHook = hooks.registerOptionalShutdownHook(
+        "catalog-auto-refresh",
+        stopCatalogAutoRefresh,
+      );
+    })
+    .catch(() => {
+      // Without the hook the unref'd timer still cannot delay exit.
+    });
+}
+
+export function stopCatalogAutoRefresh(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+  liveIntervalMs = null;
+  generation += 1;
+  detachShutdownHook?.();
+  detachShutdownHook = null;
+}
+
+export function isCatalogAutoRefreshRunning(): boolean {
+  return timer !== null;
+}
+
+/**
+ * Adopt the operator's configured cadence at startup.
+ *
+ * The caller starts the scheduler synchronously with the default interval, because
+ * resolving the config here would mean a static edge to ../config from a module
+ * background-lifecycle imports at load time. Resolving it through import() keeps
+ * that edge dynamic, at the cost of the timer running at the default for the few
+ * microtasks before this settles.
+ */
+export async function syncCatalogAutoRefreshCadence(): Promise<void> {
+  const { loadConfig, resolveCatalogAutoRefreshIntervalMs } = await import("../config");
+  const configured = resolveCatalogAutoRefreshIntervalMs(loadConfig());
+  // 0 is dormant: tick() already returns before converging, and the timer stays unref'd.
+  if (configured === 0) return;
+  restartIfCadenceChanged(configured);
+}
+
+/** Test-only: run one tick synchronously rather than waiting out the interval. */
+export async function runCatalogAutoRefreshTickForTests(): Promise<void> {
+  await tick();
+}
+
+export function catalogAutoRefreshTickCountForTests(): number {
+  return tickCount;
+}
+
+/** Test-only: the bounded cadence the live timer is running at, or null when stopped. */
+export function catalogAutoRefreshIntervalForTests(): number | null {
+  return liveIntervalMs;
+}
+
+export function resetCatalogAutoRefreshForTests(): void {
+  stopCatalogAutoRefresh();
+  tickCount = 0;
+}

package/src/codex/catalog-refresh-status.ts

@@ -103,3 +103,96 @@ function normalizeCatalogFailureCause(value: unknown): CatalogFailureCause | und
 export function catalogRefreshIsPending(disposition: CatalogDisposition): boolean {
   return disposition.status !== "committed";
 }
+
+export interface CatalogAutoRefreshOutcome {
+  readonly at: number;
+  readonly disposition: CatalogDisposition;
+  readonly changed: boolean;
+  /**
+   * A refresh that has failed repeatedly is the signal an operator needs, and the
+   * boolean disposition alone cannot express it: skipped and failed look the same
+   * as a one-off busy skip until this count climbs.
+   */
+  readonly consecutiveFailures: number;
+}
+
+let lastAutoRefreshOutcome: CatalogAutoRefreshOutcome | null = null;
+
+/** Rebuild and freeze so a management reader cannot mutate scheduler state. */
+function freezeCatalogDisposition(disposition: CatalogDisposition): CatalogDisposition {
+  if (disposition.status === "committed") {
+    return Object.freeze({
+      status: "committed" as const,
+      changed: disposition.changed,
+      degraded: disposition.degraded,
+      notices: Object.freeze([...disposition.notices]),
+    });
+  }
+  if (disposition.status === "skipped") {
+    return Object.freeze({
+      status: "skipped" as const,
+      reason: disposition.reason,
+      retryable: disposition.retryable,
+    });
+  }
+  const cause = disposition.cause
+    ? Object.freeze({
+        kind: disposition.cause.kind,
+        ...(disposition.cause.code ? { code: disposition.cause.code } : {}),
+      })
+    : undefined;
+  return Object.freeze({
+    status: "failed" as const,
+    reason: disposition.reason,
+    phase: disposition.phase,
+    retryable: disposition.retryable,
+    partialWrite: disposition.partialWrite,
+    ...(cause ? { cause } : {}),
+  });
+}
+
+function freezeCatalogAutoRefreshOutcome(
+  outcome: CatalogAutoRefreshOutcome,
+): CatalogAutoRefreshOutcome {
+  return Object.freeze({
+    at: outcome.at,
+    disposition: freezeCatalogDisposition(outcome.disposition),
+    changed: outcome.changed,
+    consecutiveFailures: outcome.consecutiveFailures,
+  });
+}
+
+/**
+ * Record one auto-refresh tick. The disposition is rebuilt through
+ * normalizeCatalogDisposition before anything is stored: an unnormalizable
+ * value is exactly the case this privacy boundary exists for, so it is dropped
+ * rather than copied through into a management response.
+ */
+export function recordCatalogAutoRefreshOutcome(
+  disposition: CatalogDisposition,
+  changed: boolean,
+): CatalogAutoRefreshOutcome | null {
+  const normalized = normalizeCatalogDisposition(disposition);
+  if (normalized === null) return null;
+  const consecutiveFailures = catalogRefreshIsPending(normalized)
+    ? (lastAutoRefreshOutcome?.consecutiveFailures ?? 0) + 1
+    : 0;
+  const outcome = freezeCatalogAutoRefreshOutcome({
+    at: Date.now(),
+    disposition: normalized,
+    changed: changed === true,
+    consecutiveFailures,
+  });
+  lastAutoRefreshOutcome = outcome;
+  return freezeCatalogAutoRefreshOutcome(outcome);
+}
+
+export function lastCatalogAutoRefreshOutcome(): CatalogAutoRefreshOutcome | null {
+  return lastAutoRefreshOutcome === null
+    ? null
+    : freezeCatalogAutoRefreshOutcome(lastAutoRefreshOutcome);
+}
+
+export function resetCatalogAutoRefreshStatusForTests(): void {
+  lastAutoRefreshOutcome = null;
+}

package/src/codex/history-provider.ts

@@ -171,6 +171,41 @@ function readFirstRolloutLine(fd: number): string | null {
   return nlIndex === -1 ? null : collected.subarray(0, nlIndex).toString("utf8");
 }
 
+/**
+ * Bounded tail of complete JSONL lines, newest-last.
+ *
+ * Used to refuse a rollout that *became* paginated after a legacy first line
+ * (#4311). Line 1 can still look writable after a newer Codex migrates the
+ * thread in place, and the native projector then dies on the first
+ * out-of-sequence ordinal a legacy append introduces. Every record written
+ * after such a migration carries an ordinal, so the newest records are where
+ * the evidence is.
+ *
+ * One read of a fixed window from EOF, split once. An earlier draft grew the
+ * window chunk by chunk and re-decoded the accumulated buffer on every
+ * iteration, which is quadratic: a rollout whose only `session_meta` sits at
+ * the top would have decoded and split up to the whole window ~256 times. The
+ * window is a cap, not a target — it is not walked and it is not the file.
+ *
+ * Returns `null` only when the file cannot be measured, which the caller
+ * treats as an unreadable record rather than a writable rollout.
+ */
+const ROLLOUT_TAIL_WINDOW_BYTES = 1 << 20;
+
+function readRolloutTailCompleteLines(fd: number): string[] | null {
+  const size = Number(fstatSync(fd).size);
+  if (!Number.isFinite(size) || size < 0) return null;
+  if (size === 0) return [];
+  const start = Math.max(0, size - ROLLOUT_TAIL_WINDOW_BYTES);
+  const window = Buffer.alloc(size - start);
+  const read = readSync(fd, window, 0, window.length, start);
+  if (read === 0) return [];
+  const lines = window.subarray(0, read).toString("utf8").split("\n");
+  // Unless the window reached BOF, the first element starts mid-record (and
+  // possibly mid-codepoint), so it is not a complete line.
+  return (start === 0 ? lines : lines.slice(1)).filter(line => line.length > 0);
+}
+
 function planFirstLineProvider(firstLine: string, expectedId: string, provider: string): FirstLineProviderPlan {
   const meta = parseSessionMetaLine(firstLine);
   if (!meta || meta.record.payload.id !== expectedId) return { state: "unsafe" };
@@ -315,6 +350,26 @@ function assertLegacyHistoryWritable(path: string, heldFd?: number): void {
     const first = readFirstRolloutLine(fd);
     if (!first) throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
     assertLegacyHistoryRecord(first);
+    // Line 1 is not enough: a newer Codex can migrate a live rollout in place,
+    // leaving the original session_meta and writing ordinals / history_mode only
+    // onto later records (#4311). The native projector then stops at the first
+    // cloned ordinal-0 append. Inspect a bounded window of the newest records
+    // and refuse before any mutation of the rollout, the row, or the manifest.
+    const tail = readRolloutTailCompleteLines(fd);
+    if (tail === null) throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
+    if (tail.length === 0) return;
+    const last = tail[tail.length - 1];
+    if (!last) throw new CodexHistoryIntegrityError("history_rollout_record_invalid");
+    if (last !== first) assertLegacyHistoryRecord(last);
+    // Cheap filter: only re-parse tail lines that look paginated. Needed because
+    // a compensating append can make the last line look legacy again while an
+    // earlier-in-tail native conversion still carries ordinals (#4311).
+    for (const line of tail) {
+      if (line === first || line === last) continue;
+      if (line.includes("\"ordinal\"") || line.includes("\"history_mode\"")) {
+        assertLegacyHistoryRecord(line);
+      }
+    }
   } finally {
     if (heldFd === undefined) closeSync(fd);
   }

package/src/codex/model-entitlements.ts

@@ -317,6 +317,37 @@ const MODEL_ROSTER_VERSIONS_PER_ACCOUNT_MAX = 4;
  * roster.
  */
 const MODEL_ROSTER_FLIGHTS_PER_ACCOUNT_MAX = 4;
+
+/**
+ * Distinct caller-selected roster versions admitted per account in one roster window.
+ *
+ * The cache budget and the flight budget both bound STATE, not WORK. A caller that cycles
+ * `client_version` and waits for each answer misses the cache by design and misses the flight
+ * key by design, so it can renew an authenticated upstream request under EVERY stored account
+ * token as often as it likes, and the gated-model checks it displaces fail closed while it does.
+ *
+ * DISTINCT VERSIONS are counted, never attempts. One legitimate client retrying a single version
+ * through an upstream outage comes back every 15s on the failure TTL; charging each attempt would
+ * spend the whole allowance on that one version and then refuse it for the rest of the 5-minute
+ * window, turning a recovered upstream into several more minutes without gated models.
+ */
+const MODEL_ROSTER_VERSION_MISSES_PER_ACCOUNT_MAX = 4;
+
+interface AccountVersionMissBudget {
+  credentialIdentity: string;
+  /** Version -> when this version stops occupying the allowance. */
+  versions: Map<string, number>;
+}
+
+/**
+ * One row per ACCOUNT, not per credential identity.
+ *
+ * A Pool access-token refresh increments the generation, so an identity-keyed map would gain a
+ * permanent row per generation for the lifetime of the process: a protection against renewable
+ * work would have introduced an unbounded cache. A generation change replaces the row instead,
+ * which is also the right budget semantics — new credential, new allowance.
+ */
+const accountModelsMisses = new Map<string, AccountVersionMissBudget>();
 const DIRECT_CALLER_ACCOUNT_PREFIX = "__direct_codex__:";
 
 export interface CodexModelEntitlementCredentialSnapshot {
@@ -670,6 +701,7 @@ async function modelsForCredential(
   fetcher: typeof fetch,
   now: number,
   clientVersion: string,
+  trustedClientVersion: string,
   credentialMutationEpoch?: number,
 ): Promise<CachedAccountModels> {
   const cached = accountModelsCache.get(cacheKeyFor(credential.accountId, clientVersion));
@@ -698,6 +730,21 @@ async function modelsForCredential(
       confirmed: false,
     };
   }
+  // Cache hits, joined flights and capacity refusals start no upstream request. Charge only
+  // after capacity admission; the locally selected runtime version remains exempt.
+  if (
+    !credential.accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)
+    && clientVersion !== trustedClientVersion
+    && !admitVersionMiss(credential, clientVersion, now)
+  ) {
+    return {
+      credentialIdentity: credential.credentialIdentity,
+      clientVersion,
+      expiresAt: now,
+      models: new Set(),
+      confirmed: false,
+    };
+  }
   const flight = fetchAccountModels(credential, fetcher, now, clientVersion)
     .then(result => {
       if (
@@ -716,6 +763,30 @@ async function modelsForCredential(
   return flight;
 }
 
+/** Whether this caller-selected version may open a new upstream request for the account. */
+function admitVersionMiss(
+  credential: CodexModelEntitlementCredentialSnapshot,
+  clientVersion: string,
+  now: number,
+): boolean {
+  const stored = accountModelsMisses.get(credential.accountId);
+  const budget = stored && stored.credentialIdentity === credential.credentialIdentity
+    ? stored
+    : { credentialIdentity: credential.credentialIdentity, versions: new Map<string, number>() };
+  for (const [version, expiresAt] of budget.versions) {
+    if (expiresAt <= now) budget.versions.delete(version);
+  }
+  const alreadyCharged = budget.versions.has(clientVersion);
+  const admitted = alreadyCharged
+    || budget.versions.size < MODEL_ROSTER_VERSION_MISSES_PER_ACCOUNT_MAX;
+  // A repeat keeps its ORIGINAL expiry. Refreshing it here would let a caller hold one version
+  // open indefinitely, and it is the retry case this distinction exists to protect.
+  if (admitted && !alreadyCharged) budget.versions.set(clientVersion, now + MODEL_ROSTER_TTL_MS);
+  if (budget.versions.size === 0) accountModelsMisses.delete(credential.accountId);
+  else accountModelsMisses.set(credential.accountId, budget);
+  return admitted;
+}
+
 function candidateAccountIds(config: Pick<OcxConfig, "codexAccounts">): string[] {
   return [
     MAIN_CODEX_ACCOUNT_ID,
@@ -992,6 +1063,10 @@ export async function resolveCodexModelEntitlements(
       fetcher,
       now,
       clientVersion,
+      resolveCodexEntitlementClientVersion(
+        null,
+        options.loadPersistedRuntime ?? loadPersistedCodexRuntime,
+      ),
       options.credentialMutationEpoch,
     ),
   })));
@@ -1050,6 +1125,7 @@ export async function isDirectCallerEntitledToCodexModel(
     options.fetcher ?? fetch,
     options.now ?? Date.now(),
     clientVersion,
+    clientVersion,
   );
   return codexModelEntitlementStateForRoster(
     result.models,
@@ -1128,11 +1204,13 @@ export function invalidateCodexModelEntitlementsForAccount(accountId: string | n
   for (const key of [...accountModelsCache.keys()]) {
     if (accountIdOfCacheKey(key) === accountId) accountModelsCache.delete(key);
   }
+  accountModelsMisses.delete(accountId);
 }
 
 export function resetCodexModelEntitlementCacheForTests(): void {
   accountModelsCache.clear();
   accountModelsFlights.clear();
+  accountModelsMisses.clear();
   negativeCredentialMemo.clear();
   entitlementEnsureFlights.clear();
   runtimeVersionMemo = null;