@bitkyc08/opencodex 2.44.0 → 2.45.0

package/src/claude/compatibility.ts

@@ -0,0 +1,192 @@
+/** Opt-in admission for the translated Messages path; no adapter or credential state. */
+export type ClaudeCompatibilityMode = "shadow" | "enforce";
+
+// False means deliberately tolerated degradation, not lossless representation.
+const FEATURES = {
+  cache_control: false,
+  input_examples: false,
+  thinking_settings: false,
+  unknown_beta: false,
+  thinking_replay: true,
+  documents: true,
+  web_search_tool: true,
+  tool_search: true,
+  tool_reference: true,
+  deferred_tools: true,
+  strict_tools: true,
+  caller_mode: true,
+  structured_output: true,
+  service_tier: true,
+  mcp_tool: true,
+  code_execution: true,
+  computer_use: true,
+  server_tool: true,
+  context_management: true,
+  container: true,
+  inference_geo: true,
+  user_profile: true,
+  unknown_body_field: true,
+  unknown_content_block: true,
+} as const;
+
+export type ClaudeFeatureCode = keyof typeof FEATURES;
+const FEATURE_CODES = Object.keys(FEATURES) as ClaudeFeatureCode[];
+const MAX_FEATURE_CODES = 32;
+const MAX_REASON_LENGTH = 512;
+type Rec = Record<string, unknown>;
+const isRec = (value: unknown): value is Rec =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export function isClaudeCompatibilityMode(value: unknown): value is ClaudeCompatibilityMode {
+  return value === "shadow" || value === "enforce";
+}
+
+/** Project only closed codes, including when reading an untrusted persisted row. */
+export function normalizeClaudeFeatureCodes(value: unknown): ClaudeFeatureCode[] {
+  if (!Array.isArray(value)) return [];
+  const codes = new Set<ClaudeFeatureCode>();
+  for (const code of value) {
+    if (typeof code === "string" && Object.hasOwn(FEATURES, code)) codes.add(code as ClaudeFeatureCode);
+  }
+  return FEATURE_CODES.filter(code => codes.has(code)).sort().slice(0, MAX_FEATURE_CODES);
+}
+
+/** Never accept a caller-supplied reason, header value, model name or tool name. */
+export function claudeCompatibilityReason(codes: readonly ClaudeFeatureCode[], shadow: boolean): string | undefined {
+  const unsupported = codes.filter(code => FEATURES[code]);
+  if (unsupported.length === 0) return undefined;
+  return `${shadow ? "shadow: would reject" : "unsupported translated Claude features"}: ${unsupported.join(", ")}`
+    .slice(0, MAX_REASON_LENGTH);
+}
+
+const BODY_FIELDS = new Set([
+  "model", "max_tokens", "messages", "system", "tools", "tool_choice", "thinking",
+  "output_config", "metadata", "service_tier", "stop_sequences", "stream",
+  "temperature", "top_p", "top_k", "cache_control", "context_management",
+  "container", "inference_geo", "user_profile_id", "mcp_servers", "defer_tools", "deferred_tools",
+]);
+
+function activeDeferred(value: unknown): boolean {
+  return value === true || (Array.isArray(value) ? value.length > 0 : isRec(value) && Object.keys(value).length > 0);
+}
+
+function nonDirectCaller(value: unknown): boolean {
+  return value !== undefined && !(Array.isArray(value) && value.length === 1 && value[0] === "direct");
+}
+
+/** Complete finite detection. Only protocol content positions are visited, never schemas/arguments. */
+function detectFeatures(body: unknown, anthropicBeta?: string): Set<ClaudeFeatureCode> {
+  const codes = new Set<ClaudeFeatureCode>();
+  // Header-only beta semantics are outside this policy. No header bytes become codes.
+  if (anthropicBeta?.trim()) codes.add("unknown_beta");
+  if (!isRec(body)) return codes; // The existing Messages parser owns malformed top-level input.
+  if (Object.keys(body).some(key => !BODY_FIELDS.has(key))) codes.add("unknown_body_field");
+  for (const [field, code] of [
+    ["cache_control", "cache_control"], ["context_management", "context_management"],
+    ["container", "container"], ["inference_geo", "inference_geo"],
+    ["user_profile_id", "user_profile"], ["mcp_servers", "mcp_tool"],
+  ] as const) {
+    if (Object.hasOwn(body, field)) codes.add(code);
+  }
+  if (body.service_tier !== undefined && body.service_tier !== null) codes.add("service_tier");
+  if (isRec(body.thinking)) codes.add("thinking_settings");
+  if (isRec(body.output_config)
+    && (body.output_config.format != null || body.output_config.output_format != null)) codes.add("structured_output");
+  if (activeDeferred(body.defer_tools) || activeDeferred(body.deferred_tools)) codes.add("deferred_tools");
+
+  if (Array.isArray(body.tools)) {
+    for (const tool of body.tools) {
+      if (!isRec(tool)) continue;
+      if (Object.hasOwn(tool, "cache_control")) codes.add("cache_control");
+      if (Object.hasOwn(tool, "input_examples")) codes.add("input_examples");
+      if (tool.strict === true) codes.add("strict_tools");
+      if (tool.defer === true || tool.defer_loading === true) codes.add("deferred_tools");
+      if (nonDirectCaller(tool.allowed_callers)) codes.add("caller_mode");
+      const type = tool.type;
+      // Ordinary client function names do not convey hosted execution semantics.
+      if (type === undefined || type === "function" || type === "custom") continue;
+      if (type === "mcp_toolset") codes.add("mcp_tool");
+      else if (typeof type === "string" && /^web_search_\d{8}$/.test(type)) codes.add("web_search_tool");
+      else if (typeof type === "string" && /^tool_search(?:_tool_(?:regex|bm25))?(?:_\d{8})?$/.test(type)) codes.add("tool_search");
+      else if (typeof type === "string" && /^code_execution_\d{8}$/.test(type)) codes.add("code_execution");
+      else if (typeof type === "string" && /^computer(?:_toolset)?_\d{8}$/.test(type)) codes.add("computer_use");
+      else codes.add("server_tool");
+    }
+  }
+
+  const scanBlock = (block: unknown, position: "message" | "system" | "result") => {
+    if (!isRec(block)) return;
+    if (Object.hasOwn(block, "cache_control")) codes.add("cache_control");
+    if (position === "system" && block.type !== "text") codes.add("unknown_content_block");
+    if (position === "result" && (typeof block.type !== "string" || !["text", "image", "document", "tool_reference"].includes(block.type))) {
+      codes.add("unknown_content_block");
+    }
+    switch (block.type) {
+      case "text":
+      case "image": break;
+      case "document": codes.add("documents"); break;
+      case "thinking":
+      case "redacted_thinking": codes.add("thinking_replay"); break;
+      case "tool_reference": codes.add("tool_reference"); break;
+      case "tool_search_tool_result": codes.add("tool_search"); break;
+      case "web_search_tool_result": codes.add("web_search_tool"); break;
+      case "code_execution_tool_result":
+      case "bash_code_execution_tool_result":
+      case "text_editor_code_execution_tool_result": codes.add("code_execution"); break;
+      case "mcp_tool_use":
+      case "mcp_tool_result": codes.add("mcp_tool"); break;
+      case "tool_use":
+        if (block.caller !== undefined && (!isRec(block.caller) || block.caller.type !== "direct")) codes.add("caller_mode");
+        break;
+      case "server_tool_use":
+        switch (block.name) {
+          case "tool_search":
+          case "tool_search_tool_regex":
+          case "tool_search_tool_bm25": codes.add("tool_search"); break;
+          case "web_search": codes.add("web_search_tool"); break;
+          case "code_execution": codes.add("code_execution"); break;
+          case "computer": codes.add("computer_use"); break;
+          default: codes.add("server_tool");
+        }
+        break;
+      case "tool_result": break; // Children are visited below at the one supported nesting level.
+      default: codes.add("unknown_content_block");
+    }
+  };
+  if (Array.isArray(body.system)) for (const block of body.system) scanBlock(block, "system");
+  if (Array.isArray(body.messages)) {
+    for (const message of body.messages) {
+      if (!isRec(message) || !Array.isArray(message.content)) continue;
+      for (const block of message.content) {
+        scanBlock(block, "message");
+        if (isRec(block) && block.type === "tool_result" && Array.isArray(block.content)) {
+          for (const child of block.content) scanBlock(child, "result");
+        }
+      }
+    }
+  }
+  return codes;
+}
+
+export interface ClaudeCompatibilityResult {
+  featureCodes: ClaudeFeatureCode[];
+  compatible: boolean;
+  decision: "allow" | "shadow" | "reject";
+  reason?: string;
+}
+
+/** All translated targets share this policy; native passthrough never calls it. */
+export function analyzeClaudeCompatibility(
+  body: unknown,
+  opts: { mode: ClaudeCompatibilityMode; anthropicBeta?: string },
+): ClaudeCompatibilityResult {
+  const detected = detectFeatures(body, opts.anthropicBeta);
+  const compatible = !FEATURE_CODES.some(code => detected.has(code) && FEATURES[code]);
+  const featureCodes = normalizeClaudeFeatureCodes([...detected]);
+  return {
+    featureCodes,
+    compatible,
+    decision: compatible ? "allow" : opts.mode === "shadow" ? "shadow" : "reject",
+    ...(!compatible ? { reason: claudeCompatibilityReason(featureCodes, opts.mode === "shadow") } : {}),
+  };
+}

package/src/claude/model-info.ts

@@ -15,7 +15,7 @@
  *  - created_at is a fixed constant; max_input_tokens is authoritative-or-null;
  *    max_tokens is always null (no authoritative output limit exists proxy-side).
  */
-import { catalogModelEfforts, nativeEffortClamp, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
+import { orderForModelPicker, catalogModelEfforts, nativeEffortClamp, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
 import { claudeCodeAlias, claudeCodeNativeAlias } from "./alias";
 import { cursorFastIdFor } from "../adapters/cursor/catalog";
 import { desktop3pAlias } from "./desktop-3p";
@@ -114,6 +114,7 @@ export function buildAnthropicModelInfos(
   // Presence is the feature gate: the caller passes undefined when `fastRows` is off, so a
   // default install publishes nothing. The predicate answers ELIGIBILITY, not enablement.
   fastRows?: (model: CatalogModel | { provider: string; id: string }) => boolean,
+  ordering?: { modelPickerOrder?: readonly string[]; featured?: readonly string[] },
 ): AnthropicModelInfo[] {
   const out: AnthropicModelInfo[] = [];
   const seen = new Set<string>();
@@ -198,6 +199,8 @@ export function buildAnthropicModelInfos(
     // omitting it would leave this surface without the model the feature exists for.
     if (fastRows?.({ provider: "native", id: slug }) === true) pushFastVariant(info);
   }
+  const nativeEnd = out.length;
+  const routedGroups = new Map<CatalogModel, AnthropicModelInfo[]>();
   for (const m of routedModels) {
     // Global Fast has no toggle on this surface, so the fast identity is what gets listed —
     // a client here can only pick a listed id. Limited to the readable CLI style: Desktop 3P
@@ -211,6 +214,7 @@ export function buildAnthropicModelInfos(
       : aliasForRoute(m.provider, m.id);
     if (seen.has(id)) continue;
     seen.add(id);
+    const groupStart = out.length;
     const ladder = Array.isArray(m.reasoningEfforts) ? m.reasoningEfforts : [];
     const imageInput = Array.isArray(m.inputModalities) ? m.inputModalities.includes("image") : false;
     // max_input_tokens is an input limit, so a row that publishes a lower input ceiling than
@@ -238,6 +242,14 @@ export function buildAnthropicModelInfos(
     // namespace with no config.providers entry, so the caller classifies it from the
     // aggregated supportsServiceTier the row already carries.
     if (fastRows?.(m) === true) pushFastVariant(info);
+    routedGroups.set(m, out.slice(groupStart));
   }
-  return out;
+  if (!ordering?.modelPickerOrder?.length) return out;
+  // Sort only after deduplication, preserving the registry's original collision winner
+  // and keeping each model's base/1M/Fast siblings together.
+  return [
+    ...out.slice(0, nativeEnd),
+    ...orderForModelPicker([...routedGroups.keys()], ordering.modelPickerOrder, ordering.featured)
+      .flatMap(model => routedGroups.get(model)!),
+  ];
 }

package/src/cli/account-extended.ts

@@ -367,6 +367,7 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
   if (threshold !== undefined && (!Number.isInteger(threshold) || threshold < 0 || threshold > 100)) {
     return usage("Error: threshold must be an integer 0-100");
   }
+  let settings: Record<string, unknown> = {};
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
   if (action === "status") {
@@ -378,13 +379,35 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
     if (response.status !== 200 || (!genericPool && typeof response.json.autoSwitchThreshold !== "number")) {
       return apiError(response.json, "failed to read auto-switch status", response.status);
     }
-    threshold = typeof response.json.autoSwitchThreshold === "number" ? response.json.autoSwitchThreshold : 0;
+    settings = genericPool && (!response.json || typeof response.json !== "object" || Array.isArray(response.json))
+      ? {} : response.json;
+    threshold = typeof settings.autoSwitchThreshold === "number" ? settings.autoSwitchThreshold : 0;
   } else {
     const response = genericPool
       ? await apiJson(deps, baseUrl, "PUT", "/api/oauth/accounts/pool", { provider: name, autoSwitchThreshold: threshold })
       : await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/auto-switch", { threshold });
     if (response.status === 0) return proxyUnreachable(response.transportError);
     if (response.status !== 200) return apiError(response.json, "failed to update auto-switch", response.status);
+    settings = genericPool && (!response.json || typeof response.json !== "object" || Array.isArray(response.json))
+      ? {} : response.json;
+  }
+  if (genericPool) {
+    // Generic thresholds are stored independently of the enabled override. The
+    // latter may inherit global preference and never disables reactive rotation.
+    const stored = settings.autoSwitchThreshold;
+    const storedThreshold = typeof stored === "number" && Number.isInteger(stored) && stored >= 0 && stored <= 100
+      ? stored : null;
+    const poolEnabled = typeof settings.enabled === "boolean" ? settings.enabled : null;
+    const inert = settings.inert === true ? true : null;
+    // This CLI understands only the current inert generic threshold contract.
+    const enabled = false;
+    if (wantsJson) {
+      console.log(JSON.stringify({ provider: name, autoSwitchThreshold: storedThreshold, enabled, poolEnabled, inert }, null, 2));
+    } else {
+      const value = storedThreshold === null ? "unset" : `${storedThreshold}%`;
+      console.log(`auto-switch: ${inert === true ? "inactive" : "unavailable"} (stored threshold ${value}; ${inert === true ? "not applied by this pool" : "threshold support is unknown"})`);
+    }
+    return 0;
   }
   const enabled = threshold! > 0;
   if (wantsJson) console.log(JSON.stringify({ provider: name, autoSwitchThreshold: threshold, enabled }, null, 2));

package/src/cli/init.ts

@@ -3,24 +3,44 @@ import { modelSelectionGuidance } from "./model-selection-guidance";
 import { initializeProviderModelSelection } from "../providers/initial-model-selection";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { injectCodexConfig } from "../codex/inject";
-import { classifyOpenAiTierBackup, getConfigPath, getDefaultConfig, isValidProviderName, preserveOpenAiTierRollbackSnapshot, saveConfig } from "../config";
+import { classifyOpenAiTierBackup, ConfigMutationLockError, getConfigPath, getDefaultConfig, initializePersistedConfigIfMissing, isValidProviderName, observeInitialConfigState, preserveOpenAiTierRollbackSnapshot } from "../config";
+import { InitialConfigPublicationError } from "../config/initialize";
+import { redactUserPath } from "../lib/redact";
 import { enrichProviderFromCatalog } from "../oauth/key-providers";
 import { deriveInitProviders } from "../providers/derive";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 
-function createPrompt(): { ask(question: string): Promise<string>; close(): void } {
+class InitCancelledError extends Error {
+  constructor(readonly exitCode: 1 | 130) {
+    super(exitCode === 130 ? "Setup cancelled." : "stdin reached EOF while waiting for input. Re-run `ocx init` in an interactive terminal.");
+  }
+}
+
+function createPrompt(): { ask(question: string): Promise<string>; throwIfCancelled(): void; close(): void } {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   let closed = false;
-  rl.on("close", () => { closed = true; });
+  let cancellation: InitCancelledError | undefined;
+  const onInterrupt = () => {
+    cancellation = new InitCancelledError(130);
+    rl.close();
+  };
+  rl.on("SIGINT", onInterrupt);
+  process.on("SIGINT", onInterrupt);
+  rl.on("close", () => {
+    closed = true;
+    cancellation ??= new InitCancelledError(1);
+    process.off("SIGINT", onInterrupt);
+    rl.off("SIGINT", onInterrupt);
+  });
   return {
     ask(question: string): Promise<string> {
       return new Promise((resolve, reject) => {
         if (closed) {
-          reject(new Error("stdin closed before the prompt could be answered"));
+          reject(cancellation ?? new InitCancelledError(1));
           return;
         }
         const onClose = () => {
-          reject(new Error("stdin reached EOF while waiting for input"));
+          reject(cancellation ?? new InitCancelledError(1));
         };
         rl.once("close", onClose);
         rl.question(question, answer => {
@@ -29,6 +49,9 @@ function createPrompt(): { ask(question: string): Promise<string>; close(): void
         });
       });
     },
+    throwIfCancelled() {
+      if (cancellation) throw cancellation;
+    },
     close() {
       if (!closed) rl.close();
     },
@@ -88,7 +111,18 @@ export function cleanupOpenAiTierBackupAfterInit(configPath = getConfigPath()):
 }
 
 export async function runInit(): Promise<void> {
+  const initial = observeInitialConfigState();
+  if (initial === "exists") {
+    console.log(`Keeping existing config at ${redactUserPath(getConfigPath())}. Use \`ocx config\` or the dashboard to update it.`);
+    return;
+  }
+  if (initial === "invalid") {
+    console.error(`Cannot initialize ${redactUserPath(getConfigPath())}: existing config is invalid, unreadable, or not a regular file. It has been preserved.`);
+    process.exitCode = 1;
+    return;
+  }
   const prompt = createPrompt();
+  let configCreated = false;
   try {
     console.log("\n🔧 opencodex (ocx) setup\n");
 
@@ -171,7 +205,14 @@ export async function runInit(): Promise<void> {
       modelDiscovery: { newModelPolicy: "off" },
     };
 
-    saveConfig(config);
+    prompt.throwIfCancelled();
+    const outcome = initializePersistedConfigIfMissing(config);
+    if (outcome !== "created") {
+      console.error("Config appeared or changed while setup was running; keeping it and stopping setup.");
+      process.exitCode = 1;
+      return;
+    }
+    configCreated = true;
     // Init writes a fresh config, so a stale pre-migration backup from a previous
     // installation would make the next `ocx start` crash on a stale-backup
     // collision (issue #257). But only a STALE backup (unparseable, or already a
@@ -179,23 +220,34 @@ export async function runInit(): Promise<void> {
     // valid pre-migration (v1) config is a user-intentional rollback point and is
     // preserved by renaming it out of the collision path (sol review 260722).
     cleanupOpenAiTierBackupAfterInit();
-    console.log(`\n✅ Config saved to ~/.opencodex/config.json`);
+    console.log(`\n✅ Config saved to ${redactUserPath(getConfigPath())}`);
     if (oauthHint) console.log(`🔐 Authenticate this provider with:  ocx login ${providerName}`);
 
     const injectAnswer = await prompt.ask("Inject into Codex config.toml? [Y/n]: ");
+    prompt.throwIfCancelled();
     if (injectAnswer.trim().toLowerCase() !== "n") {
       console.log("Fetching available models from provider...");
-      const result = await injectCodexConfig(port, config);
+      const result = await injectCodexConfig(port, config, {
+        beforeClientWrite: () => prompt.throwIfCancelled(),
+      }).catch(error => {
+        // The injection/lock boundary may wrap the guard's cancellation error.
+        prompt.throwIfCancelled();
+        throw error;
+      });
+      prompt.throwIfCancelled();
       console.log(result.success ? `✅ ${result.message}` : `⚠️  ${result.message}`);
     }
 
     const shimAnswer = await prompt.ask("Install Codex autostart shim? [Y/n]: ");
+    prompt.throwIfCancelled();
     if (shimAnswer.trim().toLowerCase() !== "n") {
       try {
         const { installCodexShim } = await import("../codex/shim");
+        prompt.throwIfCancelled();
         const result = installCodexShim();
         console.log(result.installed ? `✅ ${result.message}` : `⚠️  ${result.message}`);
       } catch (err) {
+        if (err instanceof InitCancelledError) throw err;
         console.log(`⚠️  Codex autostart shim skipped: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
@@ -203,13 +255,18 @@ export async function runInit(): Promise<void> {
     console.log(`\n🚀 Setup complete! Run 'ocx start' to start the proxy.`);
     for (const line of modelSelectionGuidance(providerName)) console.log(line);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (/stdin (closed|reached EOF)/i.test(message)) {
-      console.error(`\n❌ ${message}. Re-run \`ocx init\` in an interactive terminal.`);
+    if (error instanceof InitCancelledError) {
+      console.error(`\n❌ ${error.message}${configCreated ? " The created config has been kept." : ""}`);
+      process.exitCode = error.exitCode;
+    } else {
+      const message = error instanceof InitialConfigPublicationError
+        ? `${error.message}${error.publication !== "not-published" ? " Config may already exist; inspect it before retrying." : ""}${error.residualTemp ? " A temporary file could not be removed; inspect the config directory." : ""}`
+        : error instanceof ConfigMutationLockError
+          ? "Config initialization could not acquire its write lock. Retry when the other config operation finishes."
+          : `Setup did not finish.${configCreated ? " The created config has been kept." : " Check the config directory and setup inputs before retrying."}`;
+      console.error(`\n❌ ${message}`);
       process.exitCode = 1;
-      return;
     }
-    throw error;
   } finally {
     prompt.close();
   }

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

@@ -2130,6 +2130,31 @@ async function gatherRoutedModelsWithAuth(
   return models;
 }
 
+/** Bound a proven Codex-forward custom row without changing its stored configuration. */
+function boundCustomNativeReasoning(
+  model: CatalogModel,
+  allowed: readonly string[],
+  nativeDefault: string | undefined,
+): CatalogModel {
+  if (allowed.length === 0 || model.reasoningEfforts === undefined) return model;
+  const bounded = { ...model };
+  if (model.reasoningEfforts.length === 0) {
+    bounded.reasoningEfforts = [];
+    delete bounded.defaultReasoningEffort;
+    return bounded;
+  }
+  const declared = new Set(model.reasoningEfforts);
+  const surviving = [...new Set(allowed)].filter(effort => declared.has(effort));
+  const fallback = nativeDefault && allowed.includes(nativeDefault) ? nativeDefault : allowed[0]!;
+  // A nonempty but incompatible declaration is not an explicit no-reasoning setting.
+  bounded.reasoningEfforts = surviving.length > 0 ? surviving : [fallback];
+  bounded.defaultReasoningEffort = model.defaultReasoningEffort
+    && bounded.reasoningEfforts.includes(model.defaultReasoningEffort)
+    ? model.defaultReasoningEffort
+    : bounded.reasoningEfforts.includes(fallback) ? fallback : bounded.reasoningEfforts[0]!;
+  return bounded;
+}
+
 async function gatherRoutedModelsUncached(
   config: OcxConfig,
   capture: GatherFlightCapture,
@@ -2394,7 +2419,7 @@ async function gatherRoutedModelsUncached(
       ...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
       // Native-alias defaults apply only where the custom row declares nothing: the explicit
       // spreads below must win (later in object order), so a stored `[]` stays empty and a
-      // declared ladder is never replaced by the alias's native ladder.
+      // declared ladder is narrowed to proven native capabilities after the merge below.
       ...(codexForwardNativeCapabilityAlias
         ? {
           codexForwardNativeCapabilityAlias: true,
@@ -2409,7 +2434,8 @@ async function gatherRoutedModelsUncached(
         : {}),
       // Explicit custom-row ladder wins over the inherited provider row below: the merge only
       // gap-fills, so a stored `[]` (explicit "no reasoning") or a declared ladder is kept
-      // verbatim instead of being replaced by the replaced row's metadata.
+      // instead of being replaced by that row's metadata. Only proven native aliases are
+      // bounded against their own capability source after the merge.
       ...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
       ...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
       ...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
@@ -2462,22 +2488,25 @@ async function gatherRoutedModelsUncached(
       ...(base.codexToolMode === undefined && replaced.codexToolMode !== undefined ? { codexToolMode: replaced.codexToolMode } : {}),
       ...(base.capabilities === undefined && replaced.capabilities !== undefined ? { capabilities: replaced.capabilities } : {}),
     } : base;
+    const reasoningBounded = codexForwardNativeCapabilityAlias
+      ? boundCustomNativeReasoning(merged, nativeReasoningEfforts(cm.modelId), nativeAliasDefaultEffort)
+      : merged;
     // Vision-sidecar coverage only: when the enriched provider's shared predicate matches
     // noVisionModels or text-without-image modelInputModalities, advertise image input so the
     // Codex app lets images reach the sidecar (#349/#344). Deliberately NOT the full
     // applyProviderConfigHints pass — custom rows are a
     // user override, so their explicit contextWindow / inputModalities / reasoning fields must be
     // preserved verbatim (the hint pass would cap context and overwrite modalities from registry).
-    const mergedContext = typeof merged.contextWindow === "number" && merged.contextWindow > 0
-      ? merged.contextWindow
+    const mergedContext = typeof reasoningBounded.contextWindow === "number" && reasoningBounded.contextWindow > 0
+      ? reasoningBounded.contextWindow
       : undefined;
-    const boundedMergedMaxInput = typeof merged.maxInputTokens === "number" && merged.maxInputTokens > 0
-      ? (mergedContext !== undefined ? Math.min(merged.maxInputTokens, mergedContext) : merged.maxInputTokens)
+    const boundedMergedMaxInput = typeof reasoningBounded.maxInputTokens === "number" && reasoningBounded.maxInputTokens > 0
+      ? (mergedContext !== undefined ? Math.min(reasoningBounded.maxInputTokens, mergedContext) : reasoningBounded.maxInputTokens)
       : undefined;
     const mergedWithHardBounds = boundedMergedMaxInput !== undefined
-      && boundedMergedMaxInput !== merged.maxInputTokens
-      ? { ...merged, maxInputTokens: boundedMergedMaxInput }
-      : merged;
+      && boundedMergedMaxInput !== reasoningBounded.maxInputTokens
+      ? { ...reasoningBounded, maxInputTokens: boundedMergedMaxInput }
+      : reasoningBounded;
     const mergedSoftCandidates = [mergedWithHardBounds.autoCompactTokenLimit, configuredAutoCompact]
       .filter((value): value is number => typeof value === "number" && value > 0);
     const mergedWithAutoCompact: CatalogModel = mergedContext !== undefined && mergedSoftCandidates.length > 0

package/src/codex/catalog/sync.ts

@@ -471,12 +471,14 @@ export function buildCatalogEntries(
   accountNativeSlugs?: readonly string[],
   accountNativeSlugsBySelector?: ReadonlyMap<string, readonly string[]>,
   keepNativeChatGptOnV1 = false,
+  modelPickerOrder: readonly string[] = [],
 ): RawEntry[] {
-  return buildCatalogEntriesFromObservedState({
+  const entries = buildCatalogEntriesFromObservedState({
     template,
     gptSlugs,
     goModels,
     featured,
+    modelPickerOrder,
     wsEnabled,
     multiAgentMode,
     exactComboSlugs,
@@ -489,6 +491,8 @@ export function buildCatalogEntries(
     accountNativeSlugs,
     accountNativeSlugsBySelector,
   });
+  applyFullModelPickerOrder(entries, modelPickerOrder);
+  return entries;
 }
 
 /** Build entries solely from caller-observed inputs, with no feature-state filesystem read. */
@@ -720,6 +724,30 @@ export function orderForSubagents(goModels: CatalogModel[], featured?: string[])
   });
 }
 
+/** Routed discovery projection; native groups and alias ownership belong to the caller. */
+export function orderForModelPicker(
+  models: readonly CatalogModel[],
+  order: readonly string[] = [],
+  featured: readonly string[] = [],
+): CatalogModel[] {
+  const pickerOrder = normalizeModelPickerOrder(order);
+  if (pickerOrder.length === 0) return [...models];
+  const pickerRank = modelPickerRank(pickerOrder);
+  const featuredRank = modelPickerRank(featured);
+  const complete = pickerOrder.some(slug => !slug.includes("/"));
+  const rank = (model: CatalogModel): number => {
+    const slug = catalogModelSlug(model);
+    const featuredIndex = featuredRank(slug) ?? featuredRank(`${model.provider}/${model.id}`);
+    const natural = featuredIndex ?? 5;
+    const index = pickerRank(slug) ?? pickerRank(`${model.provider}/${model.id}`);
+    if (complete) return index ?? pickerOrder.length + natural;
+    // Preserve the legacy featured/alias bands, including unlisted rows before listed rows.
+    if (featuredIndex !== undefined || model.nativeAlias === true) return natural;
+    return index === undefined ? natural : PICKER_ORDER_PRIORITY_BASE + index;
+  };
+  return [...models].sort((a, b) => rank(a) - rank(b));
+}
+
 /**
  * True when an existing catalog row was authored by OpenCodex routing (#855).
  * Every generated routed row — current full-slug form, the June–July 2026
@@ -875,6 +903,10 @@ export function mergeCatalogEntriesFromObservedState({
   const detachedBaselineCatalogModels = baselineCatalogModels
     .map(entry => structuredClone(entry) as RawEntry);
   const detachedRoutedEntries = routedEntries.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 =>
+    entry.opencodex_catalog_kind === CODEX_CUSTOM_MODEL_CATALOG_KIND));
   const detachedAccountBoundEntries = accountBoundEntries
     .map(entry => structuredClone(entry) as RawEntry);
   const disabledModelKeys = new Set([...disabledModels].map(slugEquivalenceKey));
@@ -1195,7 +1227,7 @@ export function mergeCatalogEntriesFromObservedState({
     // Mock-max universality (260709): preserved routed entries from disk may predate
     // the max rung — ensure it here so subagent max spawns validate on every
     // reasoning-capable entry. max only: 5.6 exact ladders (luna: no ultra) stay intact.
-    if (!exactCombo && !reserveProjection && !String(e.slug ?? "").startsWith("opencode-go/")) {
+    if (!freshCustomEntries.has(m) && !exactCombo && !reserveProjection && !String(e.slug ?? "").startsWith("opencode-go/")) {
       const levels = Array.isArray(e.supported_reasoning_levels)
         ? e.supported_reasoning_levels as Array<{ effort?: string }>
         : [];

package/src/codex/catalog.ts

@@ -8,7 +8,7 @@ export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, c
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } from "./catalog/provider-fetch";
 export { deriveComboCatalogModel, exactComboCatalogSlugs, getLastComboCatalogOmissions, resetOpenAiApiCatalogWarningStateForTests, uniqueCatalogModelsForPublicList, uniqueCatalogModelsForRawPublicList, buildComboCatalogOmission, comboCatalogOmissionReason, summarizeComboCatalogOmissions } from "./catalog/aggregation";
 export type { ComboCatalogOmission, ComboCatalogOmissionReason } from "./catalog/aggregation";
-export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache, finalizeAutoReviewModelOverride } from "./catalog/sync";
+export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, orderForModelPicker, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache, finalizeAutoReviewModelOverride } from "./catalog/sync";
 export type { ObservedCatalogMergeInput } from "./catalog/sync";
 export type { SpawnAgentSurface, SubagentRosterExclusionReason, EffectiveSubagentModel, SubagentRosterExclusion, EffectiveSubagentRoster } from "./catalog/sync";
 export { accountBoundNativeDisplayName, accountBoundNativeModelSlugs, CODEX_ACCOUNT_BOUND_CATALOG_KIND, trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./catalog/account-models";