@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/codex/auth-api/account-selection.ts

@@ -0,0 +1,107 @@
+import type { OcxConfig } from "../../types";
+import { getConfigPath, initializePersistedConfigIfMissing, mutatePersistedConfig } from "../../config";
+import { mergeConfigDefaults, readConfigFileSnapshot, validateConfigCandidate } from "../../config/diagnostics";
+import { adoptPersistedCodexAccountSelection, claudeCodeBaselineArmed } from "../../config/live-reconcile";
+import { deleteConfigTopLevelKey, fileBackedConfigPath, recordFileBackedConfig } from "../../config/rebase-provenance";
+import { MAIN_CODEX_ACCOUNT_ID, hasLegacyMainCodexPoolAccount, isSelectableCodexPoolAccount, isValidCodexAccountId } from "../account-id";
+import { isCodexAccountPaused } from "../account-pause";
+import { readCodexAccountRecord } from "../account-store";
+import { codexAccountPinDrainReason, resetCodexRoutingForManualSelection } from "../routing";
+import { jsonResponse } from "./http";
+
+class SelectionRejected extends Error {
+  constructor(message: string, readonly status: number) { super(message); }
+}
+
+function validateSelection(config: OcxConfig, accountId: string | null): void {
+  if (accountId === null) return;
+  if (accountId === MAIN_CODEX_ACCOUNT_ID && hasLegacyMainCodexPoolAccount(config.codexAccounts)) {
+    throw new SelectionRejected("Remove the legacy __main__ pool row before selecting the Desktop account", 409);
+  }
+  if (isCodexAccountPaused(config, accountId)) throw new SelectionRejected("Account is paused", 409);
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return;
+  if (!isValidCodexAccountId(accountId)) throw new SelectionRejected("Invalid account id format", 400);
+  if (!(config.codexAccounts ?? []).some(account => isSelectableCodexPoolAccount(account) && account.id === accountId)) {
+    throw new SelectionRejected("Account not found", 400);
+  }
+  if (readCodexAccountRecord(accountId)?.codexValidationPending) {
+    throw new SelectionRejected("Account validation is pending. Refresh quota after recovery to validate it.", 409);
+  }
+}
+
+function applySelection(config: OcxConfig, accountId: string | null): boolean {
+  const changed = config.activeCodexAccountId !== (accountId ?? undefined)
+    || config.activeCodexAccountPinned !== (accountId ?? undefined);
+  if (accountId === null) {
+    deleteConfigTopLevelKey(config, "activeCodexAccountId");
+    deleteConfigTopLevelKey(config, "activeCodexAccountPinned");
+  } else {
+    config.activeCodexAccountId = accountId;
+    config.activeCodexAccountPinned = accountId;
+  }
+  return changed;
+}
+
+/** A manual selection is an explicit command, even when equal to the live merge baseline. */
+export function persistCodexAccountSelection(config: OcxConfig, accountId: string | null): Response {
+  const unknown = () => jsonResponse({
+    error: "Account selection could not be confirmed; reload settings before retrying",
+    code: "account_selection_unavailable",
+  }, 409);
+  const configPath = getConfigPath();
+  const sourcePath = fileBackedConfigPath(config);
+  if (sourcePath !== undefined && sourcePath !== configPath) return unknown();
+  let committed: OcxConfig;
+  let warning = false;
+  try {
+    // Do not activate a newly disk-only account that the running proxy has not adopted.
+    validateSelection(config, accountId);
+    const before = readConfigFileSnapshot();
+    if (before.diagnostics.source === "default" && !fileBackedConfigPath(config) && !claudeCodeBaselineArmed(config)) {
+      // Preserve transient/initial callers without recreating a deleted live configuration.
+      // The create-only owner cannot replace a competing writer's newly published config.
+      const normalized = validateConfigCandidate(mergeConfigDefaults(config));
+      if (!normalized.ok) return unknown();
+      const initial = normalized.config;
+      applySelection(initial, accountId);
+      initializePersistedConfigIfMissing(initial);
+    }
+    const result = mutatePersistedConfig(persisted => {
+      // This callback is re-run under the mutation lock immediately before publication.
+      // A removed or paused account must not be resurrected by a stale UI snapshot.
+      validateSelection(config, accountId);
+      validateSelection(persisted, accountId);
+      return { changed: applySelection(persisted, accountId), value: persisted };
+    });
+    if (result.status === "unavailable") return unknown();
+    committed = result.value;
+  } catch (error) {
+    if (error instanceof SelectionRejected) return jsonResponse({ error: error.message }, error.status);
+    // Atomic publication may succeed before generation/bookkeeping fails. Confirm the exact
+    // durable selection instead of rolling live state back behind an already published write.
+    const snapshot = readConfigFileSnapshot();
+    if (snapshot.raw === undefined) return unknown();
+    try {
+      const strict = validateConfigCandidate(JSON.parse(snapshot.raw.replace(/^\uFEFF/, "")));
+      if (!strict.ok) return unknown();
+      validateSelection(config, accountId);
+      validateSelection(strict.config, accountId);
+      if (strict.config.activeCodexAccountId !== (accountId ?? undefined)
+        || strict.config.activeCodexAccountPinned !== (accountId ?? undefined)) return unknown();
+      committed = strict.config;
+      warning = true;
+    } catch { return unknown(); }
+  }
+  adoptPersistedCodexAccountSelection(config, committed);
+  recordFileBackedConfig(config, configPath);
+  // No failed save may clear affinity, spend the manual preference, or move the RR cursor.
+  resetCodexRoutingForManualSelection(accountId ?? MAIN_CODEX_ACCOUNT_ID);
+  const pinDrainReason = accountId === null ? undefined : codexAccountPinDrainReason(config, accountId);
+  return jsonResponse({
+    ok: true,
+    activeCodexAccountId: config.activeCodexAccountId ?? null,
+    appliesImmediately: true,
+    ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
+    ...(warning ? { warning: "config_bookkeeping_failed" } : {}),
+  });
+}

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

@@ -88,14 +88,13 @@ export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise
     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.
+    // Positive evidence renews before expiry; unavailable evidence keeps discovery
+    // eligible under the same pacing. Admission still requires fresh spendable funds.
     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);
+      && (!hasSpendableCodexCredits(quota, now)
+        || (observedAt !== undefined && now - observedAt >= MAIN_CREDIT_RENEWAL_AGE_MS));
   };
   const status = getMainAccountHardLockStatus(config);
   if (status.state !== "blocked" && !creditRecoveryNeeded()) { mainHardLockRecoveryAttempt = undefined; return; }

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";
@@ -247,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

@@ -1,5 +1,6 @@
 import { bindPoolCreditPolicy, poolCreditHoldResetAt, poolContextCreditHoldResetAt } from "./pool-credit-policy";
 import { hasSpendableCodexCredits } from "./quota-types";
+import { nextQuotaQueryDelay } from "./quota-query-backoff";
 import { noteMainAccountActivity } from "./main-account-external-usage";
 import { codexAccountPriorityFailbackEnabled } from "./account-priority";
 import type { PoolQuotaWriter } from "./quota-types";
@@ -81,11 +82,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 +278,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;
@@ -547,8 +554,11 @@ function assertPoolAccountCredits(accountId: string, resetAt: number | undefined
 export class CodexMainAccountCreditsOffError extends CodexAccountCooldownError {
   readonly resetAt?: number;
 
-  constructor(resetAt?: number) {
-    super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
+  constructor(resetAt?: number, creditRecovery = false) {
+    // Keep the included reset as policy evidence, but let consented callers retry
+    // within the base metadata recovery interval even when backoff grows longer.
+    super(MAIN_CODEX_ACCOUNT_ID, creditRecovery
+      ? Math.min(resetAt ?? Infinity, Date.now() + nextQuotaQueryDelay()) : resetAt ?? 0);
     this.name = "CodexMainAccountCreditsOffError";
     this.resetAt = resetAt;
     this.message = "Codex main account reached its usage limit, and spending ChatGPT credits is off or no fresh spendable balance is available."
@@ -772,7 +782,8 @@ function assertMainAccountPolicy(
     const status = getMainAccountHardLockStatus(config);
     if (status.state === "blocked") throw new CodexMainAccountHardLockError(status.resetAt, status.thresholds);
     const creditsResetAt = mainCreditsHoldResetAt(config);
-    if (creditsResetAt !== undefined) throw new CodexMainAccountCreditsOffError(creditsResetAt);
+    if (creditsResetAt !== undefined) throw new CodexMainAccountCreditsOffError(creditsResetAt,
+      codexAccountUsesCreditsAfterLimit(config, MAIN_CODEX_ACCOUNT_ID));
   }
   // Only an admitted request is opencodex's own use of the main account. Counting a refused one
   // would hide outside usage from the warning exactly while the lock is holding.
@@ -1635,6 +1646,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 +1673,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 +1715,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 +1771,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 +1799,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/build-entries.ts

@@ -48,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;
@@ -470,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[];
@@ -510,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,
@@ -849,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;