fix(catalog): keep Codex's auto-review model so reviews stop falling back to the task model

docs-site/src/content/docs/reference/configuration/providers.md

@@ -478,10 +478,19 @@ optional pin in a hand-edited file is ignored on load without discarding the res
 
 Codex reads `auto_review_model_override` from the catalog row of the current turn's model to
 choose the model that reviews approval requests. The root `auto_review_model` setting in
-`$CODEX_HOME/config.toml` applies one reviewer to every catalog row; the provider-scoped fields
+`$CODEX_HOME/config.toml` applies one reviewer to task catalog rows; the provider-scoped fields
 below override it per provider. The [provider guide](/guides/providers/#approval-reviewer-per-provider)
 has the operator workflow and a worked example.
 
+When native OpenAI rows are included and the final catalog has an ordinary bare native row
+other than Reserve (hidden rows count), OpenCodex keeps the hidden `codex-auto-review` row so
+Codex can select its preferred approval reviewer when no override is configured. It stays out
+of model pickers, subagent choices, Desktop lists and public `/v1/models` lists. Provider and
+root reviewer overrides retain their precedence and do not stamp this internal row. Catalogs
+without an ordinary bare native row, including Reserve-only catalogs, omit it and preserve
+Codex's fallback to the task model. The reviewer receives the same multi-agent mode projection
+as ordinary native rows.
+
 `autoReviewModel` is the provider-wide reviewer target. A value can be a bare model id of that same
 provider (the catalog row is normalized to the `provider/model` slug) or a full public catalog
 slug such as `opencode-go/deepseek-v4-flash`. A bare value resolves against that provider's rows

scripts/test-layout/layout.json

@@ -2,7 +2,7 @@
   "version": 1,
   "root": "tests",
   "explicit": {
-    "claude-picker-upload.test.ts": "claude-integration", "messages-native-scope.test.ts": "claude-integration",
+    "claude-picker-upload.test.ts": "claude-integration", "messages-native-scope.test.ts": "claude-integration", "catalog-auto-review-row.test.ts": "codex-integration",
     "cli-log-view-filter.test.ts": "cli", "cli-usage-model-search.test.ts": "cli", "cli-companion-usage.test.ts": "cli", "cli-account-key-quota.test.ts": "cli",
     "cli-observe-snapshot.test.ts": "cli", "cli-access-data-plane.test.ts": "cli", "cli-access-key-guard.test.ts": "cli", "cli-access-rename.test.ts": "cli",
     "cli-access-audio.test.ts": "cli", "cli-access-audio-live.test.ts": "cli", "cli-log-follow.test.ts": "cli", "cli-injection-follow.test.ts": "cli",
@@ -19,10 +19,8 @@
     "cli-capability-provider-workflows.test.ts": "cli", "cli-capability-access-workflows.test.ts": "cli", "cli-capability-lab-workflows.test.ts": "cli", "skill-ocx-workflows.test.ts": "ci-workflows",
     "cli-capability-data.test.ts": "cli", "skill-ocx-generated.test.ts": "ci-workflows",
     "cli-update-restart.test.ts": "cli", "cli-update-restart-child.test.ts": "cli", "cli-update-restart-transport.test.ts": "cli", "cli-update-restart-home.test.ts": "cli",
-    "codex-shim-overlay.test.ts": "codex-integration",
-    "codex-shim-migration.test.ts": "codex-integration",
-    "codex-shim-overlay-transaction.test.ts": "codex-integration",
-    "codex-shim-overlay-readiness.test.ts": "codex-integration",
+    "codex-shim-overlay.test.ts": "codex-integration", "codex-shim-migration.test.ts": "codex-integration",
+    "codex-shim-overlay-transaction.test.ts": "codex-integration", "codex-shim-overlay-readiness.test.ts": "codex-integration",
     "codex-shim-overlay-candidates.test.ts": "codex-integration",
     "gui-pair-delivery.test.ts": "gui",
     "usage-antigravity-55.test.ts": "usage",

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);
   }

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";
@@ -194,7 +196,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 +226,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 +308,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 +411,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 +462,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);
@@ -539,10 +542,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 =>
@@ -921,7 +926,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 },

src/codex/catalog/control-plane.ts

@@ -0,0 +1,45 @@
+import { CODEX_INTERNAL_OPENAI_MODELS, isCodexControlPlaneModel } from "../control-plane-models";
+import { COMBO_NAMESPACE } from "../../combos";
+import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
+import { NATIVE_RESERVE_MODEL, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./native-models";
+import { isReserveCatalogProjection } from "./reserve";
+import { pinnedNativeModelRows } from "./pinned-models";
+import type { RawEntry } from "./parsing";
+
+/** Hidden ordinary natives qualify; Reserve, account choices and routed aliases do not. */
+export function hasOrdinaryNativeOpenAiRow(entries: readonly RawEntry[]): boolean {
+  return entries.some(entry => typeof entry.slug === "string"
+    && !entry.slug.includes("/")
+    && SUPPORTED_NATIVE_OPENAI_SLUGS.has(entry.slug)
+    && entry.slug !== NATIVE_RESERVE_MODEL
+    && !isReserveCatalogProjection(entry)
+    && entry.opencodex_catalog_kind !== CODEX_NATIVE_ALIAS_CATALOG_KIND
+    && entry.owned_by !== COMBO_NAMESPACE);
+}
+
+/** Keep internal reviewer metadata separate from native synthesis, picker ordering and account clones. */
+export function withCodexControlPlaneRows(
+  entries: RawEntry[],
+  sourceRows: readonly RawEntry[],
+  includeNativeOpenAi: boolean,
+  wsEnabled: boolean,
+): RawEntry[] {
+  const models = entries.filter(entry => !isCodexControlPlaneModel(entry.slug));
+  if (!includeNativeOpenAi || !hasOrdinaryNativeOpenAiRow(models)) return models;
+  for (const slug of CODEX_INTERNAL_OPENAI_MODELS) {
+    const source = sourceRows.find(entry => entry.slug === slug)
+      ?? pinnedNativeModelRows().find(entry => entry.slug === slug);
+    // A pin without the row degrades to Codex's own task-model fallback rather than failing the
+    // whole catalog write.
+    if (!source) continue;
+    const row: RawEntry = structuredClone(source);
+    row.visibility = "hide";
+    if (wsEnabled) row.supports_websockets = true;
+    else {
+      delete row.supports_websockets;
+      delete row.prefer_websockets;
+    }
+    models.push(row);
+  }
+  return models;
+}

src/codex/catalog/effort.ts

@@ -1,3 +1,5 @@
+import { hasOrdinaryNativeOpenAiRow } from "./control-plane";
+import { isCodexControlPlaneModel } from "../control-plane-models";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
@@ -385,7 +387,7 @@ export function clampEntryToCodexSupportedEfforts(
   entry: RawEntry,
   supported: ReadonlySet<string> | null,
 ): void {
-  if (!supported) return;
+  if (!supported || isCodexControlPlaneModel(entry.slug)) return;
   const levels = Array.isArray(entry.supported_reasoning_levels)
     ? entry.supported_reasoning_levels as Array<{ effort?: string }>
     : null;
@@ -532,6 +534,14 @@ export function clampCatalogModelsToObservedCodexSupport(
     else index += 1;
   }
 
+  // Only Reserve rows are currently omitted above; ordinary natives keep a fallback ladder.
+  // Also repair a persisted orphan so a removed Reserve can never leave a reviewer behind.
+  if (!hasOrdinaryNativeOpenAiRow(models)) {
+    for (let index = models.length - 1; index >= 0; index -= 1) {
+      if (isCodexControlPlaneModel(models[index]!.slug)) models.splice(index, 1);
+    }
+  }
+
   return {
     removedEfforts: [...removed].sort(),
     affectedModels: affected,

src/codex/catalog/parsing.ts

@@ -1,3 +1,4 @@
+import { isCodexControlPlaneModel } from "../control-plane-models";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
@@ -700,7 +701,7 @@ export function catalogEntryIsNativeChatGpt(entry: RawEntry): boolean {
     && entry.use_responses_lite === true
     && hasNativeOpenAiCapabilityMetadata(routedNativeSlug)
   ) return true;
-  if (UPSTREAM_NATIVE_ENTRIES.has(slug) || SUPPORTED_NATIVE_OPENAI_SLUGS.has(slug)) return true;
+  if (isCodexControlPlaneModel(slug) || UPSTREAM_NATIVE_ENTRIES.has(slug) || SUPPORTED_NATIVE_OPENAI_SLUGS.has(slug)) return true;
   return false;
 }
 

src/codex/control-plane-models.ts

@@ -0,0 +1,6 @@
+/** Exact Codex control-plane ids routed to canonical OpenAI, outside the public native roster. */
+export const CODEX_INTERNAL_OPENAI_MODELS: ReadonlySet<string> = new Set(["codex-auto-review"]);
+
+export function isCodexControlPlaneModel(slug: unknown): boolean {
+  return typeof slug === "string" && CODEX_INTERNAL_OPENAI_MODELS.has(slug);
+}

src/router.ts

@@ -1,3 +1,4 @@
+import { CODEX_INTERNAL_OPENAI_MODELS } from "./codex/control-plane-models";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "./types";
 import { createHash } from "node:crypto";
 import { peekAuthStore } from "./oauth/store";
@@ -564,9 +565,6 @@ export function comboRouteDecisionTrace(
   });
 }
 
-// Codex uses a small number of control-plane model ids that are not part of the public GPT/o
-// naming families. Keep this exact: a broad `codex-*` rule could capture a third-party model.
-const CODEX_INTERNAL_OPENAI_MODELS = new Set(["codex-auto-review"]);
 const MAX_BLOCKED_MODEL_REDIRECT_EDGES = 5;
 
 interface BlockedModelRedirectState {