@bitkyc08/opencodex 2.45.0 → 2.46.0-preview.20260907

package/src/cli/integrations.ts

@@ -161,6 +161,39 @@ export async function handleGrokCommand(argv: string[], deps: RuntimeApiDeps = {
   });
 }
 
+/** The Raycast-only block the single-client route adds; see IntegrationStateEnvelope. */
+interface RaycastStatusBlock {
+  plan: string;
+  aiDirPresent: boolean;
+}
+
+function raycastBlock(result: unknown): RaycastStatusBlock | null {
+  if (!result || typeof result !== "object") return null;
+  const block = (result as { raycast?: unknown }).raycast;
+  if (!block || typeof block !== "object") return null;
+  const { plan, aiDirPresent } = block as Partial<RaycastStatusBlock>;
+  return typeof plan === "string" && typeof aiDirPresent === "boolean" ? { plan, aiDirPresent } : null;
+}
+
+/**
+ * Text view of one client's status.
+ *
+ * Raycast carries an extra block, and the generic summary would print it as
+ * three dotted keys. A `current` file that Raycast ignores for want of a Pro
+ * subscription is the one fact this view must not bury, so `plan` gets its own
+ * line and a missing `ai` folder gets the instruction that creates it.
+ */
+function singleClientStatusLines(result: unknown): string[] {
+  const raycast = raycastBlock(result);
+  if (!raycast) return summaryLines(result);
+  const rest = Object.fromEntries(Object.entries(result as Record<string, unknown>).filter(([key]) => key !== "raycast"));
+  const lines = [...summaryLines(rest), `plan: ${raycast.plan}`];
+  if (!raycast.aiDirPresent) {
+    lines.push('Open Raycast → Settings → AI → "Reveal Providers Config" once so the ai folder exists.');
+  }
+  return lines;
+}
+
 /**
  * The headless half of the client-integration toggle.
  *
@@ -197,7 +230,7 @@ export async function handleClientIntegrationCommand(
           : [String((result as { error?: string }).error ?? "No Aside profiles found.")]
         : rows
         ? rows.map(row => `${String(row.clientId)}: ${String(row.state)}${row.installed ? "" : " (not installed)"}`)
-        : summaryLines(result));
+        : singleClientStatusLines(result));
       return;
     }
 

package/src/cli/provider.ts

@@ -79,26 +79,37 @@ function validateAndSave(config: ReturnType<typeof loadConfig>): void {
 
 function handleList(args: string[]): void {
   const wantsJson = consumeFlag(args, "--json");
-  rejectUnknownArgs(args, "Usage: ocx provider list [--json]");
+  const wantsJsonl = consumeFlag(args, "--jsonl");
+  rejectUnknownArgs(args, "Usage: ocx provider list [--json|--jsonl]");
+
+  if (wantsJson && wantsJsonl) {
+    console.error("Use only one of --json or --jsonl.");
+    process.exit(1);
+  }
 
   const config = loadConfig();
   const configured = Object.keys(config.providers);
+  const entries = configured.map(name => {
+    const prov = config.providers[name];
+    const registryEntry = getProviderRegistryEntry(name);
+    return {
+      name,
+      adapter: prov.adapter,
+      baseUrl: prov.baseUrl,
+      authMode: prov.authMode ?? "key",
+      defaultModel: prov.defaultModel ?? null,
+      isDefault: name === config.defaultProvider,
+      source: registryEntry ? "registry" : "custom",
+      models: prov.models ?? [],
+    };
+  });
+
+  if (wantsJsonl) {
+    for (const entry of entries) console.log(JSON.stringify(entry));
+    return;
+  }
 
   if (wantsJson) {
-    const entries = configured.map(name => {
-      const prov = config.providers[name];
-      const registryEntry = getProviderRegistryEntry(name);
-      return {
-        name,
-        adapter: prov.adapter,
-        baseUrl: prov.baseUrl,
-        authMode: prov.authMode ?? "key",
-        defaultModel: prov.defaultModel ?? null,
-        isDefault: name === config.defaultProvider,
-        source: registryEntry ? "registry" : "custom",
-        models: prov.models ?? [],
-      };
-    });
     console.log(JSON.stringify({ configured: entries, registryCount: PROVIDER_REGISTRY.length }, null, 2));
     return;
   }
@@ -444,6 +455,7 @@ Subcommands:
 
 Examples:
   ocx provider list
+  ocx provider list --jsonl
   ocx provider add anthropic --api-key sk-ant-...
   ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1
   ocx provider show anthropic --json

package/src/cli/registry.ts

@@ -287,8 +287,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "api-key", usage: "ocx api-key <list|create|rotate|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",

package/src/cli/version-skew.ts

@@ -1,5 +1,5 @@
 /**
- * CLI-versus-proxy version skew (#2701).
+ * CLI-versus-proxy version skew (#2701, #3464).
  *
  * The reported failure: `ocx` on PATH is an older install than the running proxy, so its
  * help describes commands the proxy does not have and its output describes a different
@@ -9,6 +9,7 @@
  * comparison instead of reimplementing it -- two diagnostics disagreeing about whether an
  * install is stale would be worse than neither reporting it.
  */
+import { parseStrictSemver, type StrictSemver } from "../lib/strict-semver";
 
 /** Placeholder versions that mean "unknown", not "different". */
 const PLACEHOLDERS = new Set(["unknown", "0.0.0"]);
@@ -22,6 +23,30 @@ export interface VersionSkew {
   readonly warning: string | null;
 }
 
+/** Suppressed comparisons are not confirmed matches, even when both placeholders agree. */
+export function isConfirmedVersionMatch(skew: VersionSkew): boolean {
+  return skew.proxyVersion === skew.cliVersion && !PLACEHOLDERS.has(skew.cliVersion);
+}
+
+/** SemVer precedence ignores build metadata; raw equality is handled separately. */
+function compareVersions(cli: StrictSemver, proxy: StrictSemver): number {
+  for (let i = 0; i < cli.core.length; i++) {
+    if (cli.core[i]! !== proxy.core[i]!) return cli.core[i]! > proxy.core[i]! ? 1 : -1;
+  }
+  if (cli.prerelease.length === 0) return proxy.prerelease.length === 0 ? 0 : 1;
+  if (proxy.prerelease.length === 0) return -1;
+  for (let i = 0; i < Math.max(cli.prerelease.length, proxy.prerelease.length); i++) {
+    const left = cli.prerelease[i];
+    const right = proxy.prerelease[i];
+    if (left === right) continue;
+    if (left === undefined) return -1;
+    if (right === undefined) return 1;
+    if (typeof left !== typeof right) return typeof left === "bigint" ? -1 : 1;
+    return left > right ? 1 : -1;
+  }
+  return 0;
+}
+
 /**
  * Compare the running CLI against the live proxy.
  *
@@ -36,11 +61,19 @@ export function computeVersionSkew(cliVersion: string, proxyVersion: string | un
   if (proxy === null || PLACEHOLDERS.has(proxy) || PLACEHOLDERS.has(cliVersion) || proxy === cliVersion) {
     return { cliVersion, proxyVersion: proxy, skewed: false, warning: null };
   }
+  const cliSemver = parseStrictSemver(cliVersion);
+  const proxySemver = parseStrictSemver(proxy);
+  const order = cliSemver && proxySemver ? compareVersions(cliSemver, proxySemver) : 0;
+  const advice = order > 0
+    ? "the running proxy is older than this CLI. Restart the proxy using the intended current installation. "
+      + "For a background service, run ocx service repair (ocx service restart is an alias)."
+    : order < 0
+      ? "this ocx on PATH is older than the running proxy. Upgrade the CLI or resolve PATH to the intended installation."
+      : "the versions differ, but neither can be identified as older. Check which installations the CLI and proxy use.";
   return {
     cliVersion,
     proxyVersion: proxy,
     skewed: true,
-    warning: `CLI ${cliVersion} does not match the running proxy ${proxy} — this ocx on PATH is stale. `
-      + "Its help and features describe a different build. Reinstall, or run the proxy's own binary.",
+    warning: `CLI ${cliVersion} does not match the running proxy ${proxy} — ${advice}`,
   };
 }

package/src/clients/aside-profiles.ts

@@ -1,4 +1,4 @@
-import { lstatSync, readFileSync, readlinkSync, realpathSync, statSync, type Stats } from "node:fs";
+import { lstatSync, readFileSync, readlinkSync, realpathSync, statSync, type BigIntStats } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import type { IntegrationIO } from "../integrations/config-io";
@@ -14,7 +14,7 @@ export interface AsideProfile {
 }
 
 const MAX_PROFILES = 128;
-const MAX_MANIFEST_BYTES = 4 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 4n * 1024n * 1024n;
 const MAX_LEAF_LINKS = 40;
 
 function refuse(message: string): never {
@@ -30,9 +30,10 @@ function object(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function inspect(path: string, follow = false): Stats | null {
+function inspect(path: string, follow = false): BigIntStats | null {
   try {
-    return follow ? statSync(path) : lstatSync(path);
+    // File IDs can exceed Number's exact integer range; never round identities.
+    return follow ? statSync(path, { bigint: true }) : lstatSync(path, { bigint: true });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
     return refuse("a filesystem boundary could not be inspected.");
@@ -110,10 +111,10 @@ export function listAsideProfiles(env: NodeJS.ProcessEnv = process.env, home: st
   return readProfiles(root);
 }
 
-type DirectoryIdentity = { path: string; dev: number; ino: number };
+type DirectoryIdentity = { path: string; dev: bigint; ino: bigint };
 type Boundary = Array<DirectoryIdentity | null>;
 
-function sameIdentity(a: Pick<Stats, "dev" | "ino">, b: Pick<Stats, "dev" | "ino">): boolean {
+function sameIdentity(a: Pick<BigIntStats, "dev" | "ino">, b: Pick<BigIntStats, "dev" | "ino">): boolean {
   return a.dev === b.dev && a.ino === b.ino;
 }
 
@@ -162,7 +163,7 @@ function boundary(profile: AsideProfile, profiles: AsideProfile[], mutation: boo
   }
   if (absent) return identities;
   const leaf = inspect(profile.configPath);
-  if (leaf && (leaf.isSymbolicLink() || !leaf.isFile() || leaf.nlink > 1)) {
+  if (leaf && (leaf.isSymbolicLink() || !leaf.isFile() || leaf.nlink > 1n)) {
     refuse("the model catalog is a link, shared file or non-regular file.");
   }
   if (leaf && canonical(profile.configPath) !== join(parent!, "models.json")) {

package/src/clients/config-export/contracts.ts

@@ -93,7 +93,8 @@ export type ExportClientId =
   | "mcode"
   | "zcode"
   | "prime"
-  | "aside";
+  | "aside"
+  | "raycast";
 
 export interface ExportClientSpec {
   id: ExportClientId;

package/src/clients/config-export/raycast.ts

@@ -0,0 +1,106 @@
+import { exportPresentationLabel } from "../model-presentation";
+import { OPENCODE_PROVIDER_ID } from "./constants";
+import type { ExportContext, ManagedContribution } from "./contracts";
+import { authoritativeContextWindow, normalizeExportModels, singleFragment } from "./model-metadata";
+
+export interface RaycastAbility {
+  supported: boolean;
+}
+
+export type RaycastAbilityName =
+  | "temperature"
+  | "vision"
+  | "system_message"
+  | "tools"
+  | "reasoning_effort";
+
+export interface RaycastModelEntry {
+  id: string;
+  name: string;
+  context?: number;
+  abilities: Record<RaycastAbilityName, RaycastAbility>;
+}
+
+export interface RaycastProviderEntry {
+  id: string;
+  name: string;
+  base_url: string;
+  models: RaycastModelEntry[];
+}
+
+export interface RaycastGeneratedConfig {
+  providers: RaycastProviderEntry[];
+}
+
+/**
+ * Raycast appends `/chat/completions` to `base_url`, so the proxy's `/v1`
+ * root is passed through unchanged. The format has no safe credential
+ * interpolation, which is why the registry exposes it only on loopback.
+ */
+export function buildRaycastClientConfig(ctx: ExportContext): RaycastGeneratedConfig {
+  const models: RaycastModelEntry[] = normalizeExportModels(ctx.models).map(model => {
+    const hasLadder = (model.reasoningEfforts?.length ?? 0) > 0;
+    const context = authoritativeContextWindow(model.contextWindow);
+    return {
+      id: model.namespaced,
+      name: exportPresentationLabel(model),
+      ...(context !== undefined ? { context } : {}),
+      abilities: {
+        temperature: { supported: !hasLadder },
+        vision: { supported: model.inputModalities?.includes("image") ?? false },
+        system_message: { supported: true },
+        // Existing client-export convention, not a verified per-model capability:
+        // ExportModel has no authoritative tool-support field.
+        tools: { supported: true },
+        reasoning_effort: { supported: hasLadder },
+      },
+    };
+  });
+  return {
+    providers: [
+      { id: OPENCODE_PROVIDER_ID, name: "OpenCodex", base_url: ctx.baseUrl, models },
+    ],
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function summarizeRaycast(
+  document: unknown,
+): { modelCount: number; modelsWithoutLimits: number } {
+  const empty = { modelCount: 0, modelsWithoutLimits: 0 };
+  if (!isRecord(document) || !Array.isArray(document.providers)) return empty;
+  const providers = document.providers.filter(
+    provider => isRecord(provider) && provider.id === OPENCODE_PROVIDER_ID,
+  );
+  // An ambiguous managed provider has no meaningful summary either.
+  if (providers.length !== 1) return empty;
+  const provider: unknown = providers[0];
+  if (!isRecord(provider) || !Array.isArray(provider.models)) return empty;
+  const models = provider.models.filter((model): model is Record<string, unknown> => (
+    isRecord(model)
+    && typeof model.id === "string" && model.id.trim().length > 0
+    && typeof model.name === "string" && model.name.trim().length > 0
+  ));
+  return {
+    modelCount: models.length,
+    modelsWithoutLimits: models.filter(model => (
+      typeof model.context !== "number" || authoritativeContextWindow(model.context) === undefined
+    )).length,
+  };
+}
+
+/**
+ * Raycast stores providers in a sequence. The stable id selector owns only
+ * OpenCodex's element, preserving user-defined providers around it.
+ */
+export function buildRaycastContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildRaycastClientConfig(ctx);
+  return singleFragment(
+    "raycast",
+    ["providers", `[id=${OPENCODE_PROVIDER_ID}]`],
+    doc.providers[0]!,
+  );
+}

package/src/clients/config-export.ts

@@ -37,6 +37,8 @@ export type { OmpModelEntry, OmpProviderBlock, OmpGeneratedConfig } from "./conf
 export type { ZcodeModelEntry, ZcodeProviderBlock, ZcodeGeneratedConfig } from "./config-export/zcode";
 export type { DshReasoningEffort, DshWireReasoningEffort, DshModelEntry, DshProviderBlock, DshGeneratedConfig } from "./config-export/dsh";
 export type { McodeProviderBlock, McodeModelEntry, McodeGeneratedConfig } from "./config-export/mcode";
+export type { RaycastAbility, RaycastAbilityName, RaycastModelEntry, RaycastProviderEntry, RaycastGeneratedConfig } from "./config-export/raycast";
+export { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
 
 import type { OpencodeLaunchEnv, OpencodeCatalogModel, ExportContext, PiModelEntry, ManagedContribution, ManagedFragment, ExportClientId, ExportClientSpec } from "./config-export/contracts";
 import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENCODE_CONFIG_SCHEMA, OPENCODE_PROVIDER_ID, PI_API_DIALECT, LOOPBACK_API_KEY_PLACEHOLDER, HERMES_API_KEY_ENV_REF, OPENCLAW_API_KEY_ENV_REF, GAJAE_API_KEY_ENV, OPENCODE_API_KEY_ENV, HERMES_API_KEY_ENV, OPENCLAW_API_KEY_ENV } from "./config-export/constants";
@@ -45,6 +47,7 @@ import { buildOmpClientConfig, summarizeOmp, buildOmpContribution } from "./conf
 import { buildDshClientConfig, summarizeDsh, buildDshContribution } from "./config-export/dsh";
 import { buildMcodeClientConfig, summarizeMcode, buildMcodeContribution } from "./config-export/mcode";
 import { buildZcodeClientConfig, summarizeZcode, buildZcodeContribution } from "./config-export/zcode";
+import { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
 
 
 
@@ -533,6 +536,22 @@ export function asideConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(asideAccountDir(env, home), "models.json");
 }
 
+/**
+ * Raycast's Custom Providers directory. Raycast hard-codes
+ * `~/.config/raycast/ai` on macOS AND Windows: it neither honors
+ * `XDG_CONFIG_HOME` nor ships a variable of its own that relocates the file, so
+ * unlike `opencodeGlobalConfigPath` there is no override to mirror and the env
+ * parameter exists only to keep the resolver signature uniform with the rest.
+ */
+export function raycastAiDir(_env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(home, ".config", "raycast", "ai");
+}
+
+/** The providers file Raycast watches (manual.raycast.com/ai/custom-providers). */
+export function raycastConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(raycastAiDir(env, home), "providers.yaml");
+}
+
 /** Endpoint plus admission, identical for the V1 `options` and V2 `settings` field. */
 function opencodeProviderConnection(baseURL: string, config: OcxConfig): OpencodeProviderConnection {
   const options: OpencodeProviderConnection = { baseURL };
@@ -1259,6 +1278,23 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // bind would generate a config that 401s.
     loopbackOnly: true,
   },
+  raycast: {
+    id: "raycast",
+    // Not a bare `providers.yaml`: same Downloads-folder collision argument as
+    // `aside-models.json`.
+    filename: "raycast-providers.yaml",
+    destination: env => raycastConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "Raycast reads providers.yaml with no api_keys entry; loopback needs no key.",
+    build: buildRaycastClientConfig,
+    format: "yaml",
+    summarize: summarizeRaycast,
+    buildContribution: buildRaycastContribution,
+    // Raycast's provider entry has no header field, and its `api_keys` value
+    // is read literally (no env interpolation), so the only way to admit a
+    // remote bind would be a plaintext secret on disk. Refuse instead.
+    loopbackOnly: true,
+  },
 };
 
 export const EXPORT_CLIENT_IDS: readonly ExportClientId[] = Object.keys(EXPORT_CLIENTS) as ExportClientId[];

package/src/clients/model-presentation.ts

@@ -0,0 +1,61 @@
+import { CURSOR_CAPABILITIES } from "../adapters/cursor/catalog";
+import { nativeOpenAiCapabilityDisplayName } from "../codex/catalog/metadata";
+import type { ExportModel } from "./config-export/contracts";
+
+const KNOWN_ACRONYMS = new Set(["gpt", "glm", "grok"]);
+
+function titleWord(word: string): string {
+  const lower = word.toLowerCase();
+  if (KNOWN_ACRONYMS.has(lower)) return lower.toUpperCase();
+  if (/^\d+\.\d+$/.test(word)) return word;
+  return lower.charAt(0).toUpperCase() + lower.slice(1);
+}
+
+/**
+ * Last-resort label when no catalog or operator name exists. Joins dotted version
+ * tails (`5-1` → `5.1`, `2-5` → `2.5`) so Raycast reads like a product name
+ * instead of a slug.
+ */
+function humanizeModelSlug(modelId: string): string {
+  const parts = modelId.split("-");
+  const words: string[] = [];
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index]!;
+    const next = parts[index + 1];
+    if (/^\d+$/.test(part) && next !== undefined && /^\d+$/.test(next)) {
+      words.push(`${part}.${next}`);
+      index += 1;
+      continue;
+    }
+    words.push(part);
+  }
+  return words.map(titleWord).join(" ");
+}
+
+function wireModelId(model: ExportModel): string {
+  if (model.id?.trim()) return model.id.trim();
+  const slash = model.namespaced.lastIndexOf("/");
+  return slash >= 0 ? model.namespaced.slice(slash + 1) : model.namespaced;
+}
+
+/**
+ * Human-facing model label for clients whose picker shows `name` verbatim.
+ *
+ * Raycast has no second column for provider, so the shared `exportModelLabel`
+ * suffix `(anthropic)` would be noise — and its fallback is the raw wire id
+ * because management slugs are deliberately withheld from ExportModel. Resolve
+ * operator labels first, then the canonical capability tables, then a slug
+ * humanizer.
+ */
+export function exportPresentationLabel(model: ExportModel): string {
+  const configured = model.displayName?.trim();
+  if (configured) return configured;
+  const wireId = wireModelId(model);
+  const fromCursor = CURSOR_CAPABILITIES[wireId]?.displayName;
+  if (fromCursor) return fromCursor;
+  if (model.native) {
+    const native = nativeOpenAiCapabilityDisplayName(wireId);
+    if (native) return native;
+  }
+  return humanizeModelSlug(wireId);
+}

package/src/codex/catalog/sync.ts

@@ -307,6 +307,11 @@ function routedDisplayName(slug: string, model?: CatalogModel, config?: Pick<Ocx
   return slug;
 }
 
+/**
+ * Cria uma entrada nativa ou roteada a partir do snapshot upstream, de um clone
+ * do template ou de campos mínimos. Aplica os metadados e limites pertinentes
+ * sem alterar o template nem herdar sua marca de nome ou histórico de prioridade.
+ */
 export function deriveEntry(
   template: RawEntry | null,
   slug: string,
@@ -332,6 +337,7 @@ export function deriveEntry(
   }
   if (template || codexForwardNativeCapabilityAlias) {
     const e = JSON.parse(JSON.stringify(codexForwardNativeCapabilityAlias ?? template)) as RawEntry;
+    delete e.opencodex_native_display_name;
     // A cached template may carry display-order history; each new row owns its natural rank.
     delete e[SPAWN_PRIORITY_FIELD];
     e.slug = slug;
@@ -773,6 +779,20 @@ function recoverableNativeSlug(entry: RawEntry): string | null {
     : null;
 }
 
+/** Undo our display overlay before native metadata normalization and template reuse. */
+function restoreNativeDisplayName(entry: RawEntry): RawEntry {
+  const saved = entry.opencodex_native_display_name;
+  delete entry.opencodex_native_display_name;
+  if (saved && typeof saved === "object" && !Array.isArray(saved)) {
+    const label = saved as Record<string, unknown>;
+    if (recoverableNativeSlug(entry) === label.slug
+      && typeof label.original === "string" && entry.display_name === label.applied) {
+      entry.display_name = label.original;
+    }
+  }
+  return entry;
+}
+
 /** Append missing supported native rows from trusted catalog sources only. */
 export function mergeCatalogModelsWithNativeRecovery(
   primaryCatalogModels: readonly RawEntry[],
@@ -862,6 +882,8 @@ export interface ObservedCatalogMergeInput {
   readonly suppressedBareNativeSlugs?: ReadonlySet<string>;
   readonly policy: ObservedCatalogMergePolicy;
   readonly openaiContextCap?: NativeContextLimitsInput;
+  /** Exact display-only labels for bare native OpenAI models. */
+  readonly nativeDisplayNames?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -896,12 +918,14 @@ export function mergeCatalogEntriesFromObservedState({
   suppressedBareNativeSlugs = new Set(),
   policy,
   openaiContextCap,
+  nativeDisplayNames,
 }: ObservedCatalogMergeInput): RawEntry[] {
   // 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.map(entry => structuredClone(entry) as RawEntry);
+  const detachedCatalogModels = catalogModels
+    .map(entry => restoreNativeDisplayName(structuredClone(entry) as RawEntry));
   const detachedBaselineCatalogModels = baselineCatalogModels
-    .map(entry => structuredClone(entry) as RawEntry);
+    .map(entry => restoreNativeDisplayName(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.
@@ -1256,6 +1280,17 @@ export function mergeCatalogEntriesFromObservedState({
   );
   applyFullModelPickerOrder(versionedEntries, modelPickerOrder);
   for (const entry of versionedEntries) {
+    // Templates and account clones must not inherit the native row's overlay marker.
+    delete entry.opencodex_native_display_name;
+    const slug = recoverableNativeSlug(entry);
+    if (slug !== null) {
+      const label = nativeDisplayNames && Object.hasOwn(nativeDisplayNames, slug)
+        ? nativeDisplayNames[slug]?.trim() : undefined;
+      if (label && label !== entry.display_name) {
+        entry.opencodex_native_display_name = { slug, original: entry.display_name, applied: label };
+        entry.display_name = label;
+      }
+    }
     const kind = entry.opencodex_catalog_kind;
     if (trustedAccountBoundNativeCatalogSlug(entry) === undefined
       && kind !== CODEX_CUSTOM_MODEL_CATALOG_KIND
@@ -1659,6 +1694,12 @@ export function finalizeAutoReviewModelOverride(
   return applyAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), sourceModels);
 }
 
+/**
+ * Mescla o catálogo retido com os modelos visíveis e as configurações atuais,
+ * incluindo os nomes nativos. Tenta preservar o backup original e usa a permissão
+ * de escrita para publicar o resultado apenas se os bytes mudarem, retornando
+ * a contagem de entradas roteadas e por conta, o caminho e o estado da gravação.
+ */
 function writeRetainedCatalogSync({
   config,
   goModels,
@@ -1880,6 +1921,7 @@ function writeRetainedCatalogSync({
     accountBoundEntries,
     suppressedBareNativeSlugs,
     openaiContextCap,
+    nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],

package/src/codex/convergence.ts

@@ -226,6 +226,12 @@ function bindGatherPaths(
   };
 }
 
+/**
+ * Prepara um candidato de catálogo para convergência sem gravá-lo em disco.
+ * Clona a fonte e mescla as observações nativas, os modelos roteados e por conta,
+ * aplicando a configuração, inclusive nomes nativos, e os limites de raciocínio
+ * observados no runtime antes de retornar o catálogo resultante.
+ */
 function prepareCatalog(
   config: Readonly<OcxConfig>,
   source: Extract<CatalogSourceForGather, { kind: "available" }>,
@@ -366,6 +372,7 @@ function prepareCatalog(
     accountBoundEntries,
     suppressedBareNativeSlugs,
     openaiContextCap,
+    nativeDisplayNames: config.providers[OPENAI_CODEX_PROVIDER_ID]?.modelDisplayNames,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],