@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/codex/auth-api/pool-mode-gate.ts

@@ -1,9 +1,11 @@
-import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
+import { codexAccountUsesCreditsAfterLimit, codexUsageLimitResetAt } from "../account-credit-use";
 import { nextCodexUsageQueryAt, nextQuotaQueryDelay, pruneRemovedCodexPoolUsageAccounts } from "../quota-query-backoff";
 import { CODEX_PRIORITY_FAILBACK_REFRESH_MS } from "../account-priority";
 import { codexQuotaHasFreshUsage } from "../quota-observation-freshness";
 import { getCodexAccountCredential, getValidCodexToken, readCodexAccountRecord } from "../account-store";
-import { getAccountQuota, isCompleteCodexQuotaRecoverySnapshot } from "../quota";
+import { getAccountQuota, getMainPolicyQuota, isCompleteCodexQuotaRecoverySnapshot } from "../quota";
+import { isCodexAccountPaused } from "../account-pause";
+import { hasSpendableCodexCredits } from "../quota-types";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { claimDueCodexQuotaRecoveryProbes, settleCodexQuotaRecoveryProbe } from "../routing";
 import { readCodexTokens } from "../auth-collision";
@@ -73,17 +75,33 @@ export async function runCodexCooldownRecoveryProbes(config: OcxConfig, now = Da
   return cooldownRecoveryInFlight;
 }
 
+const MAIN_CREDIT_RENEWAL_AGE_MS = 3 * 60_000;
+
 let mainHardLockRecoveryInFlight: Promise<void> | null = null;
 let mainHardLockRecoveryAttempt: { identity: number; credential: number; after: number; delay: number } | undefined;
 
 /** Metadata-only recovery on the existing sweep; failures retain the observed policy block. */
 export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise<void> {
   if (mainHardLockRecoveryInFlight) return mainHardLockRecoveryInFlight;
+  /** Schedule a real credit observation while leaving actual-time admission unchanged. */
+  const creditRecoveryNeeded = (): boolean => {
+    const now = Date.now();
+    const quota = getMainPolicyQuota();
+    const observedAt = quota?.credits?.observedAt;
+    // getMainPolicyQuota binds evidence to the observed physical identity. Only renew
+    // valid formerly spendable funds; admission retains the actual five-minute clock.
+    return codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID)
+      && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
+      && codexUsageLimitResetAt(quota, undefined, now) !== undefined
+      && observedAt !== undefined && observedAt > 0
+      && now - observedAt >= MAIN_CREDIT_RENEWAL_AGE_MS
+      && hasSpendableCodexCredits(quota, observedAt);
+  };
   const status = getMainAccountHardLockStatus(config);
-  if (status.state !== "blocked") { mainHardLockRecoveryAttempt = undefined; return; }
+  if (status.state !== "blocked" && !creditRecoveryNeeded()) { mainHardLockRecoveryAttempt = undefined; return; }
   if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
   // A predicted reset is a scheduling hint, never proof that the hard lock can be lifted.
-  if (status.resetAt !== undefined && status.resetAt > Date.now()) return;
+  if (status.state === "blocked" && status.resetAt !== undefined && status.resetAt > Date.now()) return;
   // Reconcile the owned physical credential before skipping work for an older one.
   reconcileMainCodexAccountRuntimeState();
   const physical = readCodexTokens();
@@ -98,9 +116,10 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
   if (!lease) return;
   mainHardLockRecoveryInFlight = (async () => {
     reconcileMainCodexAccountRuntimeState();
-    if (getMainAccountHardLockStatus(config).state !== "blocked"
+    if ((getMainAccountHardLockStatus(config).state !== "blocked" && !creditRecoveryNeeded())
       || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
     const identityGeneration = captureMainAccountIdentityGeneration();
+    const passive = getMainAccountHardLockStatus(config).state !== "blocked";
     try {
       // Refresh can require an exclusive credential claim: never hold WHAM's shared
       // claim while obtaining a valid token. The runtime lease spans both operations.
@@ -111,7 +130,12 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
       // Native refresh retains its own grant-scoped refusal; global quarantine would outlive it.
       return;
     }
-    if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
+    const currentStatus = getMainAccountHardLockStatus(config);
+    if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)
+      || !isMainAccountIdentityGenerationLive(identityGeneration)
+      || (passive && !creditRecoveryNeeded())
+      || (currentStatus.state === "blocked" && currentStatus.resetAt !== undefined
+        && currentStatus.resetAt > Date.now())) return;
     const credential = getMainQuotaCredentialGeneration();
     // Reconcile the physical bearer before consulting the previous credential's delay.
     if (previous?.identity === identityGeneration && previous.credential === credential
@@ -123,7 +147,7 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
         after: currentQueryAfter };
       return;
     }
-    const result = await fetchMainAccountInfoAttempt(true, 1, lease, false, false, false, config);
+    const result = await fetchMainAccountInfoAttempt(true, 1, lease, false, false, false, config, { passive });
     // Never charge a replacement credential for a late result from its predecessor.
     if (isMainAccountIdentityGenerationLive(identityGeneration)
       && credential === getMainQuotaCredentialGeneration()) {
@@ -134,11 +158,11 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
         const authStatus = result.quotaRefresh.status === "http_error"
           ? result.quotaRefresh.httpStatus : undefined;
         const transientAuth = (authStatus === 401 || authStatus === 403)
-          && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+          && !result.terminalAuthFailure && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         if (transientAuth) mainHardLockRecoveryAttempt = undefined;
         else {
           const delay = nextQuotaQueryDelay(previousDelay || undefined);
-          mainHardLockRecoveryAttempt = getMainAccountHardLockStatus(config).state === "blocked"
+          mainHardLockRecoveryAttempt = getMainAccountHardLockStatus(config).state === "blocked" || creditRecoveryNeeded()
             ? { identity: identityGeneration, credential, delay, after: Math.max(Date.now() + delay, queryAfter) }
             : undefined;
         }

package/src/codex/auth-api/pool-quota-probe.ts

@@ -495,6 +495,7 @@ export async function fetchPoolAccountQuota(
   validatePending = false,
   afterDispatchSequence?: number,
   recoveryProbeNow?: number,
+  explicitRefresh = false,
 ): Promise<PoolQuotaResult> {
   const existing = getAccountQuota(accountId);
   if (afterDispatchSequence === undefined && !forceRefresh && existing && Date.now() - existing.updatedAt < POOL_CACHE_TTL) {
@@ -504,10 +505,23 @@ export async function fetchPoolAccountQuota(
       credentialGeneration: readCodexAccountRecord(accountId)?.generation,
     };
   }
+  const record = readCodexAccountRecord(accountId);
+  // The token endpoint already called this grant revoked or expired. Only a re-login or a
+  // completed validation rewrites the record and drops the marker, so until then a passive read
+  // (dashboard poll, listing, priming, recovery probe) would only POST the dead refresh token again
+  // and log the same 401. Report the stored verdict the failed refresh would have produced. An
+  // operator's explicit refresh command from any principal, a dashboard validation, and a post-reset
+  // readback keep their probe, and a source-linked credential spends no grant of its own, so none
+  // of them is held here.
+  if (!explicitRefresh && !validatePending && afterDispatchSequence === undefined && record && record.deletedAt == null
+    && record.credential && !record.credential.sourceAuthPath
+    && record.lastCodexValidationTerminal === true && record.lastCodexValidationStatus === "failed") {
+    markAccountNeedsReauth(accountId, captureConfigGeneration(), record.generation);
+    return { quota: existing ?? null, needsReauth: true, reauthReason: "refresh_failed", credentialGeneration: record.generation };
+  }
   // A token refresh may increment the generation (and rotate the refresh token) before WHAM
   // completes. Join a flight whose starting or resolved generation is still current, but let a
   // replacement credential with the same pool id start its own request.
-  const record = readCodexAccountRecord(accountId);
   const flights = poolQuotaRefreshInFlight.get(accountId);
   const current = flights && [...flights].find(flight => {
     const generation = flight.state.resolvedCredentialGeneration

package/src/codex/auth-api/routes.ts

@@ -1,3 +1,4 @@
+import { persistCodexAccountSelection } from "./account-selection";
 import { CODEX_ACCOUNT_LOG_LABEL_RE, codexAccountLogLabel } from "../account-label";
 import { poolQuotaHistoryIdentity, readCodexAccountRecord } from "../account-store";
 import { estimateCodexQuotaCapacity, insufficientCodexCapacity } from "../quota-capacity";
@@ -7,13 +8,13 @@ import { getAccountQuotaHistory, listAccountQuotas } from "../quota";
 import { deleteCodexAccount } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
 import { setAllCodexAccountsCreditsAfterLimit, setCodexAccountCreditsAfterLimit } from "../account-credit-use";
-import { clearCodexAccountPin, isCodexAccountPriorityKey, pinnedCodexAccountId, setCodexAccountPin, setCodexAccountPriority } from "../account-priority";
-import { codexAccountPinDrainReason, codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned, resetCodexRoutingForManualSelection } from "../routing";
+import { clearCodexAccountPin, isCodexAccountPriorityKey, pinnedCodexAccountId, setCodexAccountPriority } from "../account-priority";
+import { codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned } from "../routing";
 import { DEFAULT_ACCOUNT_PRIORITY, MAX_ACCOUNT_PRIORITY, MIN_ACCOUNT_PRIORITY, normalizeAccountPoolStickyLimit, normalizeCodexAccountPoolStrategy, parseAccountPoolStickyLimit, parseCodexAccountPoolStrategy, parseAccountPriority } from "../pool-rotation";
 import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 import type { OcxConfig } from "../../types";
-import { CODEX_ACCOUNT_ID_RE, hasLegacyMainCodexPoolAccount, isSelectableCodexPoolAccount, isValidCodexAccountId } from "../account-id";
+import { CODEX_ACCOUNT_ID_RE, isSelectableCodexPoolAccount, isValidCodexAccountId } from "../account-id";
 import { isCodexResetCreditOperationId } from "../reset-credit-recovery";
 import { listCodexAuthAccounts, selectFallbackAfterPause, pauseExhaustedCodexAccounts } from "./account-list";
 import { jsonResponse, manualImportDisabledResponse } from "./http";
@@ -43,6 +44,7 @@ export async function handleCodexAuthAPI(
     // required by AGENTS_INSTALL.md. Raw-admin/CLI refreshes remain observational.
     return jsonResponse({ accounts: await listCodexAuthAccounts(config, true, {
       validatePending: principal === "gui-session",
+      explicitRefresh: true,
     }) });
   }
 
@@ -246,53 +248,13 @@ export async function handleCodexAuthAPI(
   }
 
   if (url.pathname === "/api/codex-auth/active" && req.method === "PUT") {
-    let body: { accountId: string | null };
-    try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
-    const runtimeConfig = getRuntimeConfig(config);
-    const targetAccountId = body.accountId ?? MAIN_CODEX_ACCOUNT_ID;
-    if (body.accountId === MAIN_CODEX_ACCOUNT_ID && hasLegacyMainCodexPoolAccount(runtimeConfig.codexAccounts)) {
-      return jsonResponse({ error: "Remove the legacy __main__ pool row before selecting the Desktop account" }, 409);
-    }
-    if (body.accountId != null && isCodexAccountPaused(runtimeConfig, targetAccountId)) {
-      return jsonResponse({ error: "Account is paused" }, 409);
-    }
-    if (body.accountId != null && body.accountId !== MAIN_CODEX_ACCOUNT_ID) {
-      if (!isValidCodexAccountId(body.accountId)) return jsonResponse({ error: "Invalid account id format" }, 400);
-      const exists = (runtimeConfig.codexAccounts ?? [])
-        .some(account => isSelectableCodexPoolAccount(account) && account.id === body.accountId);
-      if (!exists) return jsonResponse({ error: "Account not found" }, 400);
-      if (readCodexAccountRecord(body.accountId)?.codexValidationPending) {
-        return jsonResponse({ error: "Account validation is pending. Refresh quota after recovery to validate it." }, 409);
-      }
+    let body: unknown;
+    try { body = await req.json(); } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)
+      || !("accountId" in body) || (body.accountId !== null && typeof body.accountId !== "string")) {
+      return jsonResponse({ error: "accountId must be an account id or null" }, 400);
     }
-    runtimeConfig.activeCodexAccountId = body.accountId ?? undefined;
-    // "Use this account now" outranks selection order until the account is spent:
-    // persisted here rather than in resetCodexRoutingForManualSelection, which is
-    // runtime state only. A null id clears the selection instead of making one, so it
-    // must release the pin rather than record one: pinning the `targetAccountId`
-    // fallback would leave a pin that no effective active account matches, which
-    // `isEffectiveCodexAccountPinned` reports as unpinned while the tier filter still
-    // honours it as a ceiling — invisibly capping the pool at the main account's tier.
-    if (body.accountId == null) clearCodexAccountPin(runtimeConfig);
-    else setCodexAccountPin(runtimeConfig, targetAccountId);
-    resetCodexRoutingForManualSelection(targetAccountId);
-    saveRuntimeConfig(config, runtimeConfig);
-    // A pin this route accepts can still be dropped by the very next resolve, and saying
-    // nothing about that is what made the setting look ignored (#4521). The checks above
-    // refuse an account that cannot be selected at all; this reports the one remaining
-    // outcome they do not cover, from the same predicate routing releases on, so the two
-    // cannot drift. Absent means the pin survives — additive for existing clients.
-    // `appliesImmediately` is unchanged: it answers whether thread affinity was cleared,
-    // not whether the pin is durable.
-    const pinDrainReason = body.accountId == null
-      ? undefined
-      : codexAccountPinDrainReason(runtimeConfig, targetAccountId);
-    return jsonResponse({
-      ok: true,
-      activeCodexAccountId: body.accountId,
-      appliesImmediately: true,
-      ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
-    });
+    return persistCodexAccountSelection(getRuntimeConfig(config), body.accountId);
   }
 
   if (url.pathname === "/api/codex-auth/active" && req.method === "GET") {

package/src/codex/auth-context.ts

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

package/src/codex/autostart-health.ts

@@ -60,6 +60,7 @@ export interface StartupHealth {
   platform: NodeJS.Platform;
   diagnosticStale: boolean;
   recommendedCommand: string | null;
+  recommendedAction?: string | null;
   commands: {
     installService: string;
     repairService: string;
@@ -91,7 +92,8 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
   // An arbitrary localhost gateway has an independent lifecycle that OCX cannot repair.
   const ownsLocalRouting = inputs.routingKind === "opencodex-local";
   const desktopEffective = (inputs.platform === "darwin" || inputs.platform === "linux") && !inputs.diagnosticStale
-    && inputs.desktop?.owned === true && inputs.desktop.loginEnabled
+    && inputs.desktop !== undefined && (inputs.desktop.owned || inputs.desktop.supervisor !== undefined)
+    && inputs.desktop.loginEnabled
     && inputs.desktop.running && inputs.desktop.viable;
   const protection: StartupProtection = ownsLocalRouting && inputs.serviceViable
     ? "service"
@@ -105,7 +107,7 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
     : rebootSafe
       ? "protected"
       : "at-risk";
-  const recommendedCommand = status !== "at-risk" || (ownsLocalRouting && inputs.desktop?.owned)
+  const recommendedCommand = status !== "at-risk" || (ownsLocalRouting && inputs.desktop !== undefined)
     ? null
     : inputs.routingKind === "custom-local" || inputs.routingKind === "unknown"
       ? COMMANDS.restoreNative
@@ -117,6 +119,11 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
       // gets the registering command.
       ? (inputs.serviceInstalled && !inputs.serviceConflict ? COMMANDS.repairService : COMMANDS.installService)
       : COMMANDS.restoreNative;
+  const recommendedAction = status === "at-risk" && ownsLocalRouting && inputs.desktop !== undefined
+    ? inputs.diagnosticStale || inputs.desktop.loginEnabled
+      ? "Reopen OpenCodex and check Start at Login."
+      : "Turn on Start at Login in the OpenCodex menu so the desktop app starts this proxy after a restart."
+    : null;
   return {
     ...inputs,
     diagnosticStale: inputs.diagnosticStale ?? false,
@@ -127,6 +134,7 @@ export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth
     protection,
     shimCoverage,
     recommendedCommand,
+    recommendedAction,
     commands: { ...COMMANDS },
   };
 }
@@ -211,7 +219,8 @@ function classifyStartupHealthSummary(health: StartupHealth): string {
   const command = health.recommendedCommand ?? health.commands.restoreNative;
   if (health.routingKind === "unknown") return `AT RISK after restart (Codex routing could not be verified; run '${command}')`;
   if (health.routingKind === "custom-local") return `AT RISK after restart (custom local gateway lifecycle is not managed by opencodex; run '${command}')`;
-  if (health.desktop?.owned) return "AT RISK after restart (desktop startup could not be verified; reopen OpenCodex and check Start at Login)";
+  if (health.desktop?.supervisor && !health.desktop.loginEnabled && !health.diagnosticStale) return "AT RISK after restart (OpenCodex Desktop runs this proxy, but its Start at Login could not be verified; turn it on in the OpenCodex menu)";
+  if (health.desktop) return "AT RISK after restart (desktop startup could not be verified; reopen OpenCodex and check Start at Login)";
   if (health.shimCoverage === "cli-only") return `AT RISK for Codex Desktop after restart (launcher shim covers CLI scripts only; run '${command}')`;
   if (health.serviceConflict) return `AT RISK after restart (background service managers conflict; run '${command}')`;
   if (health.serviceStale) return `AT RISK after restart (background service files are stale; run '${command}')`;

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

@@ -1,3 +1,4 @@
+import { isCodexControlPlaneModel } from "../control-plane-models";
 import { redactSecretString } from "../../lib/redact";
 import type { OcxConfig } from "../../types";
 import { encodeRoutedModelId } from "../../providers/slug-codec";
@@ -34,6 +35,7 @@ export type AutoReviewModelOverrideResult = "absent" | "applied" | "invalid" | "
 
 /** True when a catalog row was synthesized by opencodex instead of coming from upstream. */
 function isRoutedCatalogEntry(entry: RawEntry): boolean {
+  if (isCodexControlPlaneModel(entry.slug)) return false;
   const slug = typeof entry.slug === "string" ? entry.slug : "";
   return slug.includes("/")
     || (typeof entry.description === "string" && entry.description.startsWith("Routed via opencodex → "));
@@ -57,6 +59,7 @@ function clearAutoReviewOverrideValue(entry: RawEntry): void {
  * Returns the stamped values when the observed rows match that shape.
  */
 function legacyRootStampValues(observedModels: readonly RawEntry[]): ReadonlySet<string> | undefined {
+  observedModels = observedModels.filter(entry => !isCodexControlPlaneModel(entry?.slug));
   if (observedModels.some(entry => entry?.[AUTO_REVIEW_ROOT_MARKER] !== undefined)) return undefined;
   const configuredValues = new Set(observedModels.flatMap(entry => {
     const value = entry?.auto_review_model_override;
@@ -90,7 +93,7 @@ function clearLegacyRootStamps(models: readonly RawEntry[], sourceModels: readon
   const legacyStamp = legacyRootStampValues([...models, ...sourceModels]);
   if (legacyStamp === undefined) return;
   for (const entry of models) {
-    if (!entry || typeof entry !== "object") continue;
+    if (!entry || typeof entry !== "object" || isCodexControlPlaneModel(entry.slug)) continue;
     const current = entry.auto_review_model_override;
     if (entry[AUTO_REVIEW_ROOT_MARKER] === undefined
       && typeof current === "string" && legacyStamp.has(current)) clearAutoReviewOverrideValue(entry);
@@ -107,7 +110,7 @@ function clearAutoReviewModelOverride(
 ): void {
   const legacyStamp = legacyRootStampValues([...models, ...sourceModels]);
   for (const entry of models) {
-    if (!entry || typeof entry !== "object") continue;
+    if (!entry || typeof entry !== "object" || isCodexControlPlaneModel(entry.slug)) continue;
     const current = entry.auto_review_model_override;
     if (isRoutedCatalogEntry(entry)
       || (entry[AUTO_REVIEW_ROOT_MARKER] === true || rootAutoReviewStamp(entry) !== undefined)
@@ -188,6 +191,7 @@ function preserveNativeAutoReviewModelOverrides(
 
 /** Stamp a root-derived override and mark native rows so later root removal is durable. */
 function stampRootAutoReviewOverride(entry: RawEntry, target: string): void {
+  if (isCodexControlPlaneModel(entry.slug)) return;
   if (!isRoutedCatalogEntry(entry)) {
     const previous = rootAutoReviewStamp(entry);
     const current = entry.auto_review_model_override;
@@ -399,7 +403,7 @@ function applyRootSelectorToRemaining(
 ): AutoReviewModelOverrideResult {
   const clearRemaining = (): void => {
     for (const entry of models) {
-      if (!entry || providerStamped.has(entry)) continue;
+      if (!entry || providerStamped.has(entry) || isCodexControlPlaneModel(entry.slug)) continue;
       // Native rows written by releases before the root marker cannot be told apart from upstream
       // values once provider stamps diverge. clearLegacyRootStamps sweeps the ones the legacy
       // uniform signature still recognizes before provider plans land, because provider stamping
@@ -427,7 +431,7 @@ function applyRootSelectorToRemaining(
     return "unresolved";
   }
   for (const entry of models) {
-    if (!entry || providerStamped.has(entry)) continue;
+    if (!entry || providerStamped.has(entry) || isCodexControlPlaneModel(entry.slug)) continue;
     stampRootAutoReviewOverride(entry, trimmed);
   }
   return "applied";
@@ -449,7 +453,7 @@ export function applyConfiguredAutoReviewModelOverride(
   const { plans, failure } = buildProviderReviewPlans(models, config);
   const providerStamped = new Set<RawEntry>();
   for (const entry of models) {
-    if (!entry || typeof entry !== "object") continue;
+    if (!entry || typeof entry !== "object" || isCodexControlPlaneModel(entry.slug)) continue;
     const provider = catalogEntryProviderName(entry);
     if (!provider) continue;
     const plan = plans.get(provider);
@@ -482,7 +486,10 @@ export function finalizeAutoReviewModelOverride(
   sourceModels: readonly RawEntry[] = [],
   config?: Pick<OcxConfig, "providers">,
 ): AutoReviewModelOverrideResult {
-  if (models && sourceModels.length > 0) preserveNativeAutoReviewModelOverrides(models, sourceModels);
+  if (models && sourceModels.length > 0) preserveNativeAutoReviewModelOverrides(
+    models.filter(entry => !isCodexControlPlaneModel(entry.slug)),
+    sourceModels.filter(entry => !isCodexControlPlaneModel(entry.slug)),
+  );
   if (config && configHasProviderAutoReview(config)) {
     return applyConfiguredAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), config, sourceModels);
   }

package/src/codex/catalog/build-entries.ts

@@ -1,3 +1,5 @@
+import { isCodexControlPlaneModel } from "../control-plane-models";
+import { withCodexControlPlaneRows } from "./control-plane";
 import { CODEX_REASONING_LEVELS, type CodexReasoningLevel } from "../../reasoning-effort";
 import { clearModelCache } from "../model-cache";
 import { routedSlug, slugEquivalenceKey } from "../../providers/slug-codec";
@@ -46,6 +48,7 @@ import { NATIVE_RESERVE_MODEL } from "./native-models";
 import { isReserveCatalogProjection, type ReserveCatalogProjection } from "./reserve";
 import { deriveEntry, finishUpstreamNativeEntry, isExactComboCatalogEntry } from "./derive-entry";
 import { PICKER_ORDER_PRIORITY_BASE, SPAWN_PRIORITY_FIELD } from "./subagent-roster";
+import { preserveOperatorUltraFastTiers } from "./operator-tiers";
 
 export interface ObservedCatalogEntryBuildInput {
   readonly template: RawEntry | null;
@@ -194,7 +197,7 @@ export function buildCatalogEntriesFromObservedState({
   const comboPublicSlugs = new Set(goModels
     .filter(model => model.provider === COMBO_NAMESPACE)
     .map(catalogModelSlug));
-  for (const slug of gptSlugs) {
+  for (const slug of gptSlugs.filter(slug => !isCodexControlPlaneModel(slug))) {
     const native = deriveEntry(template, slug, "OpenAI native model (Codex OAuth passthrough).", 9, undefined, new Set(), openaiContextCap);
     if (rank.has(slug)) native.priority = rank.get(slug)!;
     nativeEntries.push(native);
@@ -224,7 +227,7 @@ export function buildCatalogEntriesFromObservedState({
     const selectorNativeSlugs = accountNativeSlugsBySelector?.get(selector)
       ?? accountNativeSlugs
       ?? gptSlugs;
-    const accountNativeEntries = selectorNativeSlugs.filter(slug => slug !== NATIVE_RESERVE_MODEL).map(slug => (
+    const accountNativeEntries = selectorNativeSlugs.filter(slug => slug !== NATIVE_RESERVE_MODEL && !isCodexControlPlaneModel(slug)).map(slug => (
       nativeEntriesBySlug.get(slug)
         ?? deriveEntry(template, slug, "OpenAI native model (Codex OAuth passthrough).", 9, undefined, new Set(), openaiContextCap)
     ));
@@ -306,7 +309,7 @@ export function buildCatalogEntriesFromObservedState({
       delete entry.prefer_websockets;
     }
   }
-  return applyMultiAgentMode(out, multiAgentMode, multiAgentV2Enabled, {
+  return applyMultiAgentMode(withCodexControlPlaneRows(out, template ? [template] : [], true, wsEnabled), multiAgentMode, multiAgentV2Enabled, {
     keepNativeChatGptOnV1,
     preserveDefaultMultiAgentVersion: isReserveCatalogProjection,
   });
@@ -409,12 +412,12 @@ export function mergeCatalogModelsWithNativeRecovery(
 ): RawEntry[] {
   const merged = [...primaryCatalogModels];
   const recoveredNativeSlugs = new Set(primaryCatalogModels.flatMap(entry => {
-    const slug = recoverableNativeSlug(entry);
+    const slug = isCodexControlPlaneModel(entry.slug) ? String(entry.slug) : recoverableNativeSlug(entry);
     return slug === null ? [] : [slug];
   }));
   for (const source of nativeRecoverySources) {
     for (const entry of source) {
-      const slug = recoverableNativeSlug(entry);
+      const slug = isCodexControlPlaneModel(entry.slug) ? String(entry.slug) : recoverableNativeSlug(entry);
       if (slug === null || recoveredNativeSlugs.has(slug)) continue;
       merged.push(structuredClone(entry) as RawEntry);
       recoveredNativeSlugs.add(slug);
@@ -460,6 +463,7 @@ export function applyFullModelPickerOrder(entries: RawEntry[], order: readonly s
   if (!pickerOrder.some(slug => !slug.includes("/"))) return;
   const rankOf = modelPickerRank(pickerOrder);
   for (const entry of entries) {
+    if (isCodexControlPlaneModel(entry.slug)) continue;
     const natural = entry[SPAWN_PRIORITY_FIELD] ?? entry.priority ?? 9;
     entry[SPAWN_PRIORITY_FIELD] = natural;
     entry.priority = rankOf(String(entry.slug)) ?? pickerOrder.length + Number(natural);
@@ -467,6 +471,8 @@ export function applyFullModelPickerOrder(entries: RawEntry[], order: readonly s
 }
 
 export interface ObservedCatalogMergeInput {
+  /** Preserve operator-supplied Ultra Fast only from the exact persisted routed row. */
+  readonly ultraFastTier?: boolean;
   readonly catalogModels: readonly RawEntry[];
   readonly baselineCatalogModels: readonly RawEntry[];
   readonly routedEntries: readonly RawEntry[];
@@ -507,6 +513,7 @@ export interface ObservedCatalogMergeInput {
  * accidentally fall back to process-ambient catalog discovery or merge-policy warnings.
  */
 export function mergeCatalogEntriesFromObservedState({
+  ultraFastTier = false,
   catalogModels,
   baselineCatalogModels,
   routedEntries,
@@ -539,10 +546,12 @@ export function mergeCatalogEntriesFromObservedState({
   // Raw catalog rows contain nested arrays/objects that normalization mutates. Detach every row at
   // the observed-core boundary so callers can safely retain evidence objects or repeat the merge.
   const detachedCatalogModels = catalogModels
+    .filter(entry => !isCodexControlPlaneModel(entry.slug))
     .map(entry => restoreNativeDisplayName(structuredClone(entry) as RawEntry));
   const detachedBaselineCatalogModels = baselineCatalogModels
+    .filter(entry => !isCodexControlPlaneModel(entry.slug))
     .map(entry => restoreNativeDisplayName(structuredClone(entry) as RawEntry));
-  const detachedRoutedEntries = routedEntries.map(entry => structuredClone(entry) as RawEntry);
+  const detachedRoutedEntries = routedEntries.filter(entry => !isCodexControlPlaneModel(entry.slug)).map(entry => structuredClone(entry) as RawEntry);
   // Track this invocation's generated custom rows, not ownership markers read from disk.
   // Their builder already finalized exact native ladders and ordinary routed mock tiers.
   const freshCustomEntries = new Set(detachedRoutedEntries.filter(entry =>
@@ -844,6 +853,20 @@ export function mergeCatalogEntriesFromObservedState({
     }
     return false;
   });
+  // First occurrence wins, matching enforceCatalogSlugUniqueness: a later duplicate row of the
+  // same slug is what the writer drops, so it must not decide which declaration survives.
+  const operatorRows = new Map<string, RawEntry | undefined>();
+  for (const entry of detachedCatalogModels) {
+    if (typeof entry.slug !== "string" || operatorRows.has(entry.slug)) continue;
+    operatorRows.set(entry.slug, trustedAccountBoundNativeCatalogSlug(entry) === undefined
+      && !isNativeAliasCatalogEntry(entry) && entry.owned_by !== COMBO_NAMESPACE ? entry : undefined);
+  }
+  for (const entry of finalRoutedEntries) {
+    if (typeof entry.slug !== "string" || !entry.slug.includes("/")
+      || isNativeAliasCatalogEntry(entry) || isExactComboCatalogEntry(entry, exactComboSlugs)
+      || trustedAccountBoundNativeCatalogSlug(entry) !== undefined) continue;
+    preserveOperatorUltraFastTiers(entry, operatorRows.get(entry.slug), ultraFastTier);
+  }
   const finalRoutedEntrySet = new Set(finalRoutedEntries);
   const degradedPreservedCount = preservedRoutedEntries.filter(entry => {
     if (!finalRoutedEntrySet.has(entry)) return false;
@@ -921,7 +944,10 @@ export function mergeCatalogEntriesFromObservedState({
   // clobber a hide flag back to list. Bare ids disable every account clone; qualified ids disable
   // only their generated account row.
   const versionedEntries = applyMultiAgentMode(
-    applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
+    withCodexControlPlaneRows(
+      applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
+      [...catalogModels, ...baselineCatalogModels, ...routedEntries], includeNativeOpenAi, wsEnabled,
+    ),
     multiAgentMode,
     multiAgentV2Enabled,
     { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection, nativeDefaults: nativeMultiAgentDefaults },