@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0-preview.20260912

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

@@ -0,0 +1,71 @@
+import type { ExportContext, ManagedContribution } from "./contracts";
+import { LOOPBACK_API_KEY_PLACEHOLDER, OPENCODE_PROVIDER_ID } from "./constants";
+import { authoritativeContextWindow, exportModelLabel, inputModalitiesForClient, normalizeExportModels } from "./model-metadata";
+
+/** Cline CLI/shared SDK schema at cline/cline cfe9cadab996 (2026-09-12). */
+export interface ClineModel {
+  name: string;
+  contextWindow?: number;
+  modalities?: { input: string[]; output: string[] };
+  supportsVision?: boolean;
+}
+
+export function buildClineClientConfig(ctx: ExportContext) {
+  const models: Record<string, ClineModel> = {};
+  for (const model of normalizeExportModels(ctx.models)) {
+    const input = inputModalitiesForClient("pi", model.inputModalities);
+    if (input === null) continue;
+    const contextWindow = authoritativeContextWindow(model.contextWindow);
+    models[model.namespaced] = {
+      name: exportModelLabel(model),
+      ...(contextWindow === undefined ? {} : { contextWindow }),
+      ...(model.inputModalities?.length ? {
+        modalities: { input, output: ["text"] },
+        supportsVision: input.includes("image"),
+      } : {}),
+    };
+  }
+  const connection = { baseUrl: ctx.baseUrl, protocol: "openai-responses", client: "openai" } as const;
+  return {
+    settings: {
+      version: 1,
+      modes: {},
+      providers: {
+        [OPENCODE_PROVIDER_ID]: {
+          settings: { provider: OPENCODE_PROVIDER_ID, ...connection, apiKey: LOOPBACK_API_KEY_PLACEHOLDER },
+          // Required by Cline's schema; a stable generation sentinel keeps export deterministic.
+          // The operation's actual time belongs to the OpenCodex journal.
+          updatedAt: "1970-01-01T00:00:00.000Z",
+          tokenSource: "manual",
+        },
+      },
+    },
+    catalog: {
+      version: 1,
+      providers: {
+        [OPENCODE_PROVIDER_ID]: {
+          provider: { name: "OpenCodex", ...connection },
+          models,
+        },
+      },
+    },
+  };
+}
+
+export type ClineGeneratedConfig = ReturnType<typeof buildClineClientConfig>;
+
+export function summarizeCline(document: unknown) {
+  const models = Object.values((document as ClineGeneratedConfig | undefined)?.catalog?.providers?.[OPENCODE_PROVIDER_ID]?.models ?? {});
+  return { modelCount: models.length, modelsWithoutLimits: models.filter(model => model.contextWindow === undefined).length };
+}
+
+export function buildClineContribution(ctx: ExportContext): ManagedContribution {
+  const document = buildClineClientConfig(ctx);
+  return {
+    clientId: "cline",
+    fragments: [
+      { path: ["settings", "providers", OPENCODE_PROVIDER_ID], value: document.settings.providers[OPENCODE_PROVIDER_ID] },
+      { path: ["catalog", "providers", OPENCODE_PROVIDER_ID], value: document.catalog.providers[OPENCODE_PROVIDER_ID] },
+    ],
+  };
+}

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

@@ -38,6 +38,13 @@ export interface OpencodeCatalogModel {
   id?: string;
   contextWindow?: number;
   displayName?: string;
+  /**
+   * Declared input modalities, carried verbatim from `/api/models`. Serialized as opencode's
+   * per-model `attachment` + `modalities`, because opencode gates attachments CLIENT-side:
+   * without them every `opencodex` model is text-only in its picker and an image never
+   * reaches the proxy or the vision sidecar (#4286).
+   */
+  inputModalities?: readonly string[];
   /** Declared effort ladder. Exported as opencode model variants where the client reads them. */
   reasoningEfforts?: readonly string[];
   /**
@@ -94,7 +101,9 @@ export type ExportClientId =
   | "zcode"
   | "prime"
   | "aside"
-  | "raycast";
+  | "raycast"
+  | "omo"
+  | "cline";
 
 export interface ExportClientSpec {
   id: ExportClientId;

package/src/clients/config-export/model-metadata.ts

@@ -72,6 +72,39 @@ export function inputModalitiesForClient(
   return kept.length > 0 ? kept : null;
 }
 
+/**
+ * Input modalities opencode's model schema accepts (opencode.ai/config.json, both
+ * `modalities.input` and `modalities.output`). Wider than our internal `text | image | audio`
+ * vocabulary, so unlike Pi and Gajae this filter can only drop a value no current ingress
+ * produces: `/api/custom-models`, `ocx models add` and the catalog writer all normalize to
+ * the internal three. It exists so a future ingress cannot do to opencode what `audio` did
+ * to Gajae, whose loader rejected the whole config file over one out-of-enum value.
+ */
+const OPENCODE_INPUT_MODALITIES: ReadonlySet<string> = new Set(["text", "audio", "image", "video", "pdf"]);
+
+/**
+ * opencode's per-model capability fields for one catalog row, or `undefined` when the row
+ * declares nothing.
+ *
+ * `undefined` rather than `{ input: ["text"] }`: opencode already computes an entry without
+ * capabilities as text-only, and leaving the keys out keeps every model that declares
+ * nothing byte-identical to what shipped before. A declared list is carried across as-is, so
+ * an audio-only row keeps `attachment: true` instead of being rewritten to text it cannot
+ * read — the same call Pi's exporter makes, in the opposite direction.
+ */
+export function opencodeModelCapabilities(
+  modalities: readonly string[] | undefined,
+): { attachment: boolean; modalities: { input: string[]; output: string[] } } | undefined {
+  const input: string[] = [];
+  for (const value of modalities ?? []) {
+    if (OPENCODE_INPUT_MODALITIES.has(value) && !input.includes(value)) input.push(value);
+  }
+  if (input.length === 0) return undefined;
+  // `attachment` is what opencode's client gates pasting on; `modalities` refines it into
+  // which kinds. Output is always text — nothing in the catalog declares otherwise.
+  return { attachment: input.some(value => value !== "text"), modalities: { input, output: ["text"] } };
+}
+
 /**
  * Label shared by every client: `"<displayName|id> (<native|provider|routed>)"`. The
  * provider suffix is what makes two same-named models from different upstreams

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

@@ -6,9 +6,18 @@ import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants"
 
 
 /**
- * ZCode's `~/.zcode/v2/config.json` provider entry (observed schema, validated
- * live against ZCode 3.7.7 / 3.8.1). `kind: "openai-compatible"` selects the
- * OpenAI Chat Completions protocol, which the proxy serves at `/v1/chat/completions`.
+ * ZCode's `~/.zcode/v2/config.json` provider entry (observed schema, validated live
+ * against ZCode 3.7.7 / 3.8.1 and re-extracted from 3.11.2's bundle).
+ * `kind: "openai"` selects the OpenAI Responses protocol, which the proxy serves at
+ * `/v1/responses`. ZCode's own dispatch is the authority: its
+ * `getDefaultModelProviderEndpointPathForKind` maps `anthropic` to `/v1/messages`,
+ * `openai` to `/responses`, and `openai-compatible` to `/chat/completions`.
+ *
+ * Responses is the only surface the proxy speaks natively. The Chat and Anthropic
+ * inbounds translate their body into a Responses shape and replay it through
+ * `handleResponses`, then translate the stream back, so the previous
+ * `openai-compatible` wiring paid two translations per turn and reshaped tool-call
+ * deltas and reasoning blocks on the way through.
  * `apiKeyRequired` keeps ZCode's UI from prompting for a key it does not need on
  * loopback; the serialized key is always the non-secret loopback placeholder.
  */
@@ -30,7 +39,7 @@ export interface ZcodeModelEntry {
 
 export interface ZcodeProviderBlock {
   name: "OpenCodex";
-  kind: "openai-compatible";
+  kind: "openai";
   enabled: true;
   source: "custom";
   options: {
@@ -46,11 +55,12 @@ export interface ZcodeGeneratedConfig {
 }
 
 /**
- * ZCode dials the OpenAI Chat Completions surface (`openai-compatible`), which
- * appends `/chat/completions` to `baseURL`. We supply `baseURL` with the `/v1`
- * suffix so requests land on `/v1/chat/completions`. Model ids are the proxy's canonical
- * `provider/id` selectors, which `/v1/chat/completions` resolves directly. Context
- * limits follow the authoritative-window rule: a model without one ships
+ * ZCode dials the OpenAI Responses surface (`openai`), which appends `/responses` to
+ * `baseURL`. We supply `baseURL` with the `/v1` suffix so requests land on
+ * `/v1/responses`; ZCode's `normalizeModelProviderBaseUrlForKind` strips only the
+ * `/responses` suffix for this kind, so the `/v1` root survives. Model ids are the
+ * proxy's canonical `provider/id` selectors, which `/v1/responses` resolves directly.
+ * Context limits follow the authoritative-window rule: a model without one ships
  * without `limit` rather than guessing. Modalities are ZCode's observed
  * `text`-floor vocabulary; image-capable rows advertise image input.
  */
@@ -73,8 +83,9 @@ export function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig
       entry.limit = { context };
     }
     // `none` is a Codex omit-sentinel, not a ZCode picker option. Keep catalog
-    // `ultra` when present: ZCode forwards the selected variant as
-    // `reasoning_effort`. Set `defaultVariant` only when it survives that filter.
+    // `ultra` when present: ZCode forwards the selected variant to the wire field its
+    // kind uses — `reasoning.effort` on `openai`, which is what `/v1/responses` reads
+    // natively. Set `defaultVariant` only when it survives that filter.
     const efforts = sanitizeCodexReasoningEfforts(model.reasoningEfforts)
       ?.filter(effort => effort !== "none");
     if (efforts && efforts.length > 0) {
@@ -91,7 +102,7 @@ export function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig
     provider: {
       [OPENCODE_PROVIDER_ID]: {
         name: "OpenCodex",
-        kind: "openai-compatible",
+        kind: "openai",
         enabled: true,
         source: "custom",
         options: {

package/src/clients/config-export.ts

@@ -21,7 +21,7 @@
  */
 import { homedir } from "node:os";
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
@@ -42,11 +42,12 @@ export { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution }
 
 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";
-import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, normalizeExportModels, inputModalitiesForClient, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
+import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, normalizeExportModels, inputModalitiesForClient, opencodeModelCapabilities, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
 import { buildOmpClientConfig, summarizeOmp, buildOmpContribution } from "./config-export/omp";
 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 { buildClineClientConfig, summarizeCline, buildClineContribution } from "./config-export/cline";
 import { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
 
 
@@ -54,6 +55,14 @@ import { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution }
 export interface OpencodeModelEntry {
   name: string;
   limit?: { context: number; output: number };
+  /**
+   * opencode's own capability fields, derived from the catalog row's declared input
+   * modalities. Written only when the row declares at least one — an entry without them is
+   * what opencode already treats as text-only, and omitting them keeps an undeclared model
+   * byte-identical to what shipped before.
+   */
+  attachment?: boolean;
+  modalities?: { input: string[]; output: string[] };
 }
 
 /**
@@ -458,6 +467,51 @@ export function primeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(primeAgentDir(env, home), "models.json");
 }
 
+/**
+ * omo resolves its agent directory from THREE variables, in its own order:
+ * `OMO_CODING_AGENT_DIR`, then `SENPI_CODING_AGENT_DIR`, then
+ * `PI_CODING_AGENT_DIR`, falling back to `~/.omo/agent`. That is not an
+ * inference from the family resemblance — `bin/lib/agent-dir.js` publishes the
+ * list as `AGENT_DIR_ENV_NAMES` and the launcher pins the first two to whatever
+ * it resolves before spawning senpi, so the engine can never disagree with it.
+ *
+ * The order is load-bearing rather than cosmetic. A user with both
+ * `PI_CODING_AGENT_DIR` and `OMO_CODING_AGENT_DIR` set runs omo out of the omo
+ * one; checking Pi's first would have us write a catalog omo never reads.
+ *
+ * Each variable reports under its OWN name, because telling someone that
+ * `PI_CODING_AGENT_DIR` is relative when they set `OMO_CODING_AGENT_DIR` sends
+ * them to the wrong line of their shell profile. An empty or whitespace value
+ * falls through to the next name, which is what omo's own `.trim()`-then-test
+ * loop does.
+ *
+ * One divergence is deliberate: omo `resolve()`s a relative override against its
+ * own cwd and does not expand `~`. We refuse the relative form and do expand
+ * `~`, exactly as Pi, Prime, MCode and ZCode already do, because a background
+ * proxy and a foreground client have different working directories and would
+ * otherwise disagree about which file is named.
+ *
+ * Consequence worth knowing: a user who sets only `PI_CODING_AGENT_DIR` has Pi
+ * and omo reading ONE `models.json`. Both clients emit the same provider block
+ * through the same builder so the bytes agree; what cannot be shared is the
+ * ownership record, since two enabled clients would claim one file. That is
+ * omo's contract, not ours to paper over.
+ */
+export function omoAgentDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const omo = env.OMO_CODING_AGENT_DIR?.trim();
+  if (omo) return absoluteClientPath(omo, home, "OMO_CODING_AGENT_DIR");
+  const senpi = env.SENPI_CODING_AGENT_DIR?.trim();
+  if (senpi) return absoluteClientPath(senpi, home, "SENPI_CODING_AGENT_DIR");
+  const pi = env.PI_CODING_AGENT_DIR?.trim();
+  if (pi) return absoluteClientPath(pi, home, "PI_CODING_AGENT_DIR");
+  return join(home, ".omo", "agent");
+}
+
+/** omo's canonical custom-provider catalog, read by the senpi engine it wraps. */
+export function omoConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(omoAgentDir(env, home), "models.json");
+}
+
 /**
  * Aside's state root. Unlike every other client here, Aside ships NO variable
  * that relocates it: its CLI carries `ASIDE_DAEMON_BASE_URL`,
@@ -614,13 +668,30 @@ export function opencodeProviderBlocks(
     if (context !== undefined) {
       entry.limit = { context, output: outputBudgetFor(context) };
     }
+    // `attachment` / `modalities` are fields of opencode's V1 model schema — the shape its
+    // published config.json defines and the one its loader reads (verified against opencode
+    // 1.18.30, src/provider/provider.ts: `model.attachment ?? …` / `model.modalities?.input`).
+    // They ride on both generations anyway: the two blocks are two spellings of one model list,
+    // and the V2 model schema (capabilities.{tools,input,output}, which opencode fills by
+    // migrating this same `modalities` field) ignores keys it does not define — its loader
+    // decodes with `onExcessProperty: "ignore"`. Same values on both, so a merge cannot make
+    // the two entries disagree.
+    const capabilities = opencodeModelCapabilities(model.inputModalities);
+    if (capabilities) {
+      entry.attachment = capabilities.attachment;
+      entry.modalities = capabilities.modalities;
+    }
     v1Models[key] = entry;
     const variants = opencodeEffortVariants(model);
-    // Own `limit` object, not a shared reference: the two blocks are serialized and reasoned
-    // about separately, and an in-place edit of one must never move the other.
+    // Own `limit` and `modalities` objects, not shared references: the two blocks are
+    // serialized and reasoned about separately, and an in-place edit of one must never move
+    // the other.
     v2Models[key] = {
       ...entry,
       ...(entry.limit ? { limit: { ...entry.limit } } : {}),
+      ...(entry.modalities
+        ? { modalities: { input: [...entry.modalities.input], output: [...entry.modalities.output] } }
+        : {}),
       ...(variants ? { variants } : {}),
     };
   }
@@ -1109,6 +1180,44 @@ function buildAsideContribution(ctx: ExportContext): ManagedContribution {
   return singleFragment("aside", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
 }
 
+/**
+ * omo is the Pi document again, and this time the engine was checked rather
+ * than inferred: `omo-ai@beta` is a launcher around `@code-yeongyu/senpi`, and
+ * senpi's compiled validator accepts what `buildPiClientConfig` emits verbatim —
+ * the keyed `providers`, the `models` ARRAY whose identity is `id`, the
+ * `openai-completions` dialect, the loopback placeholder, and the
+ * `thinkingLevelMap` levels. Evidence:
+ * `devlog/_plan/260912_omo_client_integration/001_omo_contract.md`.
+ *
+ * The flag is passed HERE as well as in the spec's `build`, which is the one
+ * thing Prime and Aside do not do. They pass the default on both paths, so they
+ * are consistent; passing it on only one would make `ocx export --client omo`
+ * emit a `compat` block while enable and refresh wrote a file without it, and
+ * the two would drift apart at the first refresh.
+ */
+function buildOmoContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildPiClientConfig(ctx, true);
+  return singleFragment("omo", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
+}
+
+/** Cline's shared SDK store; command-local --config must be mirrored by the env override. */
+export function clineConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const explicit = env.CLINE_PROVIDER_SETTINGS_PATH?.trim();
+  const data = env.CLINE_DATA_DIR?.trim();
+  const root = env.CLINE_DIR?.trim();
+  const path = explicit ? absoluteClientPath(explicit, home, "CLINE_PROVIDER_SETTINGS_PATH")
+    : join(data ? absoluteClientPath(data, home, "CLINE_DATA_DIR")
+      : join(root ? absoluteClientPath(root, home, "CLINE_DIR") : join(home, ".cline"), "data"), "settings", "providers.json");
+  if (basename(path).toLowerCase() === "models.json") {
+    throw new ClientPathError("CLINE_PROVIDER_SETTINGS_PATH must differ from the sibling models.json catalog");
+  }
+  return path;
+}
+
+export function clineSettingsDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return dirname(clineConfigPath(env, home));
+}
+
 export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
   opencode: {
     id: "opencode",
@@ -1297,6 +1406,49 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // remote bind would be a plaintext secret on disk. Refuse instead.
     loopbackOnly: true,
   },
+  /*
+   * Appended rather than filed beside the other Pi-family clients on purpose.
+   * `EXPORT_CLIENT_IDS` is `Object.keys(EXPORT_CLIENTS)`, so this object's
+   * insertion order IS the public order, and three tests assert it exactly. The
+   * existing sequence is landing order — `pi` second, `prime` eleventh — not a
+   * grouping, so appending is the edit that leaves the other thirteen alone.
+   */
+  omo: {
+    id: "omo",
+    // Not a bare `models.json`: same Downloads-folder collision argument as
+    // `prime-models.json` and `aside-models.json`.
+    filename: "omo-models.json",
+    destination: env => omoConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "omo reads a non-secret placeholder from models.json; loopback needs no key.",
+    build: ctx => buildPiClientConfig(ctx, true),
+    format: "json",
+    summarize: summarizePi,
+    buildContribution: buildOmoContribution,
+    /*
+     * Loopback-only for OMP's and Prime's reason, NOT Pi's and Aside's. senpi's
+     * provider block does accept a `headers` map and does interpolate `$ENV` in
+     * its values, so unlike Aside there is somewhere the dedicated admission
+     * header could live. What does not exist is a builder that emits one:
+     * `buildPiClientConfig` writes no headers at all, which is why `pi` is
+     * loopback-only too. Teaching the shared builder to emit them would change
+     * four clients at once, so remote wiring is deferred and a non-loopback bind
+     * refuses rather than generating a config that 401s.
+     */
+    loopbackOnly: true,
+  },
+  cline: {
+    id: "cline",
+    filename: "cline-config-bundle.json",
+    destination: env => clineConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "Cline CLI bundle: settings goes in providers.json, catalog in sibling models.json. Stop Cline before enabling/syncing/restoring, then restart. Select --provider opencodex; the default provider stays unchanged. Loopback only.",
+    build: buildClineClientConfig,
+    format: "json",
+    summarize: summarizeCline,
+    buildContribution: buildClineContribution,
+    loopbackOnly: true,
+  },
 };
 
 export const EXPORT_CLIENT_IDS: readonly ExportClientId[] = Object.keys(EXPORT_CLIENTS) as ExportClientId[];

package/src/codex/account-store.ts

@@ -751,8 +751,13 @@ export async function forceRefreshCodexPoolToken(
   };
 }
 
-export async function getValidCodexToken(id: string): Promise<CodexTokenResult> {
-  const result = await resolveCodexToken(id);
+export async function getValidCodexToken(
+  id: string,
+  options: { signal?: AbortSignal } = {},
+): Promise<CodexTokenResult> {
+  // Cancellation ends THIS caller's wait. A shared refresh already in flight keeps running for
+  // whoever else awaits it, which is what `awaitOwnCancellation` inside the resolver preserves.
+  const result = await resolveCodexToken(id, undefined, options.signal);
   return {
     accessToken: result.accessToken,
     chatgptAccountId: result.chatgptAccountId,

package/src/codex/auth-context.ts

@@ -1023,7 +1023,7 @@ export async function resolveCodexAuthContext(
   }
 
   try {
-    const token = await getValidCodexToken(accountId);
+    const token = await getValidCodexToken(accountId, { signal: options.signal });
     assertCodexAccountValidationReady(accountId);
     return {
       kind: "pool",

package/src/codex/catalog/effort.ts

@@ -59,9 +59,10 @@ export function nativeEffortClamp(slug: string, effort: string | undefined): str
     : [];
   if (levels.length === 0) {
     // Not snapshot-covered. gpt-5.6 natives have a REAL max rung (ensureGpt56ReasoningLevels
-    // restores it even off-snapshot) -> never clamp. Every other bare native (gpt-5.5/5.4/
-    // 5.4-mini/5.3-codex-spark and future old-ladder slugs) really stops at xhigh — the
-    // ChatGPT backend error names exactly none..xhigh — so clamp the synthetic top tier.
+    // restores it even off-snapshot) -> never clamp. Every other bare native (gpt-5.5,
+    // 5.3-codex-spark, a retired slug a client still asks for, and future old-ladder slugs)
+    // really stops at xhigh — the ChatGPT backend error names exactly none..xhigh — so clamp
+    // the synthetic top tier.
     return isGpt56NativeSlug(slug) ? null : "xhigh";
   }
   const supported = levels.flatMap(l => typeof l.effort === "string" ? [l.effort] : []);

package/src/codex/catalog/metadata.ts

@@ -48,6 +48,7 @@ import {
   NATIVE_OPENAI_MODELS,
   SELF_DESCRIBED_NATIVE_OPENAI_MODELS,
   SUPPORTED_NATIVE_OPENAI_SLUGS,
+  RETIRED_NATIVE_OPENAI_MODELS,
   hasNativeOpenAiCapabilityMetadata,
   isNativeOpenAiCapabilityAliasModel,
   nativeOpenAiAliasPresentation,
@@ -63,6 +64,7 @@ export {
   NATIVE_OPENAI_MODELS,
   SELF_DESCRIBED_NATIVE_OPENAI_MODELS,
   SUPPORTED_NATIVE_OPENAI_SLUGS,
+  RETIRED_NATIVE_OPENAI_MODELS,
   hasNativeOpenAiCapabilityMetadata,
   isNativeOpenAiCapabilityAliasModel,
   nativeOpenAiAliasPresentation,
@@ -120,8 +122,7 @@ export function isUnsupportedOpenAiNativeSlug(slug: string): boolean {
  *
  * This is an OPERATING CAP, not the hard ceiling — the same shape upstream uses. The live
  * catalog reports `context_window: 272000` against a `max_context_window: 872000` for these
- * slugs, and gpt-5.4 runs 272,000 against 1,000,000: the advertised window is always well
- * inside what the model can take.
+ * slugs: the advertised window is always well inside what the model can take.
  *
  * The hard ceiling here was measured on 2026-08-17 against a real Codex-login account:
  * `POST /backend-api/codex/responses` admitted 921,508 input tokens and refused 922,013 with
@@ -162,7 +163,6 @@ const NATIVE_GPT56_FAMILY = new Set<string>([
 
 export const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: number; maxContextWindow?: number; maxInputTokens?: number }> = {
   "gpt-5.5": { contextWindow: 272_000, maxContextWindow: 272_000 },
-  "gpt-5.4": { contextWindow: 1_000_000, maxContextWindow: 1_000_000 },
   "gpt-5.3-codex-spark": { contextWindow: 100_000, maxContextWindow: 100_000 },
   "gpt-5.6-sol": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_MAX_INPUT_TOKENS, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
   "gpt-5.6-terra": { contextWindow: NATIVE_GPT56_CONTEXT_WINDOW, maxContextWindow: NATIVE_GPT56_MAX_INPUT_TOKENS, maxInputTokens: NATIVE_GPT56_MAX_INPUT_TOKENS },
@@ -537,7 +537,7 @@ function upstreamNativeEntryForSlug(slug: string): RawEntry | undefined {
   const sourceSlug = nativeOpenAiCapabilitySourceSlug(slug);
   // A self-described native returns its OWN pinned row; the alias-cloning branch below stays
   // reserved for slugs that genuinely borrow another model's identity. The allowlist is explicit
-  // rather than "has a pinned entry", which would also admit gpt-5.5/gpt-5.4/gpt-5.4-mini into
+  // rather than "has a pinned entry", which would also admit gpt-5.5/gpt-5.2/codex-auto-review into
   // the sync-replacement authority this map carries.
   if (!sourceSlug.startsWith("gpt-5.6-") && !SELF_DESCRIBED_NATIVE_OPENAI_MODELS.has(slug)) {
     return undefined;
@@ -696,6 +696,10 @@ function hasNativeCatalogRowShape(entry: RawEntry): boolean {
 function observedAccountBoundNativeSlug(entry: RawEntry): string | undefined {
   const accountBound = trustedAccountBoundNativeCatalogSlug(entry);
   const slug = accountBound ?? (typeof entry.slug === "string" ? entry.slug : "");
+  // A retired native is refused at this one choke point rather than at each call site: every
+  // observation path funnels through here, and an admitted retired slug comes back as a real
+  // catalog row — bare or account-qualified — with capabilities synthesized from the template.
+  if (RETIRED_NATIVE_OPENAI_MODELS.has(slug)) return undefined;
   if (!isAccountBoundOpenAiNativeSlug(slug)
     || (entry.supported_in_api !== true && !(slug === NATIVE_RESERVE_MODEL && entry.supported_in_api === false))
     || (slug === NATIVE_RESERVE_MODEL && entry[RESERVE_METADATA_SOURCE_FIELD] !== undefined

package/src/codex/catalog/native-models.ts

@@ -72,9 +72,11 @@ const NATIVE_OPENAI_CAPABILITY_SOURCES: Readonly<Record<string, string>> = Objec
  *
  * Membership authorizes `upstreamNativeEntryForSlug` to return the pinned entry directly. It is
  * an explicit list, not a structural `PINNED_UPSTREAM_MODELS.has(slug)` predicate: the pin also
- * holds `gpt-5.5`, `gpt-5.4` and `gpt-5.4-mini`, and admitting those into
+ * holds `gpt-5.5`, `gpt-5.2` and `codex-auto-review`, and admitting those into
  * `UPSTREAM_NATIVE_ENTRIES` would newly authorize replacing their persisted catalog rows during
- * sync — an invariant that map's own comment reserves for the GPT-5.6 family.
+ * sync — an invariant that map's own comment reserves for the GPT-5.6 family. The snapshot
+ * keeps rows this runtime does not expose, which is exactly why presence in the pin cannot be
+ * the predicate: `gpt-5.4` and `gpt-5.4-mini` are still pinned after their retirement.
  */
 export const SELF_DESCRIBED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
   NATIVE_GPT6_ASTRA_MODEL,
@@ -153,7 +155,7 @@ export function nativeOpenAiAliasPresentation(slug: string): { displayName: stri
  * Devlog: 260816_codexrs_multiagent_v2_and_history_perf/011 §4-bis.
  */
 export const NATIVE_OPENAI_MODELS = [
-  "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark",
+  "gpt-5.5", "gpt-5.3-codex-spark",
   "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna",
   NATIVE_DAYBREAK_BLUE_MODEL,
   NATIVE_GPT6_ASTRA_MODEL,
@@ -161,6 +163,24 @@ export const NATIVE_OPENAI_MODELS = [
 
 export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);
 
+/**
+ * Natives this runtime used to ship that upstream has since retired.
+ *
+ * Leaving `NATIVE_OPENAI_MODELS` is not enough on its own. An account-bound observation admits
+ * any native it sees that is NOT already in `SUPPORTED_NATIVE_OPENAI_SLUGS` — that is how a
+ * genuinely new upstream model reaches one entitled account before this repo knows about it. A
+ * retired slug fails that same membership test, so a stale `selector/gpt-5.4` row persisted in a
+ * user's catalog or models cache would be re-observed as an unknown native and synthesized
+ * straight back into the picker, one sync after the removal took it out.
+ *
+ * This set is the difference between the two cases: unknown-and-new is admitted, known-and-dead
+ * is refused. It is deliberately explicit rather than a version heuristic, because the only
+ * thing that makes a slug retired is upstream withdrawing it.
+ */
+export const RETIRED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
+  "gpt-5.4", "gpt-5.4-mini",
+]);
+
 /**
  * Natives that retain the physical main account as a read-free sentinel during a native-main
  * drain, instead of reading as unavailable and letting the subagent fallback chain advance.
@@ -172,7 +192,7 @@ export const SUPPORTED_NATIVE_OPENAI_SLUGS = new Set(NATIVE_OPENAI_MODELS);
  * flipped false — letting a drain silently rewrite the operator's configured subagent model.
  *
  * It is an explicit list rather than `SUPPORTED_NATIVE_OPENAI_SLUGS`, which would have widened
- * the sentinel to `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini` and `gpt-5.3-codex-spark` as well. Those
+ * the sentinel to `gpt-5.5` and `gpt-5.3-codex-spark` as well. Those
  * models were never covered, and widening would turn "fell back and answered" into a
  * maintenance error for the most commonly configured fallback slug in the repo. Membership is
  * the set the drain behaviour was actually reasoned about: the account-gated natives plus the

package/src/codex/catalog/parsing.ts

@@ -183,6 +183,23 @@ export const ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS = new Set([
   // Issue #2330: OpenCode Go models absent from current documentation or returning terminal HTTP 400 errors.
   "opencode-go/mimo-v2-omni",
   "opencode-go/mimo-v2-pro",
+  /*
+   * DeepSeek retired `deepseek-v4-pro` on 2026-09-14 04:00 UTC and routes its requests to
+   * V4.1-Flash (api-docs.deepseek.com/news/news260910). Deleting the registry rows removes
+   * the model on providers that publish a static roster, but every provider below discovers
+   * its models live — there, a deleted row does not remove anything, it only strips the
+   * context window, the effort ladder and the text-only hint, so the retired model would
+   * keep appearing with its capabilities broken. Excluding the slug is what actually takes
+   * it out of the routed catalog.
+   */
+  "command-code/deepseek-deepseek-v4-pro",
+  "commandcode/deepseek-deepseek-v4-pro",
+  "orcarouter/deepseek-deepseek-v4-pro",
+  "cline-pass/cline-pass-deepseek-v4-pro",
+  "baseten/deepseek-ai-DeepSeek-V4-Pro",
+  "digitalocean/deepseek-v4-pro",
+  "qoder/DeepSeek-V4-Pro",
+  "codebuddy/deepseek-v4-pro",
 ]);
 
 export function isRoutedModelCompatibilityExcluded(slug: string): boolean {
@@ -501,7 +518,8 @@ export function applyNativeOpenAiContextOverride(entry: RawEntry, limits?: Nativ
   }
   // providerContextCaps.openai is a ceiling for native OpenAI rows regardless of where the
   // advertised window came from (#1430): preserved rows without a hardcoded override (e.g.
-  // gpt-5.4-mini) must stay under the cap too, and auto-compaction follows the capped window.
+  // gpt-5.3-codex-spark) must stay under the cap too, and auto-compaction follows the capped
+  // window.
   // The per-model window narrows the same rows for the same reason.
   const currentContext = typeof entry.context_window === "number" ? entry.context_window : undefined;
   const cappedContext = narrowNativeMaxContextWindow(nativeSlug, currentContext, limits);