@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/server/fast-row.ts

@@ -0,0 +1,295 @@
+import {
+  accountBoundNativeOpenAiSlugsBySelector,
+  shouldIncludeAccountBoundNativeOpenAi,
+  shouldIncludeNativeOpenAi,
+  UPSTREAM_NATIVE_ENTRIES,
+} from "../codex/catalog/metadata";
+import { comboModelId, comboPublicModelId } from "../combos/types";
+import { policyModelId, policyPublicModelId } from "../routing/profile";
+import type { InboundWire } from "../providers/registry";
+import { fastPolicyForModel } from "../providers/service-tier";
+import type { OcxConfig } from "../types";
+import {
+  isKnownId,
+  knownEffortRowIds,
+  loadDetectedCursorEffortTable,
+  parseEffortRowId,
+  parseRequestEffortRowId,
+  type EffortRowKnownIds,
+  type ParsedEffortRowId,
+} from "./effort-row";
+
+/**
+ * Synthetic Fast selectors: `<base-id>--fast` published on external model listings for
+ * models whose resolved Fast policy is eligible, so a client that can only pick a model by
+ * id reaches the priority service tier. The Codex app has a picker toggle for this; nothing
+ * else did (devlog/_plan/260904_external_fast_wire).
+ *
+ * The marker is `--fast`, not `-fast`. Terminal `-fast` is a REAL id across this catalog —
+ * grok-4-fast, glm-5.3-fast, gpt-5-fast, and every Cursor fast variant — so a single hyphen
+ * cannot tell a product apart from a tier. `--` is the same terminal separator the effort-row
+ * grammar relies on for the same reason.
+ */
+const FAST_ROW_SUFFIX = "--fast";
+
+export interface ParsedFastRowId {
+  baseId: string;
+}
+
+export interface ParsedSyntheticRow {
+  fastRow: ParsedFastRowId | null;
+  effortRow: ParsedEffortRowId | null;
+}
+
+export function fastRowId(baseId: string): string {
+  return `${baseId}${FAST_ROW_SUFFIX}`;
+}
+
+/**
+ * Whether a provider/model pair's resolved Fast policy may be published as a row.
+ *
+ * `eligible` alone. `unclassified` means capability is undefined, and `decideTier` makes
+ * `fastMode` inert there, so publishing it would advertise a tier the runtime then refuses
+ * to send.
+ */
+export function fastRowEligible(
+  provider: Parameters<typeof fastPolicyForModel>[0],
+  modelId: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+): boolean {
+  return fastPolicyForModel(provider, modelId, providerName, inbound).eligibility === "eligible";
+}
+
+/** Shared discovery/export policy; native rows additionally need upstream tier evidence. */
+export function catalogFastRowEligible(
+  config: OcxConfig,
+  model: { provider: string; id: string; native?: boolean; supportsServiceTier?: boolean },
+): boolean {
+  if (config.fastRows === false) return false;
+  // Configured suffix-shaped IDs are real bases; live-only ones are deliberately
+  // refused by ingress. Discovery must not advertise a selector ingress cannot strip.
+  if (model.id.endsWith(FAST_ROW_SUFFIX)
+    && !fastRowBases(config)(model.native ? model.id : `${model.provider}/${model.id}`)) return false;
+  if (model.native) {
+    const id = model.id.slice(model.id.lastIndexOf("/") + 1);
+    const tiers = UPSTREAM_NATIVE_ENTRIES.get(id)?.additional_speed_tiers;
+    const provider = config.providers.openai;
+    return Array.isArray(tiers) && tiers.includes("fast") && provider !== undefined
+      && fastRowEligible(provider, id, "openai");
+  }
+  if (model.supportsServiceTier !== undefined) return model.supportsServiceTier === true;
+  const provider = config.providers[model.provider];
+  return provider !== undefined && fastRowEligible(provider, model.id, model.provider);
+}
+
+/**
+ * Bases that may carry a fast row.
+ *
+ * Deliberately a SUPERSET of what the listings publish, and deliberately not
+ * `knownEffortRowIds`. That set answers "which exact ids defeat the synthetic grammar"; it
+ * does not answer "which bases are routable". Bare natives prove the gap: the `openai`
+ * registry entry declares no `models` list and the default provider config declares none
+ * either, because they route through a family-pattern rule instead. `gpt-5.6-sol` is
+ * therefore absent from it, and requiring membership would publish `gpt-5.6-sol--fast` and
+ * then refuse to parse it.
+ *
+ * Being too permissive costs nothing here: routing still rejects a base it cannot serve, and
+ * the exact-id guard in `parseFastRowId` still protects real models. Being too strict breaks
+ * the feature.
+ *
+ * Membership must not depend on the live-model cache. An earlier version seeded this set
+ * from `knownEffortRowIds` alone, which reads `getStaleCached` (router.ts:125), so a
+ * live-only model leaving the cache silently stopped its `--fast` selector from parsing.
+ * The argument that its base row leaves the listing at the same time is true but
+ * irrelevant: `/v1/models` is discovery, not a routing allowlist, and `routeModel` still
+ * serves the bare base through the default provider (router.ts:791) and the qualified base
+ * through its configured provider (router.ts:680). So the base kept working while only the
+ * fast selector broke — the asymmetry this set exists to prevent.
+ *
+ * A pure Set cannot express this. Listings also publish LIVE-discovered and retained models
+ * that appear in no config (`provider-fetch.ts` publishes `goModels` and `retainModels`), and
+ * enumerating them means reading the very cache whose churn caused the original defect. So
+ * this returns a PREDICATE: an id is a routable base when it is a known static/config id, or
+ * when it is namespaced under an enabled configured provider. The second clause is
+ * structural, so it holds for a live-discovered model without consulting the cache, and it
+ * is exactly the shape `routeModel` uses to accept a qualified id (router.ts:680).
+ *
+ * A base is RECOGNIZED here and then judged by routing, which is the component that actually
+ * knows whether it can serve it.
+ */
+export function fastRowBases(config: OcxConfig): (id: string) => boolean {
+  const bases = new Set<string>();
+  // Configured providers: any model the router would accept for this provider, plus the
+  // namespaced and alias-namespaced spellings a listing can publish. Deliberately NOT
+  // knownEffortRowIds, whose live-cache half makes membership time-dependent.
+  for (const [providerName, providerConfig] of Object.entries(config.providers)) {
+    if (providerConfig.disabled === true) continue;
+    const namespaces = [providerName, providerConfig.alias].filter(
+      (value): value is string => typeof value === "string" && value.length > 0,
+    );
+    const declared = [
+      ...(providerConfig.models ?? []),
+      ...(providerConfig.defaultModel ? [providerConfig.defaultModel] : []),
+      ...Object.values(providerConfig.modelAliases ?? {}),
+      ...(config.customModels ?? [])
+        .filter(model => model.provider === providerName && model.modelId)
+        .map(model => model.modelId),
+    ];
+    for (const id of declared) {
+      bases.add(id);
+      for (const namespace of namespaces) bases.add(`${namespace}/${id}`);
+    }
+  }
+  // The STATIC upstream table, not `visibleNativeSlugs()`: that one filters by
+  // disabled/shadowed state and reaches the catalog cache on disk, so it would both read a
+  // file per parsed selector and SHRINK as runtime state changes. A base disappearing
+  // mid-session would strand a client still holding the id it was published.
+  if (shouldIncludeNativeOpenAi(config)) {
+    for (const slug of UPSTREAM_NATIVE_ENTRIES.keys()) bases.add(slug);
+  }
+  if (shouldIncludeAccountBoundNativeOpenAi(config)) {
+    // An EMPTY observed-entry list on purpose: the default argument reads the Codex models
+    // cache and catalog from disk. The empty form still seeds every selector with the native
+    // model set, and anything publishable is in UPSTREAM_NATIVE_ENTRIES anyway.
+    for (const [selector, slugs] of accountBoundNativeOpenAiSlugsBySelector(config, [])) {
+      for (const slug of slugs) bases.add(`${selector}/${slug}`);
+    }
+  }
+  // Namespaces whose qualified ids route, whatever the cache currently holds.
+  const namespaces = new Set<string>();
+  // Virtual rows. A combo or routing profile is published under its canonical
+  // `<namespace>/<id>` AND under an operator alias, which may be an arbitrary bare string
+  // with no namespace to vouch for it, so the structural clause below cannot reach it. A
+  // combo also cannot be covered by config.providers: declaring a provider named `combo`
+  // is rejected outright (combos/types.ts:191).
+  for (const [id, combo] of Object.entries(config.combos ?? {})) {
+    bases.add(comboModelId(id));
+    bases.add(comboPublicModelId(id, combo));
+  }
+  for (const [id, profile] of Object.entries(config.routingProfiles ?? {})) {
+    bases.add(policyModelId(id));
+    bases.add(policyPublicModelId(id, profile));
+  }
+  for (const [providerName, providerConfig] of Object.entries(config.providers)) {
+    if (providerConfig.disabled === true) continue;
+    namespaces.add(providerName.toLowerCase());
+    if (typeof providerConfig.alias === "string" && providerConfig.alias.length > 0) {
+      namespaces.add(providerConfig.alias.toLowerCase());
+    }
+  }
+  return (id: string): boolean => {
+    if (bases.has(id)) return true;
+    const slash = id.indexOf("/");
+    if (slash <= 0 || slash === id.length - 1) return false;
+    // A live-discovered or retained model is published as `<provider>/<model>` and appears in
+    // no config, so structural recognition is the only cache-free way to accept it.
+    //
+    // But NOT when the remainder itself ends in the marker. A real live model may legitimately
+    // be named `foo--fast`; its exact id is protected by the known-id guard only while the
+    // discovery cache still holds it, and after eviction that guard goes quiet while this
+    // clause would still accept `provider/foo` structurally - silently routing a DIFFERENT
+    // model than the client selected. Refusing the strip is the safe side: the caller then
+    // sends the id verbatim and routing resolves the real model, or fails honestly.
+    if (id.slice(slash + 1).endsWith(FAST_ROW_SUFFIX)) return false;
+    return namespaces.has(id.slice(0, slash).toLowerCase());
+  };
+}
+
+export function parseFastRowId(
+  id: string,
+  config: Pick<OcxConfig, "fastRows">,
+  knownIds?: EffortRowKnownIds,
+  routableBases?: EffortRowKnownIds,
+): ParsedFastRowId | null {
+  if (config.fastRows === false) return null;
+  if (!id.endsWith(FAST_ROW_SUFFIX)) return null;
+  // An exact configured/public id always beats the synthetic grammar, the same precedence
+  // effort rows use. An operator who really named a model `x--fast` keeps it.
+  if (isKnownId(knownIds, id)) return null;
+  const baseId = id.slice(0, -FAST_ROW_SUFFIX.length);
+  if (baseId.length === 0) return null;
+  return isKnownId(routableBases, baseId) ? { baseId } : null;
+}
+
+/**
+ * True when an effort-row base still carries a fast marker, i.e. the selector nested the two
+ * grammars. Composition is not supported, so such an id resolves to neither rather than
+ * silently to whichever parser ran first.
+ *
+ * Known-id guarded, so a real model named `foo--fast` keeps its legitimate `foo--fast--high`
+ * effort row.
+ */
+export function effortBaseCarriesFastMarker(
+  baseId: string,
+  knownIds: EffortRowKnownIds | undefined,
+): boolean {
+  return baseId.endsWith(FAST_ROW_SUFFIX) && !isKnownId(knownIds, baseId);
+}
+
+/**
+ * Resolve one ingress selector against both synthetic grammars, returning at most one.
+ * Callers pass the id the client sent and never a value another parser mutated.
+ */
+export function parseSyntheticRowId(
+  id: string,
+  config: OcxConfig,
+  // Claude surfaces decode the alias before the marker is unambiguous, so they pass the
+  // decoded form for Fast while effort parsing keeps seeing the id the client sent. A THUNK,
+  // not a string: arguments are evaluated before the call, so an eager decode would run its
+  // alias lookups even on the fastRows-off path this function exists to leave untouched.
+  fastSelector?: () => string,
+): ParsedSyntheticRow {
+  // Explicit opt-out preserves the effort-only parser and avoids Fast inventory work.
+  if (config.fastRows === false) {
+    return { fastRow: null, effortRow: parseRequestEffortRowId(id, config) };
+  }
+  const selector = fastSelector?.() ?? id;
+  const wantsFast = selector.endsWith(FAST_ROW_SUFFIX);
+  // Bail before building any inventory when neither grammar can match. A readable Claude
+  // alias is `claude-ocx-<provider>--<model>`, so it ALWAYS contains `--`: testing only for
+  // the separator would rebuild the whole model inventory on every Claude turn for a
+  // selector that cannot be a fast row. With effort parsing off, the terminal suffix is the
+  // only thing that can match.
+  const wantsEffort = config.cursorEffortRows === true && id.lastIndexOf("--") > 0;
+  if (!wantsFast && !wantsEffort) return { fastRow: null, effortRow: null };
+  const knownIds = knownEffortRowIds(config);
+  const fastRow = wantsFast
+    ? parseFastRowId(selector, config, knownIds, fastRowBases(config))
+    : null;
+  if (fastRow) return { fastRow, effortRow: null };
+  // Cursor install detection stays behind its own flag, exactly as parseRequestEffortRowId
+  // gates it today.
+  const effortRow = wantsEffort
+    ? parseEffortRowId(id, config, { knownIds, table: loadDetectedCursorEffortTable() })
+    : null;
+  return effortRow && effortBaseCarriesFastMarker(effortRow.baseId, knownIds)
+    ? { fastRow: null, effortRow: null }
+    : { fastRow: null, effortRow };
+}
+
+/** Fast-only resolution for surfaces that never parsed an effort row. */
+export function parseFastOnlyRowId(
+  config: OcxConfig,
+  selector: () => string,
+): ParsedFastRowId | null {
+  if (config.fastRows === false) return null;
+  return parseSyntheticRowId("", config, selector).fastRow;
+}
+
+/**
+ * Add a fast sibling beside an eligible row. The base row is always kept: a fast row is an
+ * addition, never a replacement. That is the deliberate difference from `fastMode`, which
+ * replaces the listed Cursor id — replacement suits a global switch, but a per-request
+ * selector has to leave the default reachable.
+ */
+export function expandFastRow<T extends { id: string }>(
+  row: T,
+  eligible: boolean,
+  config: Pick<OcxConfig, "fastRows">,
+  knownIds?: EffortRowKnownIds,
+): T[] {
+  if (config.fastRows === false || !eligible) return [row];
+  const id = fastRowId(row.id);
+  return isKnownId(knownIds, id) ? [row] : [row, { ...row, id }];
+}

package/src/server/gui-static.ts

@@ -90,6 +90,22 @@ function runtimeRoleMeta(runtimeRole: string): string {
   return `<meta name="opencodex-runtime-role" content="${escapeHtmlAttribute(runtimeRole)}">`;
 }
 
+/**
+ * Does this bind require a typed management credential?
+ *
+ * Emitted for the same reason as the role: so the dashboard can answer a question on first
+ * paint without asking a remote-hub endpoint. It is NOT the same question as the role.
+ * `standalone` + `hostname: "0.0.0.0"` is an operator who deliberately exposed the dashboard
+ * and must type the admin token, while a `hub` on loopback still mints its own session — so
+ * the role cannot stand in for this, and using it that way locked out exactly the operator
+ * who is supposed to see the prompt.
+ *
+ * Non-secret: it restates the bind the operator chose, which `/healthz` and the dashboard
+ * already reflect.
+ */
+function managementAuthRequiredMeta(required: boolean): string {
+  return `<meta name="opencodex-management-auth-required" content="${required ? "1" : "0"}">`;
+}
 function htmlDocumentResponse(html: string): Response {
   return new Response(html, {
     headers: {
@@ -101,9 +117,18 @@ function htmlDocumentResponse(html: string): Response {
   });
 }
 
-function htmlResponse(path: string, session?: GuiSessionBootstrap, runtimeRole?: string): Response {
+function htmlResponse(
+  path: string,
+  session?: GuiSessionBootstrap,
+  runtimeRole?: string,
+  managementAuthRequired?: boolean,
+): Response {
   let html = readFileSync(path, "utf8");
-  const bootstrap = `${runtimeRole ? runtimeRoleMeta(runtimeRole) : ""}${session ? sessionBootstrapMeta(session) : ""}`;
+  const bootstrap = [
+    runtimeRole ? runtimeRoleMeta(runtimeRole) : "",
+    managementAuthRequired === undefined ? "" : managementAuthRequiredMeta(managementAuthRequired),
+    session ? sessionBootstrapMeta(session) : "",
+  ].join("");
   if (bootstrap) {
     html = html.includes("</head>") ? html.replace("</head>", `${bootstrap}</head>`) : `${bootstrap}${html}`;
   }
@@ -126,6 +151,7 @@ export function serveGuiFile(
   guiDist = findGuiDist(),
   session?: GuiSessionBootstrap,
   runtimeRole?: string,
+  managementAuthRequired?: boolean,
 ): Response | null {
   if (!guiDist) return null;
   const filePath = resolveGuiFilePath(guiDist, pathname);
@@ -135,7 +161,7 @@ export function serveGuiFile(
     if (!extname(pathname)) {
       const indexPath = join(guiDist, "index.html");
       if (isFile(indexPath)) {
-        return htmlResponse(indexPath, session, runtimeRole);
+        return htmlResponse(indexPath, session, runtimeRole, managementAuthRequired);
       }
     }
     return null;
@@ -143,7 +169,7 @@ export function serveGuiFile(
 
   const ext = extname(filePath);
   const contentType = MIME_TYPES[ext] || "application/octet-stream";
-  if (ext === ".html") return htmlResponse(filePath, session, runtimeRole);
+  if (ext === ".html") return htmlResponse(filePath, session, runtimeRole, managementAuthRequired);
   // Snapshot bytes before returning the response. Bun.file is lazy: if gui/dist is replaced
   // after Bun frames the response but before the stream finishes, its Content-Length can
   // describe the old file while the body comes from the new one (#2792).

package/src/server/index.ts

@@ -12,7 +12,6 @@ import {
 } from "./ws-bridge";
 import type { Server, ServerWebSocket } from "bun";
 import {
-  DEFAULT_SUBAGENT_MODELS,
   applyProxyEnv,
   armClaudeCodeBaseline,
   loadConfig,
@@ -22,6 +21,8 @@ import {
 } from "../config";
 import { grokDefaultReasoningEffort } from "../grok/effort";
 import { flushConfigDirHardening } from "../config/paths";
+import { migrateStartupSubagentModels } from "./subagent-models-startup";
+import { migrateStartupXaiResponses } from "./xai-responses-startup";
 import { reconcileOAuthProviders } from "../oauth";
 import { withCatalogWriteSerialization } from "../codex/catalog-write-serialization";
 import { invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
@@ -33,8 +34,12 @@ import {
   type NativeCodexOwnership,
   type OwnershipInspection,
 } from "../integrations/native/ownership-preflight";
-import { createResetCreditWhamClient, registerCodexCooldownRecoveryProbeWorker } from "../codex/auth-api";
+import {
+  createResetCreditWhamClient,
+  registerCodexCooldownRecoveryProbeWorker,
+} from "../codex/auth-api";
 import { activateResetCreditAutoRedeem } from "../codex/reset-credit-auto-redeem";
+import { registerCodexQuotaAutoRefreshWorker } from "../codex/quota-auto-refresh";
 import {
   reconcileLiveStateStores,
   setLiveStateStoreConfig,
@@ -230,6 +235,7 @@ import { recordCursorSeen } from "../integrations/cursor-seen";
 import { detectCursorInstalls } from "../integrations/cursor-detect";
 import { loadCursorEffortTable } from "../integrations/cursor-effort-table";
 import { expandCursorEffortRow, knownEffortRowIds } from "./effort-row";
+import { catalogFastRowEligible, expandFastRow } from "./fast-row";
 
 export const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
 const WEBSOCKET_IDLE_TIMEOUT_SECONDS = 0;
@@ -509,7 +515,7 @@ function attachLiveSidebandUpstream(
 
 // Adapter resolution + wire-protocol override extracted to ./server/adapter-resolve.
 
-// Source invariant for tests/passthrough-abort.test.ts after the pure module split:
+// Source invariant for tests/responses/passthrough-abort.test.ts after the pure module split:
 // if (isEventStream && upstreamResponse.body) {
 // const repairConfig = route.provider.responsesItemIdRepair;
 // const needsClientRewrite = imageGenCallAliases.size > 0
@@ -583,6 +589,8 @@ export interface StartServerDeps {
   readinessGate?: ReadinessGate;
   /** Test-only package-tree observation; production captures package.json identity at boot. */
   packageTreeIntegrity?: PackageTreeIntegrityGuard;
+  /** Test-only seam for observing quota-worker registration ownership. */
+  registerCodexQuotaAutoRefreshWorker?: typeof registerCodexQuotaAutoRefreshWorker;
 }
 
 function inspectStartupOwnership(
@@ -645,7 +653,13 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   // Captured before loadConfig() starts the optional ACL flight so stop() drains the same dir
   // even if OPENCODEX_HOME changes underneath a long-lived process.
   const startupConfigDir = getConfigDir();
-  const config = runModelRenameStartupMigration(runAlibabaRegionStartupMigration(runOpenAiTierStartupMigration(loadConfig())));
+  const startupConfig = migrateStartupSubagentModels(
+    runModelRenameStartupMigration(runAlibabaRegionStartupMigration(runOpenAiTierStartupMigration(loadConfig()))),
+  );
+  // Reconcile disk-backed presets first: it replaces provider rows and must not undo
+  // an in-memory wire upgrade when that upgrade's persistence is temporarily unavailable.
+  reconcileOAuthProviders(startupConfig);
+  const config = migrateStartupXaiResponses(startupConfig);
   warnAgentTaskRecoveryStartup(config);
   setLiveStateStoreConfig(config);
   applyProxyEnv(config);
@@ -655,16 +669,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   let userCostOverlayReconciler: { stop(): void } | null = null;
   // Arm synchronously before listen. A pending journal therefore makes __main__ unusable
   // before any request can resolve its physical credential, while health/management/Pool stay live.
-  // Refresh OAuth provider presets (models/noReasoningModels) from the registry so a proxy update
-  // adding/dropping models reaches existing configs on start — not just fresh installs.
-  reconcileOAuthProviders(config);
   reconcileLiveStateStores();
-  // Seed default featured subagent models on first run only (UNSET → defaults). A user-set list,
-  // even [], is left alone so GUI removals persist.
-  if (config.subagentModels === undefined) {
-    config.subagentModels = [...DEFAULT_SUBAGENT_MODELS];
-    saveConfig(config);
-  }
   // authMode migration (devlog 260726_claude_auth_auto/015): before "auto" existed,
   // choosing Subscription DELETED the key, so a pre-upgrade block with no authMode is
   // indistinguishable from "never chose". Pin those to subscription once so an upgrade
@@ -798,6 +803,10 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
    * on the direct-spawn host into a 404 (#3192). The handler still runs its own admission, so a
    * loopback caller without a ChatGPT credential is refused inside it rather than by this gate.
    *
+   * The standalone Images client uses the same base URL for its two POST routes. Their handler
+   * keeps the paid upstream behind its own admission and forward-credential checks, so admit only
+   * the exact methods and paths it serves (#3428).
+   *
    * `GET /v1/models` is on the list for a reason that is easy to miss. When catalog
    * materialization fails or finds no source, `syncCodex` warns and injects with
    * `catalogPath: null`; Codex then builds an ONLINE model manager and `model/list` refreshes
@@ -811,6 +820,9 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     }
     if (path === "/v1/responses/compact") return req.method === "POST";
     if (path === "/v1/alpha/search") return req.method === "POST";
+    if (path === "/v1/images/generations" || path === "/v1/images/edits") {
+      return req.method === "POST";
+    }
     if (path === "/v1/models") return req.method === "GET";
     // Realtime voice — a directly-spawned `codex app-server` needs these for desktop voice
     // the same way it needs /v1/responses. Two shapes, same trust model as /v1/responses:
@@ -1017,8 +1029,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     return "public";
   }
   let backgroundLifecycle: ReturnType<typeof acquireServerBackgroundLifecycle> | null = null;
+  let unregisterQuotaAutoRefresh: (() => void) | null = null;
   try {
     backgroundLifecycle = acquireServerBackgroundLifecycle(applyPolicy);
+    unregisterQuotaAutoRefresh = (deps.registerCodexQuotaAutoRefreshWorker
+      ?? registerCodexQuotaAutoRefreshWorker)(config);
     // External `ocx config set` / direct config.json edits run in other
     // processes; poll the file so Logs/Usage display prices follow them live.
     // Started inside the guarded startup transaction so the catch below can
@@ -1270,7 +1285,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           // Built directly rather than through formatErrorResponse: that helper derives
           // `code` from the status and message via classifyError, and these two need stable,
           // specific codes. `catalog_not_found` in particular is what lets a caller — and
-          // tests/api-key-attribution.test.ts — tell "this route exists and has no catalog"
+          // tests/server/api-key-attribution.test.ts — tell "this route exists and has no catalog"
           // apart from "this route is gone", which is the difference between admission proof
           // and a vacuous pass.
           return withCors(
@@ -1430,6 +1445,37 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         // Codex catalog (client_version) and the OpenAI list shape below stay byte-identical.
         const wantsAnthropicList = req.headers.get("anthropic-version") !== null
           || url.searchParams.get("flavor") === "anthropic";
+        /**
+         * Whether a NATIVE slug may carry a Fast sibling.
+         *
+         * Both halves are required. Upstream asserts the tier per model — the same
+         * `additional_speed_tiers` the Codex picker's own toggle is built from — but an
+         * operator capability override or the final wire resolution can still make the
+         * route ineligible, and `decideTier` would then drop the tier the row advertised.
+         *
+         * Declared here, above the Claude discovery call, because that call reads it while
+         * the raw OpenAI mapper further down does too; defining it there would leave this
+         * use in its temporal dead zone.
+         */
+        const nativeFastEligible = (metadataId: string): boolean =>
+          catalogFastRowEligible(config, { provider: OPENAI_CODEX_PROVIDER_ID, id: metadataId, native: true });
+
+        /**
+         * Whether a routed catalog row may carry a Fast sibling.
+         *
+         * A combo is its own namespace with no `config.providers` entry — declaring a
+         * provider named `combo` is rejected (combos/types.ts:191) — so provider lookup
+         * cannot classify it. Its aggregated `supportsServiceTier` is already true only
+         * when EVERY member supports the tier (aggregation.ts:201), which is the right
+         * rule for a row that fans out to all of them.
+         *
+         * Declared beside nativeFastEligible, above the Claude discovery call that reads
+         * both; defining it near the raw OpenAI mapper below would leave that use in its
+         * temporal dead zone.
+         */
+        const catalogRowFastEligible = (m: { provider: string; id: string; supportsServiceTier?: boolean }): boolean =>
+          catalogFastRowEligible(config, m);
+
         if (wantsAnthropicList && !url.searchParams.has("client_version")) {
           if (config.claudeCode?.enabled === false) return jsonResponse({ data: [] }, 200, req, policy);
           // Build Desktop 3P registry so inbound alias resolution works for subsequent requests.
@@ -1451,7 +1497,22 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             : idsParam === "desktop"
               ? "desktop3p" as const
               : (/^claude-code\//i.test(req.headers.get("user-agent") ?? "") ? "readable" as const : "desktop3p" as const);
-          const data = buildAnthropicModelInfos(desktopNativeSlugs, goOrdered, resolveAutoContext(config.claudeCode), idStyle, activeDesktop3pAlias, nativeContextLimits(config), config.fastMode);
+          const data = buildAnthropicModelInfos(
+            desktopNativeSlugs,
+            goOrdered,
+            resolveAutoContext(config.claudeCode),
+            idStyle,
+            activeDesktop3pAlias,
+            nativeContextLimits(config),
+            config.fastMode,
+            // Explicit opt-out omits the Fast predicate.
+            config.fastRows !== false
+              ? (model: { provider: string; id: string; supportsServiceTier?: boolean }) =>
+                model.provider === "native"
+                  ? nativeFastEligible(model.id)
+                  : catalogRowFastEligible(model)
+              : undefined,
+          );
           return jsonResponse({ data }, 200, req, policy);
         }
         if (url.searchParams.has("client_version")) {
@@ -1580,7 +1641,13 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         // The projection is opt-in. Keep the default path free of Cursor install detection,
         // and resolve the bundle table once for the whole list rather than once per row.
         const effortRowsEnabled = config.cursorEffortRows === true;
-        const effortRowKnownIds = effortRowsEnabled ? knownEffortRowIds(config) : undefined;
+        // Explicit opt-out skips policy resolution and additional rows.
+        const fastRowsEnabled = config.fastRows !== false;
+        // One inventory serves both grammars; building it twice would double the work on a
+        // hot path for no benefit.
+        const effortRowKnownIds = effortRowsEnabled || fastRowsEnabled
+          ? knownEffortRowIds(config)
+          : undefined;
         const privateInference = effortRowsEnabled
           ? detectCursorInstalls().find(install => install.build === "private-inference")
           : undefined;
@@ -1593,7 +1660,15 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             knownIds: effortRowKnownIds,
             table: cursorEffortTable,
             supportsReasoning: reasoningEfforts.length > 0,
-          });
+          }).flatMap(row => expandFastRow(
+            row,
+            // Only the BASE row earns a fast sibling. An effort row already spent the
+            // grammar, and the parser requires the stripped base to be routable, so
+            // `<base>--<effort>--fast` would publish a row no ingress can resolve.
+            row.id === id && nativeFastEligible(metadataId),
+            config,
+            effortRowKnownIds,
+          ));
         };
         const routedRows = await Promise.all(uniqueCatalogModelsForRawPublicList(goOrdered).map(async m => {
           // Same rule as the anthropic branch: with the global fast switch on, a client
@@ -1634,7 +1709,12 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             knownIds: effortRowKnownIds,
             table: cursorEffortTable,
             supportsReasoning: (m.reasoningEfforts ?? []).length > 0,
-          });
+          }).flatMap(expanded => expandFastRow(
+            expanded,
+            expanded.id === row.id && catalogRowFastEligible(m),
+            config,
+            effortRowKnownIds,
+          ));
         }));
         const data = [
           ...visibleNatives.flatMap(id => expandedNativeModelRow(id)),
@@ -1753,7 +1833,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           ...admissionFields(admission),
         };
         return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
-          const response = await handleSearch(req, config, logCtx, turnAdmissionLease);
+          const response = await handleSearch(req, config, logCtx, turnAdmissionLease, admission);
           addFinalRequestLog(requestId, start, logCtx, response.status,
             response.status === 499 ? { closeReason: "client_cancel" } : undefined);
           return withCors(response, req, policy);
@@ -1855,7 +1935,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         // pre-translation stream + native passthrough callbacks) — do not re-wrap the
         // translated Anthropic stream here.
         return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => withCors(
-          await handleClaudeMessages(req, config, logCtx, { requestId, start, turnAdmissionLease }, policy),
+          await handleClaudeMessages(req, config, logCtx, { requestId, start, turnAdmissionLease, admission }, policy),
           req,
           policy,
         ));
@@ -2056,6 +2136,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         undefined,
         guiSessionCandidate ?? undefined,
         config.runtimeRole ?? "standalone",
+        isApiAuthRequired(config),
       );
       if (guiFile) return guiFile;
       if (url.pathname === "/" && req.method === "GET") {
@@ -2322,6 +2403,7 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       }
     }
   } catch (error) {
+    unregisterQuotaAutoRefresh?.();
     userCostOverlayReconciler?.stop();
     backgroundLifecycle?.releaseAfterFailedStart();
     void nativeMainLifecycle.release();
@@ -2347,7 +2429,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
             ? [() => managementIngressRef.stop(closeActiveConnections)]
             : []),
           async () => {
-            userCostOverlayReconciler?.stop();
+            try {
+              userCostOverlayReconciler?.stop();
+            } finally {
+              unregisterQuotaAutoRefresh?.();
+            }
           },
         ],
         async () => {

package/src/server/management/agent-settings-routes.ts

@@ -70,7 +70,7 @@ import type { PersistedUsageAttempt } from "../../usage/log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
 import { applySystemEnvToggle } from "../system-env";
 
-import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
+import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchInitializedModels as fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
 import { readManagementJsonBody, readOptionalManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
@@ -377,7 +377,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     // sequence after the transition. A failure here is a persistence failure (the
     // writers' ok:false result or a throw from the underlying atomic write helper),
     // reported as 502 naming the failed key plus the writes that already landed.
-    // NOTE: do not name that helper literally here — tests/grok-writer-boundary.test.ts
+    // NOTE: do not name that helper literally here — tests/providers/xai/grok-writer-boundary.test.ts
     // asserts this route file contains no direct write primitive, and matches on the
     // symbol name even inside a comment.
     const scalarWrites: Array<{ field: string; run: () => { ok: true; changed: boolean } | { ok: false; error: string } }> = [];