@bitkyc08/opencodex 2.7.30 → 2.7.33-preview.20260722

package/src/cli/help.ts

@@ -94,9 +94,18 @@ const helpEntries: Record<string, HelpEntry> = {
     ],
   },
   models: {
-    usage: "ocx models [--provider <name>] [--json]",
-    summary: "List available models from configured providers.",
-    details: ["Shows statically configured models. Providers with liveModels may have additional models at runtime."],
+    usage: "ocx models [list] [--provider <name>] [--json] | add <provider> <modelId> [opts] | remove <id|provider/modelId> [--yes] | list-custom [--json]",
+    summary: "List models and manage custom (manually registered) models.",
+    details: [
+      "List available models from static config with no subcommand (liveModels may add more at runtime).",
+      "add: register a model the provider catalog does not advertise yet.",
+      "  --display-name <name>     Human label (no slashes).",
+      "  --context-window <tokens> e.g. 200000.",
+      "  --modalities text,image   Comma-separated (text|image|audio).",
+      "remove: delete a custom model by UUID or <provider>/<modelId>.",
+      "list-custom: show all custom models.",
+      "Changes apply immediately to a running proxy (catalog sync).",
+    ],
   },
   claude: {
     usage: "ocx claude [claude args...]",
@@ -113,6 +122,17 @@ const helpEntries: Record<string, HelpEntry> = {
     usage: "ocx restart",
     summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
   },
+  v2: {
+    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>",
+    summary: "Toggle the Codex multi_agent_v2 feature (multi-agent surface).",
+    details: [
+      "status                Show flag, multi-agent mode, and thread limit.",
+      "on | off              Enable/disable multi_agent_v2 (catalog resyncs).",
+      "mode <v1|default|v2>  Force all models to one surface, or respect upstream pins.",
+      "threads <n>           Set max_concurrent_threads_per_session (integer >= 1).",
+      "Flips preserve the active thread limit while moving between v1/v2 modes.",
+    ],
+  },
   health: {
     usage: "ocx health [--json]",
     summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
@@ -156,10 +176,11 @@ Usage:
   ocx gui                     Open the opencodex dashboard
   ocx update [--tag <tag>]    Update opencodex (keeps preview installs on @preview)
   ocx restart                  Stop and restart the proxy
+  ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|threads)
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
   ocx provider <sub>          Manage providers (list|add|remove|show|set-default)
   ocx account <sub>           Accounts/keys (list|current|use|refresh|auto-switch|remove|add-key)
-  ocx models [--json]         List available models from configured providers
+  ocx models <sub>            List models; manage custom models (add|remove|list-custom)
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx help [command]          Show help
   ocx --version | -v          Print version

package/src/cli/init.ts

@@ -1,6 +1,7 @@
 import * as readline from "node:readline";
+import { constants as fsConstants, copyFileSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { injectCodexConfig } from "../codex/inject";
-import { getDefaultConfig, isValidProviderName, saveConfig } from "../config";
+import { classifyOpenAiTierBackup, getConfigPath, getDefaultConfig, isValidProviderName, saveConfig } from "../config";
 import { enrichProviderFromCatalog } from "../oauth/key-providers";
 import { deriveInitProviders } from "../providers/derive";
 import type { OcxConfig, OcxProviderConfig } from "../types";
@@ -42,7 +43,7 @@ const KIND_HEADING: Record<InitKind, string> = {
 };
 
 function printMenu(providers: InitProvider[]): void {
-  console.log("Available providers:");
+  console.log("Choose your default provider (you can add more later):");
   let lastKind: InitKind | null = null;
   providers.forEach((p, i) => {
     if (p.kind !== lastKind) { console.log(`\n  ${KIND_HEADING[p.kind]}:`); lastKind = p.kind; }
@@ -53,6 +54,33 @@ function printMenu(providers: InitProvider[]): void {
 
 const envKeyFor = (id: string) => `${id.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`;
 
+/** Post-init cleanup of `.pre-openai-tiers-v2.bak` with rollback preservation (issue #257). */
+export function cleanupOpenAiTierBackupAfterInit(configPath = getConfigPath()): void {
+  const backup = `${configPath}.pre-openai-tiers-v2.bak`;
+  try {
+    if (!existsSync(backup)) return;
+    if (classifyOpenAiTierBackup(readFileSync(backup)) === "stale") {
+      unlinkSync(backup);
+      return;
+    }
+    // Publish the preserved snapshot with a no-replace copy (COPYFILE_EXCL) so a
+    // destination collision (frozen/rolled-back clock, pre-created file) can never
+    // silently overwrite another rollback snapshot; retry with a sequence suffix.
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const preserved = `${configPath}.pre-openai-tiers-v1-rollback.${Date.now()}${attempt ? `-${attempt}` : ""}.bak`;
+      try {
+        copyFileSync(backup, preserved, fsConstants.COPYFILE_EXCL);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+        throw error;
+      }
+      unlinkSync(backup);
+      console.warn(`⚠️  Kept your pre-migration config rollback snapshot at ${preserved}`);
+      return;
+    }
+  } catch { /* cleanup is best-effort; never block init on backup housekeeping */ }
+}
+
 export async function runInit(): Promise<void> {
   const prompt = createPrompt();
   console.log("\n🔧 opencodex (ocx) setup\n");
@@ -60,7 +88,7 @@ export async function runInit(): Promise<void> {
   const providers = buildInitProviders();
   printMenu(providers);
 
-  const choice = await prompt.ask("\nSelect provider (number): ");
+  const choice = await prompt.ask("\nSelect default provider (number): ");
   const idx = parseInt(choice, 10) - 1;
 
   let providerName: string;
@@ -136,6 +164,13 @@ export async function runInit(): Promise<void> {
   };
 
   saveConfig(config);
+  // 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
+  // post-migration v2 snapshot) may be deleted; a backup that still parses as a
+  // 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`);
   if (oauthHint) console.log(`🔐 Authenticate this provider with:  ocx login ${providerName}`);
 

package/src/cli/models.ts

@@ -1,11 +1,18 @@
 /**
- * `ocx models` subcommand — list available models from configured providers.
- *
- * Usage:
- *   ocx models [--provider <name>] [--json]
+ * `ocx models` subcommand — list configured models and manage custom models.
  */
-import { hasOwnProvider, loadConfig } from "../config";
-import type { OcxConfig } from "../types";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { syncModelsToCodex } from "../codex/sync";
+import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
+import { routedSlug } from "../providers/slug-codec";
+import { findLiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig, OcxCustomModel } from "../types";
+
+const ADD_USAGE = "Usage: ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities text,image,audio]";
+const REMOVE_USAGE = "Usage: ocx models remove <customId|provider/modelId> [--yes]";
+const LIST_CUSTOM_USAGE = "Usage: ocx models list-custom [--json]";
+const ALLOWED_MODALITIES = new Set(["text", "image", "audio"]);
 
 interface ModelEntry {
   provider: string;
@@ -75,7 +82,175 @@ function consumeFlagValue(args: string[], flag: string): string | undefined {
   return value;
 }
 
-export function handleModels(args: string[]): void {
+function fail(message: string, usage?: string): never {
+  console.error(`Error: ${message}`);
+  if (usage) console.error(usage);
+  process.exit(1);
+}
+
+function rejectUnexpectedArgs(args: string[], usage: string): void {
+  if (args.length === 0) return;
+  const unknown = args.filter(arg => arg.startsWith("-"));
+  fail(
+    unknown.length > 0
+      ? `Unknown flag(s): ${unknown.join(", ")}`
+      : `Unexpected argument(s): ${args.join(", ")}`,
+    usage,
+  );
+}
+
+async function syncCustomModelsIfLive(): Promise<void> {
+  const live = await findLiveProxy();
+  if (!live) return;
+  await syncModelsToCodex(live.port).catch(error => {
+    console.error(`Warning: custom model saved, but catalog sync failed: ${error instanceof Error ? error.message : String(error)}`);
+  });
+}
+
+async function handleCustomAdd(args: string[]): Promise<void> {
+  const rest = [...args];
+  const provider = rest.shift()?.trim() ?? "";
+  const modelId = rest.shift()?.trim() ?? "";
+  const displayNameValue = consumeFlagValue(rest, "--display-name");
+  const contextWindowValue = consumeFlagValue(rest, "--context-window");
+  const modalitiesValue = consumeFlagValue(rest, "--modalities");
+  rejectUnexpectedArgs(rest, ADD_USAGE);
+
+  if (!provider || !modelId) fail("provider and modelId are required", ADD_USAGE);
+  if (!isValidProviderName(provider)) fail(`invalid provider name "${provider}"`);
+  if (modelId.includes("/")) fail("modelId must not contain /");
+
+  const config = loadConfig();
+  if (!hasOwnProvider(config.providers, provider)) {
+    fail(`provider "${provider}" is not configured. See: ocx provider list`);
+  }
+
+  const displayName = displayNameValue?.trim() || undefined;
+  if (displayName?.includes("/")) fail("displayName must not contain /");
+
+  let contextWindow: number | undefined;
+  if (contextWindowValue !== undefined) {
+    contextWindow = Number(contextWindowValue);
+    if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+      fail("context window must be a positive integer");
+    }
+  }
+
+  let inputModalities: string[] | undefined;
+  if (modalitiesValue !== undefined) {
+    inputModalities = modalitiesValue.split(",").map(value => value.trim());
+    const invalid = inputModalities.filter(value => !ALLOWED_MODALITIES.has(value));
+    if (inputModalities.length === 0 || invalid.length > 0) {
+      fail("modalities must be comma-separated values from text|image|audio");
+    }
+    inputModalities = [...new Set(inputModalities)];
+  }
+
+  const existing = config.customModels ?? [];
+  const slug = routedSlug(provider, modelId);
+  if (existing.some(model => routedSlug(model.provider, model.modelId) === slug)) {
+    fail(`custom model "${slug}" already exists`);
+  }
+
+  const entry: OcxCustomModel = {
+    id: randomUUID(),
+    provider,
+    modelId,
+    ...(displayName ? { displayName } : {}),
+    ...(contextWindow ? { contextWindow } : {}),
+    ...(inputModalities ? { inputModalities } : {}),
+    addedAt: new Date().toISOString(),
+  };
+  config.customModels = [...existing, entry];
+  saveConfig(config);
+  await syncCustomModelsIfLive();
+  console.log(`Added custom model ${slug} (${entry.id}).`);
+}
+
+async function confirmCustomRemoval(model: OcxCustomModel): Promise<boolean> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail("remove requires --yes in non-interactive mode");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`Remove custom model ${routedSlug(model.provider, model.modelId)}? [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function handleCustomRemove(args: string[]): Promise<void> {
+  const rest = [...args];
+  const confirmed = consumeFlag(rest, "--yes");
+  const target = rest.shift()?.trim() ?? "";
+  rejectUnexpectedArgs(rest, REMOVE_USAGE);
+  if (!target) fail("custom model id or provider/modelId is required", REMOVE_USAGE);
+
+  const config = loadConfig();
+  const existing = config.customModels ?? [];
+  const index = target.includes("/")
+    ? existing.findIndex(model => routedSlug(model.provider, model.modelId) === target)
+    : existing.findIndex(model => model.id === target);
+  if (index === -1) fail(`custom model "${target}" not found`);
+
+  const model = existing[index];
+  if (!confirmed && !(await confirmCustomRemoval(model))) {
+    console.log("Cancelled.");
+    return;
+  }
+
+  const next = existing.filter((_, modelIndex) => modelIndex !== index);
+  config.customModels = next.length > 0 ? next : undefined;
+  saveConfig(config);
+  await syncCustomModelsIfLive();
+  console.log(`Removed custom model ${routedSlug(model.provider, model.modelId)}.`);
+}
+
+function customModelCells(model: OcxCustomModel): string[] {
+  return [
+    model.id.slice(0, 8),
+    model.modelId,
+    model.displayName ?? "-",
+    model.contextWindow ? `${Math.round(model.contextWindow / 1000)}k` : "-",
+    model.inputModalities?.join(",") ?? "-",
+  ];
+}
+
+function printCustomModelGroup(provider: string, models: OcxCustomModel[]): void {
+  const rows = models.map(customModelCells);
+  const headers = ["ID", "MODEL", "DISPLAY NAME", "CONTEXT", "MODALITIES"];
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map(row => row[column].length)));
+  const line = (cells: string[]) => cells.map((cell, column) => cell.padEnd(widths[column])).join("  ");
+  console.log(`${provider}:`);
+  console.log(`  ${line(headers)}`);
+  for (const row of rows) console.log(`  ${line(row)}`);
+  console.log();
+}
+
+function handleCustomList(args: string[]): void {
+  const rest = [...args];
+  const wantsJson = consumeFlag(rest, "--json");
+  rejectUnexpectedArgs(rest, LIST_CUSTOM_USAGE);
+  const models = loadConfig().customModels ?? [];
+  if (wantsJson) {
+    console.log(JSON.stringify(models, null, 2));
+    return;
+  }
+  if (models.length === 0) {
+    console.log("No custom models registered.");
+    return;
+  }
+  const byProvider = new Map<string, OcxCustomModel[]>();
+  for (const model of models) {
+    const group = byProvider.get(model.provider) ?? [];
+    group.push(model);
+    byProvider.set(model.provider, group);
+  }
+  for (const [provider, providerModels] of byProvider) printCustomModelGroup(provider, providerModels);
+}
+
+function handleConfiguredModels(args: string[]): void {
   const restArgs = [...args];
   const wantsJson = consumeFlag(restArgs, "--json");
   const providerFilter = consumeFlagValue(restArgs, "--provider");
@@ -136,3 +311,27 @@ export function handleModels(args: string[]): void {
   console.log("* = default model for provider");
   console.log("Note: providers with liveModels may have additional models at runtime.");
 }
+
+function runCustomCommand(command: Promise<void>): void {
+  command.catch(error => {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  });
+}
+
+export function handleModels(args: string[]): void {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "add") {
+    runCustomCommand(handleCustomAdd(rest));
+    return;
+  }
+  if (subcommand === "remove") {
+    runCustomCommand(handleCustomRemove(rest));
+    return;
+  }
+  if (subcommand === "list-custom") {
+    handleCustomList(rest);
+    return;
+  }
+  handleConfiguredModels(subcommand === "list" ? rest : args);
+}

package/src/codex/auth-api.ts

@@ -77,6 +77,7 @@ function poolAccountDto(
   return {
     id: account.id,
     email: maskEmail(account.email) ?? account.email,
+    ...(account.alias !== undefined ? { alias: account.alias } : {}),
     ...(account.plan !== undefined ? { plan: account.plan } : {}),
     ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
     isMain: false,
@@ -168,9 +169,13 @@ async function verifyCodexAccountWarmup(
 }
 
 function expireCodexAuthFlow(flowId: string | null, error = "Login cancelled"): void {
-  if (!flowId) return;
-  codexAuthLoginState.set(flowId, { status: "error", error, doneAt: Date.now() });
-  setTimeout(() => codexAuthLoginState.delete(flowId), 30_000);
+  const ids = flowId
+    ? [flowId]
+    : [...codexAuthLoginState].filter(([, state]) => state.status === "pending").map(([id]) => id);
+  for (const id of ids) {
+    codexAuthLoginState.set(id, { status: "error", error, doneAt: Date.now() });
+    setTimeout(() => codexAuthLoginState.delete(id), 30_000);
+  }
 }
 
 let mainAccountCache: { email: string | null; plan: string | null; quota: Omit<StoredAccountQuota, "updatedAt"> | null; ts: number } | null = null;
@@ -258,6 +263,7 @@ interface PoolQuotaResult {
 
 export interface CodexAuthAccountDto {
   id: string;
+  alias?: string;
   email: string;
   plan?: string | null;
   logLabel?: string;
@@ -442,6 +448,24 @@ export async function handleCodexAuthAPI(
     return jsonResponse({ ok: true });
   }
 
+  if (url.pathname === "/api/codex-auth/accounts/alias" && req.method === "PUT") {
+    const body = await req.json().catch(() => ({})) as { id?: unknown; alias?: unknown };
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    const alias = typeof body.alias === "string" ? body.alias.trim() : "";
+    if (!id || !ACCOUNT_ID_RE.test(id)) return jsonResponse({ error: "Invalid account id format" }, 400);
+    if (id === MAIN_CODEX_ACCOUNT_ID) return jsonResponse({ error: "Main Codex account alias is not configurable" }, 400);
+    if (typeof body.alias !== "string" || alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) {
+      return jsonResponse({ error: "Alias must be a string of at most 80 printable characters" }, 400);
+    }
+    const runtimeConfig = getRuntimeConfig(config);
+    const account = (runtimeConfig.codexAccounts ?? []).find(candidate => candidate.id === id && !candidate.isMain);
+    if (!account) return jsonResponse({ error: "Account not found" }, 404);
+    if (alias) account.alias = alias;
+    else delete account.alias;
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true, id, alias: alias || null });
+  }
+
   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); }
@@ -763,6 +787,24 @@ export async function handleCodexAuthAPI(
     }
   }
 
+  if (url.pathname === "/api/codex-auth/login/code" && req.method === "POST") {
+    const body = (await req.json().catch(() => ({}))) as { flowId?: unknown; input?: unknown };
+    const flowId = typeof body.flowId === "string" ? body.flowId.trim() : "";
+    const input = typeof body.input === "string" ? body.input : "";
+    if (!flowId) return jsonResponse({ error: "flowId required" }, 400);
+    if (input.length > 4096) return jsonResponse({ error: "input too long" }, 400);
+
+    // Import may yield; validate afterwards so cancel/replace cannot race a stale flow through.
+    const { submitManualLoginCode } = await import("../oauth");
+    const flow = codexAuthLoginState.get(flowId);
+    if (!flow) return jsonResponse({ error: "login flow expired or unknown" }, 400);
+    if (flow.status !== "pending") return jsonResponse({ error: "login flow is not pending" }, 400);
+
+    const result = submitManualLoginCode("chatgpt", input);
+    if (!result.ok) return jsonResponse({ error: result.error }, 400);
+    return jsonResponse({ ok: true }, 202);
+  }
+
   if (url.pathname === "/api/codex-auth/login/cancel" && req.method === "POST") {
     const body = (await req.json().catch(() => ({}))) as { flowId?: string };
     const { cancelLoginFlow } = await import("../oauth");

package/src/codex/catalog.ts

@@ -690,7 +690,7 @@ export function materializeBundledCodexCatalog(path: string, deps: BundledCatalo
 
 function loadCatalogForSync(path: string): RawCatalog | null {
   const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null;
-  if (bundled) return bundled;
+  if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog;
   const catalog = readCatalog(path);
   if (catalog && findNativeTemplate(catalog)) return catalog;
   return readCatalog(catalogBackupPathFor(path))
@@ -829,6 +829,66 @@ function ensureUltraReasoningLevel(entry: RawEntry): void {
   entry.supported_reasoning_levels = levels;
 }
 
+/** Reasoning-effort labels accepted by the installed Codex binary's bundled catalog. */
+export function codexSupportedReasoningEfforts(deps: BundledCatalogDeps = {}): Set<string> | null {
+  const bundled = loadBundledCodexCatalog(deps);
+  if (!bundled) return null;
+  const efforts = new Set<string>();
+  for (const model of bundled.models ?? []) {
+    if (typeof model.slug !== "string" || model.slug.includes("/")) continue;
+    const levels = Array.isArray(model.supported_reasoning_levels) ? model.supported_reasoning_levels : [];
+    for (const level of levels) {
+      const effort = (level as { effort?: unknown })?.effort;
+      if (typeof effort === "string") efforts.add(effort);
+    }
+    if (typeof model.default_reasoning_level === "string") efforts.add(model.default_reasoning_level);
+  }
+  return efforts.size > 0 ? efforts : null;
+}
+
+/** Highest surviving rung at or below the original default, with a conservative empty fallback. */
+export function clampedDefaultEffort(original: string, surviving: readonly string[]): string {
+  if (surviving.length === 0) return "medium";
+  const ranked = [...surviving]
+    .map(effort => ({ effort, rank: codexEffortRank(effort) }))
+    .sort((a, b) => a.rank - b.rank);
+  const originalRank = codexEffortRank(original);
+  const atOrBelow = ranked.filter(item => item.rank >= 0 && item.rank <= originalRank);
+  return (atOrBelow.at(-1) ?? ranked[0]!).effort;
+}
+
+/** Remove reasoning efforts the installed Codex binary cannot deserialize from one entry. */
+export function clampEntryToCodexSupportedEfforts(entry: RawEntry, supported: Set<string> | null): void {
+  if (!supported) return;
+  const levels = Array.isArray(entry.supported_reasoning_levels)
+    ? entry.supported_reasoning_levels as Array<{ effort?: string }>
+    : null;
+  if (levels && levels.length > 0) {
+    const kept = levels.filter(level => typeof level?.effort === "string" && supported.has(level.effort));
+    entry.supported_reasoning_levels = kept.length > 0
+      ? kept
+      : CODEX_REASONING_LEVELS
+        .filter(level => level.effort === "low" || level.effort === "medium" || level.effort === "high")
+        .map(level => ({ ...level }));
+  }
+  const currentDefault = entry.default_reasoning_level;
+  if (typeof currentDefault === "string" && !supported.has(currentDefault)) {
+    const surviving = (Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels : [])
+      .flatMap(level => typeof (level as { effort?: string })?.effort === "string"
+        ? [(level as { effort: string }).effort]
+        : []);
+    entry.default_reasoning_level = clampedDefaultEffort(currentDefault, surviving);
+  }
+}
+
+/** Clamp every catalog entry to the reasoning ladder accepted by the installed Codex binary. */
+export function clampCatalogModelsToCodexSupport(models: RawEntry[], deps: BundledCatalogDeps = {}): RawEntry[] {
+  const supported = codexSupportedReasoningEfforts(deps);
+  if (!supported) return models;
+  for (const entry of models) clampEntryToCodexSupportedEfforts(entry, supported);
+  return models;
+}
+
 /**
  * Native entry from the pinned upstream snapshot, finished for emission. Keeps the entry's
  * OWN identity (display_name, description, priority, availability_nux — it is the model's own
@@ -1240,11 +1300,22 @@ function catalogHintsFromModelsApiItem(providerName: string, item: ProviderModel
 async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs: number, contextCap?: number): Promise<CatalogModel[]> {
   if (prov.authMode === "forward") return []; // ChatGPT backend has no /models
   const apiKey = await resolveModelsAuthToken(name, prov);
-  const configured: CatalogModel[] = (prov.models ?? []).map(id => ({
+  const seedVertexDefault = prov.adapter === "google"
+    && prov.googleMode === "vertex"
+    && (prov.models?.length ?? 0) === 0
+    && Boolean(prov.defaultModel);
+  const configuredIds = seedVertexDefault && prov.defaultModel ? [prov.defaultModel] : (prov.models ?? []);
+  const configured: CatalogModel[] = configuredIds.map(id => ({
     id,
     provider: name,
     ...catalogHintsFromProviderConfig(name, prov, id, contextCap),
   }));
+  const vertexDefaultSeed = seedVertexDefault ? configured[0] : undefined;
+  const withVertexDefaultSeed = (models: CatalogModel[]): CatalogModel[] => (
+    vertexDefaultSeed && !models.some(model => model.id === vertexDefaultSeed.id)
+      ? [...models, vertexDefaultSeed]
+      : models
+  );
   if (prov.adapter === "cursor") {
     if (prov.liveModels === false || !apiKey) return configured;
     // Cursor uses a bespoke GetUsableModels RPC (not /models), returning the full effort-suffixed
@@ -1276,20 +1347,27 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
     return configured;
   }
   const fresh = getFreshCached(name, ttlMs);
-  if (fresh) return applyConfigHintsToCachedModels(name, prov, fresh, contextCap); // dedups Codex's frequent /v1/models polling within the TTL
+  if (fresh) return withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, fresh, contextCap)); // dedups Codex's frequent /v1/models polling within the TTL
   if (isModelsFetchCoolingDown(name)) {
     // A recently-failed provider (unreachable API, missing proxy, bad key) must not re-pay the
     // fetch timeout on every catalog poll — the dashboard polls this path per page load.
     const stale = getStaleCached(name);
-    return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
+    return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
   }
   const { url, headers } = buildModelsRequest(prov, apiKey, name);
+  const urlClass = new URL(url).hostname.endsWith("aiplatform.googleapis.com")
+    ? "vertex-aiplatform"
+    : "provider-models";
   try {
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
     if (!res.ok) {
       markModelsFetchFailure(name);
       const stale = getStaleCached(name);
-      return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
+      const fallback = stale ? "stale" : "configured";
+      console.warn(
+        `[opencodex] Provider model discovery for "${name}" failed with HTTP ${res.status} [urlClass=${urlClass}, fallback=${fallback}].`,
+      );
+      return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
     }
     const json = await res.json() as unknown;
     const data = json !== null && typeof json === "object" && !Array.isArray(json)
@@ -1301,7 +1379,7 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
         `[opencodex] Provider model discovery for "${name}" returned malformed 2xx data; using stale/static catalog degradation.`,
       );
       const stale = getStaleCached(name);
-      return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
+      return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
     }
     const items = data;
     const live = items.map(m => applyProviderConfigHints(name, prov, {
@@ -1324,7 +1402,7 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
       if (dated) {
         // Reapply config hints so alias-keyed overrides (modelContextWindows etc.) win.
         live.push(applyProviderConfigHints(name, prov, { ...dated, id: m.id }, contextCap));
-      } else if (shouldRetainConfiguredProviderModel(name, m.id)) {
+      } else if (seedVertexDefault || shouldRetainConfiguredProviderModel(name, m.id)) {
         live.push(m);
       } else {
         droppedConfiguredIds.push(m.id);
@@ -1341,10 +1419,14 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
     }
     setCached(name, live);
     return live;
-  } catch {
+  } catch (error) {
     markModelsFetchFailure(name);
     const stale = getStaleCached(name);
-    return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
+    const fallback = stale ? "stale" : "configured";
+    console.warn(
+      `[opencodex] Provider model discovery for "${name}" threw ${error instanceof Error ? error.name : "unknown"} [urlClass=${urlClass}, fallback=${fallback}].`,
+    );
+    return stale ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap)) : configured;
   }
 }
 
@@ -1428,7 +1510,16 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
     else warnUncataloguedComboOnce(id, combo, members);
   }
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
-  return all;
+  const customModels = (config.customModels ?? []).map(cm => ({
+    id: cm.modelId,
+    provider: cm.provider,
+    ...(cm.contextWindow ? { contextWindow: cm.contextWindow } : {}),
+    ...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
+  }));
+  // Custom rows override discovered rows that encode to the same Codex-facing slug.
+  const customKeys = new Set(customModels.map(c => routedSlug(c.provider, c.id)));
+  const deduped = all.filter(m => !customKeys.has(routedSlug(m.provider, m.id)));
+  return [...deduped, ...customModels];
 }
 
 const openAiApiCollisionWarnings = new Set<string>();
@@ -1441,11 +1532,12 @@ function intersectStrings(values: readonly string[][]): string[] {
 }
 
 function effectiveComboDefault(
-  configured: string | undefined,
+  configured: string | null | undefined,
   common: readonly string[],
 ): string | undefined {
+  if (!configured) return undefined;
   if (configured && common.includes(configured)) return configured;
-  const requestedRank = codexEffortRank(configured ?? "medium");
+  const requestedRank = codexEffortRank(configured);
   const ranked = common
     .map(effort => ({ effort, rank: codexEffortRank(effort) }))
     .filter(item => item.rank >= 0)
@@ -1903,6 +1995,7 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{ added: num
   // native template can never leak supports_websockets while the flag is off.
   const wsEnabled = websocketsEnabled(config);
   catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, disabledNativeSlugs(config), gatheredProviderNames, multiAgentMode, exactComboSlugs, hasPhysicalComboProvider);
+  clampCatalogModelsToCodexSupport(catalog.models);
 
   atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) + "\n");
   return { added: goEntries.length, path: catalogPath };