@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/chatgpt/app-server-shim/gate-rewrite.ts

@@ -0,0 +1,99 @@
+/** Plain-quota gate rewriting; usage display and non-quota restrictions are preserved. */
+const PLAIN_QUOTA_REACHED_TYPE = "rate_limit_reached";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasNonQuotaBlock(node: unknown): boolean {
+  if (Array.isArray(node)) return node.some(hasNonQuotaBlock);
+  if (!isRecord(node)) return false;
+  if (node.spendControlReached !== undefined && node.spendControlReached !== null && node.spendControlReached !== false) return true;
+  if (isRecord(node.spend_control) && node.spend_control.reached === true) return true;
+  const reached = node.rate_limit_reached_type;
+  if (isRecord(reached) && typeof reached.type === "string" && reached.type !== PLAIN_QUOTA_REACHED_TYPE) return true;
+  const rpcReached = node.rateLimitReachedType;
+  const rpcType = typeof rpcReached === "string" ? rpcReached : isRecord(rpcReached) ? rpcReached.type : undefined;
+  if (typeof rpcType === "string" && rpcType !== PLAIN_QUOTA_REACHED_TYPE) return true;
+  return Object.values(node).some(hasNonQuotaBlock);
+}
+
+export function unlockRateLimitGate(value: unknown): boolean {
+  let changed = false;
+  const payloadBlocked = hasNonQuotaBlock(value);
+  // A subtree shows the plain quota as the reason when a plain-quota reached type was removed in
+  // it or a usage window reads 100%; it stays "blocked" when a non-quota reason (workspace or
+  // credit reached type, spend control) is still standing in it.
+  const visit = (node: unknown): { cleared: boolean; exhausted: boolean; blocked: boolean } => {
+    let cleared = false;
+    let exhausted = false;
+    let blocked = false;
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        const r = visit(item);
+        cleared ||= r.cleared;
+        exhausted ||= r.exhausted;
+        blocked ||= r.blocked;
+      }
+      return { cleared, exhausted, blocked };
+    }
+    if (!isRecord(node)) return { cleared, exhausted, blocked };
+    if (typeof node.usedPercent === "number" && node.usedPercent >= 100) exhausted = true;
+    if (node.spendControlReached !== undefined && node.spendControlReached !== null && node.spendControlReached !== false) blocked = true;
+    if (isRecord(node.spend_control) && node.spend_control.reached === true) blocked = true;
+    const reachedType = node.rate_limit_reached_type;
+    if (isRecord(reachedType) && reachedType.type === PLAIN_QUOTA_REACHED_TYPE) {
+      delete node.rate_limit_reached_type;
+      changed = true;
+      cleared = true;
+    } else if (isRecord(reachedType) && typeof reachedType.type === "string") {
+      blocked = true;
+    }
+    // The app-server's JSON-RPC spelling of the same field: a nullable string.
+    const rpcReached = node.rateLimitReachedType;
+    const rpcType = typeof rpcReached === "string" ? rpcReached : isRecord(rpcReached) ? rpcReached.type : undefined;
+    if (rpcType === PLAIN_QUOTA_REACHED_TYPE) {
+      node.rateLimitReachedType = null;
+      changed = true;
+      cleared = true;
+    } else if (typeof rpcType === "string") {
+      blocked = true;
+    }
+    for (const child of Object.values(node)) {
+      const r = visit(child);
+      cleared ||= r.cleared;
+      exhausted ||= r.exhausted;
+      blocked ||= r.blocked;
+    }
+    // The rate-limit flags are opened only when the plain quota is the visible reason in this
+    // subtree and no workspace, credit or spend-control reason stands anywhere in the payload.
+    // A flag closed for a reason the payload does not show stays as the server sent it.
+    const plainQuotaShown = (cleared || exhausted) && !blocked && !payloadBlocked;
+    if (plainQuotaShown) {
+      for (const key of ["rate_limit", "rateLimit"] as const) {
+        const rateLimit = node[key];
+        if (!isRecord(rateLimit)) continue;
+        if (rateLimit.allowed === false) {
+          rateLimit.allowed = true;
+          changed = true;
+        }
+        for (const limitKey of ["limit_reached", "limitReached"] as const) {
+          if (rateLimit[limitKey] === true) {
+            rateLimit[limitKey] = false;
+            changed = true;
+          }
+        }
+      }
+    }
+    // `ordinaryUsageAllowed: false` is the same quota gate seen from the RPC side, and the only
+    // field the app reads for it. Open it only when the plain quota is the visible reason and
+    // nothing else still explains the block.
+    if (node.ordinaryUsageAllowed === false && plainQuotaShown) {
+      node.ordinaryUsageAllowed = true;
+      changed = true;
+    }
+    return { cleared, exhausted, blocked };
+  };
+  visit(value);
+  return changed;
+}

package/src/chatgpt/app-server-shim/launcher.ts

@@ -0,0 +1,91 @@
+import { accessSync, chmodSync, constants, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join, posix } from "node:path";
+import { getConfigDir } from "../../config/paths";
+import { selfLaunchArgv } from "../../lib/self-launch-argv";
+
+export const CHATGPT_APP_CODEX_BINARY = "/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex";
+
+/**
+ * Where the app-server binary sits inside a ChatGPT bundle, newest layout first. The bundle root
+ * is discovered by identity (com.openai.codex), so an install in ~/Applications or on another
+ * volume resolves to its own binary instead of the conventional /Applications path.
+ */
+const BUNDLED_CODEX_LAYOUTS: readonly (readonly string[])[] = [
+  ["Contents", "Resources", "codex-cli", "CodexCLI.app", "Contents", "MacOS", "codex"],
+  ["Contents", "Resources", "codex"],
+];
+
+function isExecutableFile(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The bundled app-server binary of a verified bundle root, or null when the bundle has none. */
+export function resolveChatgptCodexBinary(
+  bundleRoot: string,
+  isExecutable: (path: string) => boolean = isExecutableFile,
+): string | null {
+  for (const layout of BUNDLED_CODEX_LAYOUTS) {
+    const candidate = posix.join(bundleRoot, ...layout); // macOS bundle paths are POSIX on every host
+    if (isExecutable(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function chatgptShimLauncherPath(configDir = getConfigDir()): string {
+  return join(configDir, "chatgpt-codex-shim.sh");
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * A failed precondition or a failed self-test runs the original binary with untouched stdout.
+ * A filter that passes the self-test and then dies mid-session closes the pipe.
+ * Expected (not yet validated against the bundled app-server): the server gets SIGPIPE or a
+ * write error and Desktop respawns it through the same launcher.
+ */
+export function buildChatgptShimLauncher(argv: readonly string[], real = CHATGPT_APP_CODEX_BINARY): string {
+  return `#!/bin/bash
+# opencodex (experimental): ChatGPT app-server stdout passes through the quota-gate filter.
+REAL=${shellQuote(real)}
+FILTER=(${argv.map(shellQuote).join(" ")})
+if [ ! -x "$REAL" ]; then
+  echo "opencodex (experimental): the bundled app-server is no longer at $REAL; run 'ocx chatgpt launch' again or 'ocx chatgpt restore'." >&2
+  exit 127
+fi
+if [ "$(uname -s)" = "Darwin" ] && [ -x "\${FILTER[0]}" ] \\
+   && "\${FILTER[@]}" --self-test >/dev/null 2>&1; then
+  exec "$REAL" "$@" > >(exec "\${FILTER[@]}")
+fi
+exec "$REAL" "$@"
+`;
+}
+
+/**
+ * Written to a fresh temp file (exclusive create, never through a link) and renamed over the
+ * launcher, so an existing symbolic link is replaced rather than followed and a respawn during
+ * the write never runs a half-written script.
+ */
+export function writeChatgptShimLauncher(configDir = getConfigDir(), real = CHATGPT_APP_CODEX_BINARY): string {
+  mkdirSync(configDir, { recursive: true });
+  const path = chatgptShimLauncherPath(configDir);
+  const argv = [process.execPath, ...selfLaunchArgv(["internal", "chatgpt-app-server-filter"])];
+  const temp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync(temp, buildChatgptShimLauncher(argv, real), { mode: 0o755, flag: "wx" });
+    chmodSync(temp, 0o755);
+    renameSync(temp, path);
+  } catch (error) {
+    try { unlinkSync(temp); } catch { /* the temp file was never created */ }
+    throw error;
+  }
+  return path;
+}

package/src/claude/desktop-3p-startup.ts

@@ -0,0 +1,62 @@
+/**
+ * One build of the Desktop 3P alias registry from the startup discovery inputs.
+ *
+ * Startup builds the registry asynchronously so a slow provider cannot hold the proxy closed. A
+ * consumer that needs decodable aliases before that build finishes — the Claude Code CLI picker,
+ * whose catalog the CLI then caches for an hour — awaits the same in-flight build instead of
+ * starting a second one, or starts it when none ran. Inputs match `/v1/models` (entitlement-admitted
+ * native slugs plus catalog-visible routes), so both paths install the same registry.
+ */
+import type { OcxConfig } from "../types";
+import { buildDesktop3pRegistry, desktop3pRegistrySize } from "./desktop-3p";
+
+let pending: Promise<boolean> | null = null;
+let lastUnproductiveAt = -Infinity;
+/** After a build fails or installs nothing, on-demand callers wait this long before retrying. */
+export const DESKTOP_3P_REGISTRY_RETRY_MS = 30_000;
+
+/** Build and install the registry; concurrent callers share one build. Resolves false on failure. */
+export function initDesktop3pRegistry(config: OcxConfig): Promise<boolean> {
+  pending ??= (async () => {
+    try {
+      const { fetchAllModels } = await import("../server/management-api");
+      const { desktopVisibleNativeSlugs } = await import("../codex/catalog");
+      const { resolveAdmittedCodexModelEntitlements } = await import("../codex/model-entitlement-admission");
+      const { buildDesktopDiscoveryInputs } = await import("./desktop-discovery-inputs");
+      const [models, modelEntitlements] = await Promise.all([
+        fetchAllModels(config),
+        resolveAdmittedCodexModelEntitlements(config, { clientVersion: null }),
+      ]);
+      const inputs = buildDesktopDiscoveryInputs({
+        config, models, modelEntitlements,
+        desktopNativeCandidates: desktopVisibleNativeSlugs(config),
+      });
+      buildDesktop3pRegistry(inputs.nativeSlugs, inputs.routedModels, config.claudeCode?.desktopProfile, inputs.nativeContextCap);
+      if (desktop3pRegistrySize() === 0) lastUnproductiveAt = Date.now();
+      return true;
+    } catch {
+      lastUnproductiveAt = Date.now();
+      // Best-effort; model discovery can rebuild it. Never reflect credential or provider errors.
+      console.warn("[opencodex] Claude Desktop model registry could not be initialized.");
+      return false;
+    } finally {
+      pending = null;
+    }
+  })();
+  return pending;
+}
+
+/**
+ * Resolve once a build has installed the registry, starting one only when none ran or is running.
+ * A failed or empty build is not retried on demand until the cooldown passes, so a broken provider
+ * cannot turn every CLI catalog request into a fresh discovery and entitlement round.
+ */
+export async function ensureDesktop3pRegistry(readConfig: () => OcxConfig, now: () => number = Date.now): Promise<void> {
+  if (pending) {
+    await pending;
+    return;
+  }
+  if (desktop3pRegistrySize() > 0) return;
+  if (now() - lastUnproductiveAt < DESKTOP_3P_REGISTRY_RETRY_MS) return;
+  await initDesktop3pRegistry(readConfig());
+}

package/src/claude/desktop-3p.ts

@@ -334,6 +334,11 @@ export function resolveDesktop3pAlias(alias: string): string | null {
   return desktop3pRegistry.get(alias) ?? null;
 }
 
+/** Number of decodable aliases in the installed registry (0 before the first build). */
+export function desktop3pRegistrySize(): number {
+  return desktop3pRegistry.size;
+}
+
 /** Exact registered and identity-preserving catalog IDs precede synthetic syntax. */
 export function isKnownDesktop3pModelId(id: string): boolean {
   return desktop3pRegistry.has(id) || desktop3pRealAnthropicIds.has(id);

package/src/claude/first-party-settings.ts

@@ -11,6 +11,7 @@ import {
   type DesktopFirstPartyOptions,
 } from "./desktop-first-party";
 import { claudeInterceptCaCertPath } from "./intercept/local-ca";
+import { invalidateClaudeCodeServedCatalog } from "./intercept/cli-catalog";
 import { claudeInterceptEnabled } from "./intercept/runtime";
 import { isClaudeInterceptProxyUrl, removeClaudeInterceptSettings, type ClaudeInterceptSettingsState } from "./intercept/settings";
 
@@ -44,6 +45,19 @@ export function reconcileClaudeFirstPartySettings(
   config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole" | "clientIntegrations">,
   desired: ClaudeFirstPartyDesired,
   options: DesktopFirstPartyOptions = {},
+): ClaudeFirstPartyReconcileResult {
+  const result = reconcileSettingsEnv(config, desired, options);
+  // CLI intent can change without the shared env changing (Desktop already holds it), and the
+  // proxy only adds opencodex rows to the CLI's /model catalog while that intent is on. Drop the
+  // CLI's cached catalog on every successful reconcile so its next launch refetches the list.
+  if (result.ok) invalidateClaudeCodeServedCatalog(options.claudeConfigDir ?? claudeConfigDir());
+  return result;
+}
+
+function reconcileSettingsEnv(
+  config: Pick<OcxConfig, "claudeCode" | "port" | "runtimeRole" | "clientIntegrations">,
+  desired: ClaudeFirstPartyDesired,
+  options: DesktopFirstPartyOptions,
 ): ClaudeFirstPartyReconcileResult {
   if (!desired.desktop && !desired.cli) {
     const ownedCa = claudeInterceptCaCertPath(options.opencodexConfigDir ?? getConfigDir());

package/src/claude/intercept/cli-catalog.ts

@@ -0,0 +1,150 @@
+/**
+ * Claude Code CLI first-party picker: rewrite the catalogs the standalone CLI builds `/model` from.
+ *
+ * A first-party `claude` reads its picker from `GET /api/organizations/<org>/model_selector/cc` (or
+ * `/api/model_selector/cc` without an org scope): the same row shape as Desktop's bootstrap, on the
+ * `cc` surface. When that served catalog is off, the CLI falls back to its compiled list plus
+ * `additional_model_options` from `GET /api/claude_cli/bootstrap`. Both arrive on the intercepted
+ * api.anthropic.com tunnel; this module decides which may be rewritten and merges opencodex rows in.
+ * Every failure returns the upstream bytes unchanged.
+ *
+ * The CLI only offers Claude-shaped ids (an `ocx-claude-*` row renders "Update Claude Code"), so the
+ * rows carry Desktop 3P registry aliases; `buildCliPickerModels` in picker-models.ts chooses them.
+ * Import-light on purpose: the TLS listener loads this file.
+ */
+import { readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import type { ClaudeFirstPartyDesired } from "../first-party-settings";
+import { classifyInterceptClient } from "./client-class";
+import { BOOTSTRAP_MAX_DECODED_BYTES, injectPickerModels, type PickerModelEntry } from "./picker-bootstrap";
+
+export type CliCatalogKind = "model_selector" | "bootstrap";
+
+/** The CLI's own picker surface. Desktop's `ccd`/`code` surfaces belong to picker mode. */
+export const CLI_PICKER_SURFACE_IDS = ["cc"] as const;
+/** Template notices describe the Anthropic model a row was cloned from, never the routed one. */
+const CLI_EXTRA_STRIPPED_KEYS = ["notice", "selection_notice"] as const;
+const MODEL_SELECTOR_PATH = /^\/api\/(?:organizations\/[^/]+\/)?model_selector\/cc\/?$/;
+const BOOTSTRAP_PATH = /^\/api\/claude_cli\/bootstrap\/?$/;
+const REWRITE_DROPPED_HEADERS = ["content-length", "content-encoding", "etag", "digest", "content-md5", "transfer-encoding"];
+
+export function cliCatalogKind(method: string, pathname: string): CliCatalogKind | null {
+  if (method !== "GET") return null;
+  if (MODEL_SELECTOR_PATH.test(pathname)) return "model_selector";
+  if (BOOTSTRAP_PATH.test(pathname)) return "bootstrap";
+  return null;
+}
+
+/**
+ * Whether this request's catalog may carry opencodex rows. The cc catalog is cached on disk and
+ * shared by every Claude Code process, so only a CLI-classified client with CLI first-party on gets
+ * rows (a Desktop-spawned process would otherwise seed rows a plain `claude` cannot route). The
+ * bootstrap request carries a bare `claude-code/<v>` User-Agent with no entrypoint, so it follows
+ * CLI intent alone. Like the Messages split, the User-Agent is a routing hint, not a trust boundary.
+ */
+export function cliCatalogEligible(kind: CliCatalogKind, userAgent: string | null, desired: ClaudeFirstPartyDesired): boolean {
+  if (!desired.cli) return false;
+  if (kind === "bootstrap") return true;
+  return classifyInterceptClient(userAgent) === "cli";
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+/** Append rows to `additional_model_options` (`{model, name, description}`), skipping ids already present. */
+export function injectCliBootstrapOptions(bootstrap: unknown, models: readonly PickerModelEntry[]): number {
+  const body = record(bootstrap);
+  if (!body) return 0;
+  const current = body.additional_model_options;
+  if (current !== undefined && current !== null && !Array.isArray(current)) return 0;
+  const options = Array.isArray(current) ? current : [];
+  const existing = new Set(options.map(option => record(option)?.model));
+  let added = 0;
+  for (const model of models) {
+    if (existing.has(model.id)) continue;
+    options.push({ model: model.id, name: model.name, description: model.description ?? "" });
+    existing.add(model.id);
+    added++;
+  }
+  if (added > 0) body.additional_model_options = options;
+  return added;
+}
+
+/** Rewrite a decoded catalog body; `null` when nothing was added or the body is not the expected shape. */
+export function rewriteCliCatalogBody(kind: CliCatalogKind, text: string, models: readonly PickerModelEntry[]): string | null {
+  if (models.length === 0) return null;
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { return null; }
+  const added = kind === "bootstrap"
+    ? injectCliBootstrapOptions(parsed, models)
+    : injectPickerModels(parsed, models, undefined, { surfaces: CLI_PICKER_SURFACE_IDS, extraStrippedKeys: CLI_EXTRA_STRIPPED_KEYS });
+  return added > 0 ? JSON.stringify(parsed) : null;
+}
+
+/** Read at most `cap` bytes; null (and the stream cancelled) once the body would exceed it. */
+async function readCapped(body: ReadableStream<Uint8Array>, cap: number): Promise<Uint8Array<ArrayBuffer> | null> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > cap) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  return bytes;
+}
+
+/**
+ * Rewrite a relayed catalog response. Only a 2xx JSON body under the decoded cap is touched; the
+ * relay already decoded any content-encoding (and dropped content-length), so the cap is enforced
+ * while streaming; an oversized catalog is answered with a gateway error rather than buffered.
+ */
+export async function rewriteCliCatalogResponse(
+  response: Response,
+  kind: CliCatalogKind,
+  models: readonly PickerModelEntry[],
+): Promise<Response> {
+  if (response.status < 200 || response.status >= 300 || models.length === 0) return response;
+  const declared = Number(response.headers.get("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > BOOTSTRAP_MAX_DECODED_BYTES) return response;
+  if (!response.body) return response;
+  const bytes = await readCapped(response.body, BOOTSTRAP_MAX_DECODED_BYTES);
+  if (bytes === null) {
+    return Response.json({ type: "error", error: { type: "api_error", message: "model catalog exceeded the intercept size cap" } }, { status: 502 });
+  }
+  const original = (): Response => new Response(bytes, { status: response.status, statusText: response.statusText, headers: response.headers });
+  const rewritten = rewriteCliCatalogBody(kind, new TextDecoder().decode(bytes), models);
+  if (rewritten === null) return original();
+  const headers = new Headers(response.headers);
+  for (const name of REWRITE_DROPPED_HEADERS) headers.delete(name);
+  headers.set("content-type", "application/json");
+  return new Response(rewritten, { status: response.status, statusText: response.statusText, headers });
+}
+
+/**
+ * Drop the CLI's cached served catalogs (`<claudeConfigDir>/cache/model-catalog/*-cc.json`). The CLI
+ * trusts a fresh copy for about an hour without refetching, so after first-party turns on or off the
+ * next launch would otherwise keep the previous list — opencodex rows that now go to Anthropic, or
+ * no rows at all. Desktop's `*-ccd.json` and failure markers are left alone. Best effort; returns the
+ * number of files removed.
+ */
+export function invalidateClaudeCodeServedCatalog(claudeDir: string): number {
+  const dir = join(claudeDir, "cache", "model-catalog");
+  let names: string[];
+  try { names = readdirSync(dir); } catch { return 0; } // no-excuse-ok: catch -- no cache directory means nothing to drop.
+  let removed = 0;
+  for (const name of names) {
+    if (!name.endsWith("-cc.json")) continue;
+    try { unlinkSync(join(dir, name)); removed++; } catch { /* A concurrent writer or removal wins; the next reconcile retries. */ }
+  }
+  return removed;
+}

package/src/claude/intercept/cli-picker.ts

@@ -0,0 +1,82 @@
+/**
+ * The Claude Code CLI picker's model source for the intercept listener's `cliCatalog` hook.
+ *
+ * Independent of Desktop picker mode: it needs only the intercept pair and CLI first-party intent.
+ * Discovery runs lazily, on the first eligible catalog request, and the result is persisted so a
+ * restart answers immediately. A cold start waits briefly for the Desktop 3P registry (the aliases
+ * must decode before they are advertised) and for one discovery; past that bound the catalog relays
+ * unchanged rather than holding the CLI's own request open.
+ */
+import { join } from "node:path";
+import type { OcxConfig } from "../../types";
+import { desktop3pRegistrySize } from "../desktop-3p";
+import type { ClaudeFirstPartyDesired } from "../first-party-settings";
+import { cliCatalogEligible, type CliCatalogKind } from "./cli-catalog";
+import { claudeInterceptStateDir } from "./local-ca";
+import type { PickerModelEntry } from "./picker-bootstrap";
+import { buildCliPickerModels, createPickerModelSnapshot, routableCliPickerModels, type PickerRouteInput } from "./picker-models";
+
+export const CLI_PICKER_MODELS_FILE = "cli-picker-models.json";
+export const CLI_PICKER_MODELS_MAX_AGE_MS = 5 * 60_000;
+/** The CLI times its catalog fetch out after a few seconds; a cold build must answer well inside it. */
+export const CLI_PICKER_COLD_WAIT_MS = 2_500;
+
+export interface CliCatalogProviderOptions {
+  configDir: string;
+  loadRoutes: () => Promise<PickerRouteInput>;
+  desiredClients: () => ClaudeFirstPartyDesired;
+  /** Resolves once Desktop 3P aliases decode; defaults to the shared startup build. */
+  ensureRegistry?: () => Promise<void>;
+  /** Whether the registry holds aliases; defaults to the installed Desktop 3P registry. */
+  registryReady?: () => boolean;
+  coldWaitMs?: number;
+}
+
+async function defaultEnsureRegistry(): Promise<void> {
+  const [{ ensureDesktop3pRegistry }, { loadConfig }] = await Promise.all([
+    import("../desktop-3p-startup"),
+    import("../../config"),
+  ]);
+  await ensureDesktop3pRegistry(loadConfig as () => OcxConfig);
+}
+
+export function createCliCatalogProvider(options: CliCatalogProviderOptions): (req: Request, kind: CliCatalogKind) => Promise<readonly PickerModelEntry[] | null> {
+  const ensureRegistry = options.ensureRegistry ?? defaultEnsureRegistry;
+  const registryReady = options.registryReady ?? (() => desktop3pRegistrySize() > 0);
+  const snapshot = createPickerModelSnapshot(async () => {
+    await ensureRegistry();
+    // A failed build resolves into its retry cooldown with an empty registry. Building rows then
+    // would persist an empty list over the last good snapshot, so fail the refresh instead and keep it.
+    if (!registryReady()) throw new Error("Desktop 3P registry unavailable");
+    return options.loadRoutes();
+  }, join(claudeInterceptStateDir(options.configDir), CLI_PICKER_MODELS_FILE), buildCliPickerModels);
+  const coldWaitMs = options.coldWaitMs ?? CLI_PICKER_COLD_WAIT_MS;
+  // Every wait in one request shares a single deadline, so the whole answer stays inside coldWaitMs.
+  const bounded = async (work: () => Promise<unknown>, deadline: number): Promise<void> => {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([work().catch(() => {}), new Promise<void>(resolve => { timer = setTimeout(resolve, remaining); })]);
+    clearTimeout(timer);
+  };
+  return async (req, kind) => {
+    if (!cliCatalogEligible(kind, req.headers.get("user-agent"), options.desiredClients())) return null;
+    const deadline = Date.now() + coldWaitMs;
+    if (snapshot.current() === null) {
+      await bounded(() => snapshot.refresh(), deadline);
+    } else {
+      snapshot.refreshIfStale(CLI_PICKER_MODELS_MAX_AGE_MS);
+    }
+    const current = snapshot.current();
+    if (!current) return null;
+    // A persisted snapshot can outlive the registry it was built against: a restart starts with an
+    // empty registry, and a provider change retires routes the snapshot still lists. An answer
+    // missing those rows is what the CLI would cache for the next hour, so first wait for the shared
+    // registry build, and if rows still do not decode, rebuild the snapshot from the current routes
+    // before answering, all within the request's one deadline.
+    const stale = (models: readonly PickerModelEntry[]): boolean => routableCliPickerModels(models).length < models.length;
+    if (stale(current.models)) await bounded(ensureRegistry, deadline);
+    if (stale(snapshot.current()!.models)) await bounded(() => snapshot.refresh(), deadline);
+    return routableCliPickerModels(snapshot.current()!.models);
+  };
+}

package/src/claude/intercept/listener.ts

@@ -1,5 +1,7 @@
 import type { Server } from "bun";
+import { cliCatalogKind, rewriteCliCatalogResponse, type CliCatalogKind } from "./cli-catalog";
 import type { PemKeyPair } from "./local-ca";
+import type { PickerModelEntry } from "./picker-bootstrap";
 
 /**
  * TLS listener that terminates intercepted `api.anthropic.com` tunnels.
@@ -9,7 +11,8 @@ import type { PemKeyPair } from "./local-ca";
  * handed to the router's own request handler, which already knows how to route mapped models
  * to providers and pass genuine Claude models through with the caller's subscription
  * credential. Every other path (usage, feedback, model listings, …) is relayed verbatim to
- * the real upstream so the client keeps behaving like a first-party install.
+ * the real upstream so the client keeps behaving like a first-party install. The one exception
+ * is the Claude Code CLI's own picker catalog, which `cliCatalog` may extend (cli-catalog.ts).
  */
 
 export const CLAUDE_INTERCEPT_UPSTREAM = "https://api.anthropic.com";
@@ -93,6 +96,11 @@ export interface ClaudeInterceptListenerOptions<T = undefined> {
   dispatch: (req: Request, server: Server<T>) => Promise<Response>;
   /** Per-request decision for every path; absent preserves the existing path split. */
   route?: (req: Request) => "router" | "relay-native";
+  /**
+   * Rows to merge into a relayed Claude Code CLI picker catalog, or null to relay it unchanged.
+   * Consulted for every catalog GET, including ones `route` sends to the native upstream.
+   */
+  cliCatalog?: (req: Request, kind: CliCatalogKind) => Promise<readonly PickerModelEntry[] | null>;
   upstreamBase?: string;
   maxRequestBodySize?: number;
   idleTimeout?: number;
@@ -113,13 +121,20 @@ export function startClaudeInterceptListener<T = undefined>(options: ClaudeInter
     ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}),
     async fetch(req, requestServer) {
       const url = new URL(req.url);
-      if (options.route?.(req) === "relay-native") {
-        return relayToUpstream(req, CLAUDE_INTERCEPT_UPSTREAM, options.fetchImpl);
-      }
-      if (isClaudeInterceptedPath(url.pathname, req.method)) {
+      const native = options.route?.(req) === "relay-native";
+      if (!native && isClaudeInterceptedPath(url.pathname, req.method)) {
         return options.dispatch(rewriteInterceptedRequest(req, loopbackOrigin), requestServer);
       }
-      return relayToUpstream(req, upstreamBase, options.fetchImpl);
+      const upstream = native ? CLAUDE_INTERCEPT_UPSTREAM : upstreamBase;
+      const catalog = options.cliCatalog ? cliCatalogKind(req.method, url.pathname) : null;
+      if (catalog) {
+        let models: readonly PickerModelEntry[] | null = null;
+        try { models = await options.cliCatalog!(req, catalog); } catch { /* Fail open: relay unchanged. */ }
+        if (models && models.length > 0) {
+          return rewriteCliCatalogResponse(await relayToUpstream(req, upstream, options.fetchImpl), catalog, models);
+        }
+      }
+      return relayToUpstream(req, upstream, options.fetchImpl);
     },
   });
   loopbackOrigin = `http://127.0.0.1:${server.port}`;

package/src/claude/intercept/picker-bootstrap.ts

@@ -9,6 +9,10 @@ export interface PickerModelEntry {
   id: string;
   name: string;
   contextWindow?: number;
+  /** Row description; Desktop entries never carry one, so their rows keep the stripped template. */
+  description?: string;
+  /** The route an alias was minted for (CLI rows), so a later registry rebuild can be re-checked. */
+  route?: string;
 }
 
 export const BOOTSTRAP_MAX_ENCODED_BYTES = 4 * 1024 * 1024;
@@ -44,8 +48,19 @@ export type PickerInjectionOutcome =
 export const PICKER_SURFACE_IDS = ["ccd", "code"] as const;
 /** Surface names the log may print; anything else from the body is counted, never echoed. */
 const KNOWN_SURFACE_IDS = new Set(["ccd", "code", "cc", "ccr", "cowork", "chat", "design"]);
+const TEMPLATE_STRIPPED_KEYS = ["disabled", "disabled_reason", "badge", "tooltip", "description", "fast_mode"];
 
-function injectIntoSurface(surface: Record<string, unknown>, models: readonly PickerModelEntry[]): number | string {
+/** Which surfaces to rewrite and which extra template keys to drop; the defaults are Desktop's. */
+export interface PickerInjectionOptions {
+  surfaces?: readonly string[];
+  extraStrippedKeys?: readonly string[];
+}
+
+function injectIntoSurface(
+  surface: Record<string, unknown>,
+  models: readonly PickerModelEntry[],
+  stripped: readonly string[],
+): number | string {
   if (!Array.isArray(surface.models)) return "no_models";
   const entries = surface.models as unknown[];
   const template = entries.map(record).find(entry =>
@@ -63,9 +78,9 @@ function injectIntoSurface(surface: Record<string, unknown>, models: readonly Pi
     if (model.contextWindow === undefined) delete copy.context_window;
     else copy.context_window = model.contextWindow;
     for (const key of Object.keys(copy)) {
-      if (["disabled", "disabled_reason", "badge", "tooltip", "description", "fast_mode"].includes(key)
-        || /version/i.test(key)) delete copy[key];
+      if (stripped.includes(key) || /version/i.test(key)) delete copy[key];
     }
+    if (model.description !== undefined) copy.description = model.description;
     entries.push(copy);
     existing.add(model.id);
     added++;
@@ -77,13 +92,16 @@ export function injectPickerModels(
   bootstrap: unknown,
   models: readonly PickerModelEntry[],
   explain?: (outcome: PickerInjectionOutcome) => void,
+  options: PickerInjectionOptions = {},
 ): number {
   const unchanged = (reason: string): number => { explain?.({ kind: "unchanged", reason }); return 0; };
   const surfaces = record(bootstrap)?.model_selector_config;
   if (!Array.isArray(surfaces)) return unchanged("no_model_selector_config");
   const rows = surfaces.map(record);
+  const surfaceIds: readonly unknown[] = options.surfaces ?? PICKER_SURFACE_IDS;
+  const stripped = [...TEMPLATE_STRIPPED_KEYS, ...(options.extraStrippedKeys ?? [])];
   const targets = rows.filter((entry): entry is Record<string, unknown> =>
-    entry !== null && (PICKER_SURFACE_IDS as readonly unknown[]).includes(entry.id));
+    entry !== null && surfaceIds.includes(entry.id));
   if (targets.length === 0) {
     // Only known surface names reach the log; any other body-derived value is counted.
     const known = rows.flatMap(entry => typeof entry?.id === "string" && KNOWN_SURFACE_IDS.has(entry.id) ? [entry.id] : []);
@@ -93,7 +111,7 @@ export function injectPickerModels(
   let added = 0;
   const skipped: string[] = [];
   for (const surface of targets) {
-    const result = injectIntoSurface(surface, models);
+    const result = injectIntoSurface(surface, models, stripped);
     if (typeof result === "number") added += result;
     else skipped.push(`${String(surface.id)}:${result}`);
   }