@bitkyc08/opencodex 2.64.0 → 2.65.0-preview.20260925

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

@@ -0,0 +1,141 @@
+/**
+ * Claude Desktop picker mode: narrowly rewrite the Code bootstrap catalog.
+ * A failed or inapplicable transform leaves the upstream bytes untouched.
+ */
+import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
+
+/** One opencodex model offered in Desktop's Code-tab picker. */
+export interface PickerModelEntry {
+  id: string;
+  name: string;
+  contextWindow?: number;
+}
+
+export const BOOTSTRAP_MAX_ENCODED_BYTES = 4 * 1024 * 1024;
+export const BOOTSTRAP_MAX_DECODED_BYTES = 16 * 1024 * 1024;
+const BOOTSTRAP_PATH = /^\/(?:edge-api|api)\/bootstrap(?:\/[A-Za-z0-9-]+\/app_start)?\/?$/;
+const REWRITE_REMOVED_HEADERS = new Set([
+  "content-encoding", "content-length", "etag", "digest", "content-md5", "transfer-encoding",
+]);
+
+export function isPickerBootstrapRequest(method: string, pathname: string): boolean {
+  return method === "GET" && BOOTSTRAP_PATH.test(pathname);
+}
+
+export function narrowBootstrapAcceptEncoding(): string {
+  return "gzip, deflate, br";
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : null;
+}
+
+/** Why a bootstrap was left unchanged, for the metadata-only picker log. Never carries values. */
+export type PickerInjectionOutcome =
+  | { kind: "rewritten"; added: number }
+  | { kind: "unchanged"; reason: string };
+
+/**
+ * Surfaces whose picker the local Desktop Code tab can show. Desktop reads "ccd" and falls back to
+ * "code" only when "ccd" carries no catalog; "ccr" (remote sessions) is left alone because a
+ * remote session never reaches this machine's proxy, so an opencodex route could not run there.
+ */
+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"]);
+
+function injectIntoSurface(surface: Record<string, unknown>, models: readonly PickerModelEntry[]): number | string {
+  if (!Array.isArray(surface.models)) return "no_models";
+  const entries = surface.models as unknown[];
+  const template = entries.map(record).find(entry =>
+    typeof entry?.id === "string" && entry.id.startsWith("claude-")
+    && !entry.disabled && !entry.disabled_reason && entry.section !== "deprecated");
+  if (!template) return `no_template(models=${entries.length})`;
+  const existing = new Set(entries.map(record).map(entry => entry?.id));
+  let added = 0;
+  for (const model of models) {
+    if (existing.has(model.id)) continue;
+    const copy = structuredClone(template);
+    copy.id = model.id;
+    copy.name = model.name;
+    copy.section = "main";
+    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];
+    }
+    entries.push(copy);
+    existing.add(model.id);
+    added++;
+  }
+  return added;
+}
+
+export function injectPickerModels(
+  bootstrap: unknown,
+  models: readonly PickerModelEntry[],
+  explain?: (outcome: PickerInjectionOutcome) => void,
+): 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 targets = rows.filter((entry): entry is Record<string, unknown> =>
+    entry !== null && (PICKER_SURFACE_IDS as readonly unknown[]).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] : []);
+    const other = rows.length - known.length;
+    return unchanged(`no_code_surface(${[...known, ...(other > 0 ? [`other:${other}`] : [])].join(",")})`);
+  }
+  let added = 0;
+  const skipped: string[] = [];
+  for (const surface of targets) {
+    const result = injectIntoSurface(surface, models);
+    if (typeof result === "number") added += result;
+    else skipped.push(`${String(surface.id)}:${result}`);
+  }
+  if (added === 0) return unchanged(skipped.length > 0 ? skipped.join(";") : models.length === 0 ? "no_routes" : "all_present");
+  explain?.({ kind: "rewritten", added });
+  return added;
+}
+
+export function rewriteBootstrapBody(
+  encoded: Buffer,
+  contentEncoding: string | undefined,
+  models: readonly PickerModelEntry[],
+  explain?: (outcome: PickerInjectionOutcome) => void,
+): Buffer | null {
+  const unchanged = (reason: string): null => { explain?.({ kind: "unchanged", reason }); return null; };
+  if (encoded.length > BOOTSTRAP_MAX_ENCODED_BYTES) return unchanged("encoded_cap");
+  const encoding = contentEncoding?.trim().toLowerCase() || "identity";
+  let decoded: Buffer;
+  try {
+    switch (encoding) {
+      case "identity": decoded = encoded; break;
+      case "gzip":
+      case "x-gzip": decoded = gunzipSync(encoded, { maxOutputLength: BOOTSTRAP_MAX_DECODED_BYTES }); break;
+      case "deflate": decoded = inflateSync(encoded, { maxOutputLength: BOOTSTRAP_MAX_DECODED_BYTES }); break;
+      case "br": decoded = brotliDecompressSync(encoded, { maxOutputLength: BOOTSTRAP_MAX_DECODED_BYTES }); break;
+      default: return unchanged("unsupported_encoding");
+    }
+    if (decoded.length > BOOTSTRAP_MAX_DECODED_BYTES) return unchanged("decoded_cap");
+    const parsed: unknown = JSON.parse(decoded.toString("utf8"));
+    if (injectPickerModels(parsed, models, explain) === 0) return null;
+    return Buffer.from(JSON.stringify(parsed), "utf8");
+  } catch {
+    return unchanged("decode_or_parse_failed");
+  }
+}
+
+/** Rewritten payloads are identity encoded, so stale validators and sizes must go. */
+export function rewrittenHeaders(raw: readonly string[], bodyLength: number): string[] {
+  const result: string[] = [];
+  for (let i = 0; i + 1 < raw.length; i += 2) {
+    if (!REWRITE_REMOVED_HEADERS.has(raw[i]!.toLowerCase())) result.push(raw[i]!, raw[i + 1]!);
+  }
+  result.push("Content-Length", String(bodyLength));
+  return result;
+}

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

@@ -0,0 +1,126 @@
+import { createHash, X509Certificate } from "node:crypto";
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ALL_IP_ADDRESS_BASES,
+  ensurePersistedAuthority,
+  issueServerLeaf,
+  type LocalInterceptCa,
+  type PemKeyPair,
+} from "./local-ca";
+
+/** Separate root for Desktop traffic: its critical DNS constraint is checked on every reload. */
+export const PICKER_HOST = "claude.ai";
+export const PICKER_CA_COMMON_NAME = "opencodex Claude Desktop Picker CA";
+export const PICKER_STATE_DIR = "claude-picker";
+
+export interface PickerCa extends LocalInterceptCa { fingerprint: string }
+
+export function pickerStateDir(configDir: string): string { return join(configDir, PICKER_STATE_DIR); }
+export function pickerCaCertPath(configDir: string): string { return join(pickerStateDir(configDir), "ca.pem"); }
+export function pickerLeafCertPath(configDir: string): string { return join(pickerStateDir(configDir), "leaf.pem"); }
+
+export function pickerCaFingerprints(certPem: string): { sha1: string; sha256: string } {
+  const der = new X509Certificate(certPem).raw;
+  return {
+    sha1: createHash("sha1").update(der).digest("hex").toUpperCase(),
+    sha256: createHash("sha256").update(der).digest("hex").toUpperCase(),
+  };
+}
+
+interface DerItem { tag: number; body: Buffer; next: number }
+
+function readDer(bytes: Buffer, at: number): DerItem | null {
+  if (at + 2 > bytes.length) return null;
+  const tag = bytes[at]!;
+  let length = bytes[at + 1]!;
+  let cursor = at + 2;
+  if (length & 0x80) {
+    const width = length & 0x7f;
+    if (width === 0 || width > 4 || cursor + width > bytes.length) return null;
+    length = 0;
+    for (let i = 0; i < width; i++) length = length * 256 + bytes[cursor++]!;
+  }
+  if (cursor + length > bytes.length) return null;
+  return { tag, body: bytes.subarray(cursor, cursor + length), next: cursor + length };
+}
+
+function children(bytes: Buffer): DerItem[] | null {
+  const out: DerItem[] = [];
+  for (let cursor = 0; cursor < bytes.length;) {
+    const item = readDer(bytes, cursor);
+    if (!item) return null;
+    out.push(item);
+    cursor = item.next;
+  }
+  return out;
+}
+
+function constrainedToPickerHost(value: Buffer): boolean {
+  const root = readDer(value, 0);
+  if (!root || root.tag !== 0x30 || root.next !== value.length) return false;
+  const fields = children(root.body);
+  // permittedSubtrees [0] with exactly claude.ai, excludedSubtrees [1] with every IPv4 and IPv6 address.
+  if (!fields || fields.length !== 2 || fields[0]!.tag !== 0xa0 || fields[1]!.tag !== 0xa1) return false;
+  const excluded = children(fields[1]!.body);
+  if (!excluded || excluded.length !== ALL_IP_ADDRESS_BASES.length) return false;
+  const excludesAllIps = excluded.every((subtree, index) => {
+    if (subtree.tag !== 0x30) return false;
+    const base = children(subtree.body);
+    return !!base && base.length === 1 && base[0]!.tag === 0x87
+      && base[0]!.body.equals(Buffer.from(ALL_IP_ADDRESS_BASES[index]!));
+  });
+  if (!excludesAllIps) return false;
+  const subtrees = children(fields[0]!.body);
+  if (!subtrees || subtrees.length !== 1 || subtrees[0]!.tag !== 0x30) return false;
+  const subtree = children(subtrees[0]!.body);
+  return !!subtree && subtree.length === 1 && subtree[0]!.tag === 0x82
+    && subtree[0]!.body.equals(Buffer.from(PICKER_HOST, "ascii"));
+}
+
+/** Inspect the extension itself; X509Certificate does not expose nameConstraints. */
+function acceptsPickerAuthority(cert: X509Certificate): boolean {
+  if (!cert.subject.split("\n").includes(`CN=${PICKER_CA_COMMON_NAME}`)) return false;
+  const root = readDer(cert.raw, 0);
+  if (!root || root.tag !== 0x30 || root.next !== cert.raw.length) return false;
+  const certificate = children(root.body);
+  if (!certificate || certificate[0]?.tag !== 0x30) return false;
+  const tbs = children(certificate[0].body);
+  const extensionField = tbs?.find(item => item.tag === 0xa3);
+  const wrapped = extensionField && readDer(extensionField.body, 0);
+  if (!wrapped || wrapped.tag !== 0x30 || wrapped.next !== extensionField!.body.length) return false;
+  const extensions = children(wrapped.body);
+  if (!extensions) return false;
+  const matches = extensions.filter(item => {
+    if (item.tag !== 0x30) return false;
+    const fields = children(item.body);
+    return fields?.[0]?.tag === 0x06 && fields[0].body.equals(Buffer.from([0x55, 0x1d, 0x1e]));
+  });
+  if (matches.length !== 1) return false;
+  const fields = children(matches[0]!.body);
+  return !!fields && fields.length === 3
+    && fields[1]!.tag === 0x01 && fields[1]!.body.equals(Buffer.from([0xff]))
+    && fields[2]!.tag === 0x04 && constrainedToPickerHost(fields[2]!.body);
+}
+
+export function ensurePickerCa(configDir: string): PickerCa {
+  const ca = ensurePersistedAuthority(
+    pickerStateDir(configDir),
+    { commonName: PICKER_CA_COMMON_NAME, permittedDnsNames: [PICKER_HOST] },
+    "ca-publication.sqlite",
+    acceptsPickerAuthority,
+  );
+  return { ...ca, fingerprint: pickerCaFingerprints(ca.certPem).sha256 };
+}
+
+/** Persist only the public leaf, so trust inspection verifies this exact local issuer. */
+export function issuePickerLeaf(ca: PickerCa, configDir: string): PemKeyPair {
+  const leaf = issueServerLeaf(ca, PICKER_CA_COMMON_NAME, [PICKER_HOST]);
+  const path = pickerLeafCertPath(configDir);
+  mkdirSync(pickerStateDir(configDir), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, leaf.certPem, { mode: 0o644 });
+  try { chmodSync(tmp, 0o644); } catch { /* best-effort on platforms without POSIX modes */ }
+  renameSync(tmp, path);
+  return leaf;
+}

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

@@ -0,0 +1,213 @@
+/**
+ * HTTP/1.1 TLS terminator for claude.ai. Only the bounded bootstrap response is
+ * held; all other HTTP bodies and upgraded sockets relay as streams.
+ */
+import { createServer, request as httpsRequest } from "node:https";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { connect as tlsConnect } from "node:tls";
+import type { Duplex } from "node:stream";
+import type { PemKeyPair } from "./local-ca";
+import {
+  BOOTSTRAP_MAX_ENCODED_BYTES, isPickerBootstrapRequest, narrowBootstrapAcceptEncoding,
+  rewriteBootstrapBody, rewrittenHeaders,
+} from "./picker-bootstrap";
+import type { PickerModelEntry } from "./picker-bootstrap";
+
+export interface PickerListenerOptions {
+  leaf: PemKeyPair;
+  models: () => readonly PickerModelEntry[];
+  upstream?: { host: string; port: number; servername: string; ca?: string };
+  /** Test seam: encoded bootstrap cap; production uses BOOTSTRAP_MAX_ENCODED_BYTES. */
+  maxEncodedBytes?: number;
+  log?: (line: string) => void;
+}
+export interface PickerListenerHandle { port: number; close(): Promise<void> }
+
+const HOP_HEADERS = new Set([
+  "connection", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization",
+  "te", "trailer", "transfer-encoding", "upgrade",
+]);
+
+function filteredHeaders(raw: readonly string[], omit: ReadonlySet<string> = new Set()): string[] {
+  const named = new Set<string>();
+  for (let i = 0; i + 1 < raw.length; i += 2) {
+    if (raw[i]!.toLowerCase() === "connection") {
+      for (const name of raw[i + 1]!.split(",")) named.add(name.trim().toLowerCase());
+    }
+  }
+  const result: string[] = [];
+  for (let i = 0; i + 1 < raw.length; i += 2) {
+    const name = raw[i]!.toLowerCase();
+    if (!HOP_HEADERS.has(name) && !named.has(name) && !omit.has(name)) {
+      result.push(raw[i]!, raw[i + 1]!);
+    }
+  }
+  return result;
+}
+
+function hasJsonContentType(raw: readonly string[]): boolean {
+  for (let i = 0; i + 1 < raw.length; i += 2) {
+    if (raw[i]!.toLowerCase() === "content-type") {
+      return /^(?:application\/json|[^;\s]+\+json)(?:\s*;|\s*$)/i.test(raw[i + 1]!);
+    }
+  }
+  return false;
+}
+
+function contentEncoding(raw: readonly string[]): string | undefined {
+  for (let i = 0; i + 1 < raw.length; i += 2) {
+    if (raw[i]!.toLowerCase() === "content-encoding") return raw[i + 1]!;
+  }
+  return undefined;
+}
+
+export async function startPickerListener(options: PickerListenerOptions): Promise<PickerListenerHandle> {
+  const upstream = options.upstream ?? { host: "claude.ai", port: 443, servername: "claude.ai" };
+  const cap = options.maxEncodedBytes ?? BOOTSTRAP_MAX_ENCODED_BYTES;
+  const upgrades = new Set<Duplex>();
+  const server = createServer({ cert: options.leaf.certPem, key: options.leaf.keyPem, ALPNProtocols: ["http/1.1"] });
+
+  server.on("request", (req: IncomingMessage, res: ServerResponse) => {
+    const method = req.method ?? "GET";
+    const pathname = new URL(req.url ?? "/", "https://claude.ai").pathname;
+    const bootstrap = isPickerBootstrapRequest(method, pathname);
+    const category = bootstrap ? "bootstrap" : "other";
+    let logged = false;
+    const log = (status: number) => {
+      if (!logged) options.log?.(`picker ${method} ${category} ${status}`);
+      logged = true;
+    };
+    const fail = () => {
+      if (res.headersSent) res.destroy();
+      else { res.writeHead(502, { "Content-Length": "0" }); res.end(); log(502); }
+    };
+    const omit = bootstrap ? new Set(["accept-encoding"]) : new Set<string>();
+    const headers = filteredHeaders(req.rawHeaders, omit);
+    if (bootstrap) headers.push("Accept-Encoding", narrowBootstrapAcceptEncoding());
+    const upReq = httpsRequest({
+      host: upstream.host, port: upstream.port, servername: upstream.servername,
+      ca: upstream.ca, rejectUnauthorized: true, agent: false,
+      method, path: req.url, headers,
+    }, upRes => {
+      const status = upRes.statusCode ?? 502;
+      const originalHeaders = filteredHeaders(upRes.rawHeaders);
+      const sendHead = (raw: string[]) => {
+        if (res.headersSent) return;
+        res.writeHead(status, upRes.statusMessage, raw);
+        log(status);
+      };
+      upRes.on("error", fail);
+      if (!bootstrap || status !== 200 || !hasJsonContentType(upRes.rawHeaders)) {
+        sendHead(originalHeaders);
+        upRes.pipe(res);
+        return;
+      }
+      const held: Buffer[] = [];
+      let size = 0;
+      let handedOff = false;
+      const onData = (chunk: Buffer) => {
+        if (size + chunk.length > cap) {
+          upRes.pause();
+          upRes.off("data", onData);
+          handedOff = true;
+          sendHead(originalHeaders);
+          for (const part of held) res.write(part);
+          res.write(chunk);
+          upRes.pipe(res);
+          return;
+        }
+        held.push(chunk);
+        size += chunk.length;
+      };
+      upRes.on("data", onData);
+      upRes.once("end", () => {
+        if (handedOff) return;
+        const original = Buffer.concat(held, size);
+        let outcome = "unchanged";
+        const rewritten = rewriteBootstrapBody(original, contentEncoding(upRes.rawHeaders), options.models(), result => {
+          outcome = result.kind === "rewritten" ? `rewritten(+${result.added})` : `unchanged:${result.reason}`;
+        });
+        sendHead(rewritten === null ? originalHeaders : rewrittenHeaders(originalHeaders, rewritten.length));
+        options.log?.(`picker ${method} bootstrap ${outcome}`);
+        res.end(rewritten ?? original);
+      });
+    });
+    upReq.on("error", fail);
+    req.on("error", () => upReq.destroy());
+    res.on("close", () => { if (!res.writableEnded) upReq.destroy(); });
+    req.pipe(upReq);
+  });
+
+  server.on("upgrade", (req, client, head) => {
+    const method = req.method ?? "GET";
+    const target = tlsConnect({
+      host: upstream.host, port: upstream.port, servername: upstream.servername,
+      ca: upstream.ca, rejectUnauthorized: true, ALPNProtocols: ["http/1.1"],
+    });
+    upgrades.add(client);
+    upgrades.add(target);
+    let established = false;
+    let upgradeLogged = false;
+    let responseStart = "";
+    const logUpgrade = (status: number) => {
+      if (upgradeLogged) return;
+      upgradeLogged = true;
+      options.log?.(`picker ${method} other ${status}`);
+    };
+    const onResponseData = (chunk: Buffer) => {
+      responseStart += chunk.toString("latin1");
+      const end = responseStart.indexOf("\r\n");
+      if (end >= 0) {
+        target.off("data", onResponseData);
+        const status = /^HTTP\/1\.[01] (\d{3})(?: |$)/.exec(responseStart.slice(0, end));
+        logUpgrade(status ? Number(status[1]) : 502);
+      } else if (responseStart.length > 128) {
+        target.off("data", onResponseData);
+        logUpgrade(502);
+      }
+    };
+    const fail = () => {
+      if (!established && !client.destroyed) client.end("HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\nConnection: close\r\n\r\n");
+      else client.destroy();
+      target.destroy();
+      logUpgrade(502);
+    };
+    target.on("data", onResponseData);
+    target.once("secureConnect", () => {
+      established = true;
+      target.write(`${method} ${req.url ?? "/"} HTTP/1.1\r\n`);
+      for (let i = 0; i + 1 < req.rawHeaders.length; i += 2) {
+        if (/^proxy-(?:authorization|connection)$/i.test(req.rawHeaders[i]!)) continue;
+        target.write(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`);
+      }
+      target.write("\r\n");
+      if (head.length) target.write(head);
+      client.pipe(target).pipe(client);
+    });
+    target.once("error", fail);
+    client.once("error", () => target.destroy());
+    target.once("close", () => { upgrades.delete(target); if (!upgradeLogged) logUpgrade(502); client.destroy(); });
+    client.once("close", () => { upgrades.delete(client); target.destroy(); });
+  });
+
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+    });
+  } catch (error) {
+    server.close();
+    throw error;
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("picker listener has no port");
+  return {
+    port: address.port,
+    async close() {
+      for (const socket of upgrades) socket.destroy();
+      const closed = new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+      server.closeAllConnections();
+      await closed;
+    },
+  };
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Claude Desktop picker candidates use the gateway's profile order and labels, while
+ * publishing aliases that the first-party Messages ingress can resolve.
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { nativeOpenAiContextWindow, type NativeContextLimitsInput } from "../../codex/catalog";
+import type { OcxClaudeDesktopProfile } from "../../types";
+import { aliasForRoute, claudeCodeNativeAlias } from "../alias";
+import { displayModelId, type Desktop3pRoutedModel } from "../desktop-3p";
+import { reconcileDesktopProfile, renderDesktopProfile, type DesktopProfileModel } from "../desktop-profile";
+import type { PickerModelEntry } from "./picker-bootstrap";
+
+export interface PickerRouteInput {
+  nativeSlugs: string[];
+  routedModels: Desktop3pRoutedModel[];
+  profile?: OcxClaudeDesktopProfile;
+  nativeContextCap?: NativeContextLimitsInput;
+}
+
+export function buildPickerModels(input: PickerRouteInput): PickerModelEntry[] {
+  const candidates: DesktopProfileModel[] = [
+    ...input.nativeSlugs.map(id => {
+      const contextWindow = nativeOpenAiContextWindow(id, input.nativeContextCap);
+      return {
+        route: `native/${id}`,
+        label: `${displayModelId(id)} (native)`,
+        ...(contextWindow === undefined ? {} : { contextWindow }),
+      };
+    }),
+    ...input.routedModels.map(({ provider, id, contextWindow }) => ({
+      route: `${provider}/${id}`,
+      label: `${displayModelId(id)} (${provider})`,
+      ...(contextWindow === undefined ? {} : { contextWindow }),
+    })),
+  ];
+  const rendered = input.profile
+    ? renderDesktopProfile(reconcileDesktopProfile(input.profile, candidates), candidates)
+    : candidates;
+  const out: PickerModelEntry[] = [];
+  const seen = new Set<string>();
+  for (const model of rendered) {
+    const slash = model.route.indexOf("/");
+    const provider = model.route.slice(0, slash);
+    const id = model.route.slice(slash + 1);
+    if (provider === "anthropic" && id.startsWith("claude-")) continue;
+    const alias = provider === "native" ? claudeCodeNativeAlias(id) : aliasForRoute(provider, id);
+    if (!alias || seen.has(alias)) continue;
+    seen.add(alias);
+    out.push({ id: alias, name: model.label,
+      ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }) });
+  }
+  return out;
+}
+
+export interface PickerModelSnapshot {
+  current(): { models: PickerModelEntry[]; builtAt: number } | null;
+  refresh(): Promise<void>;
+  refreshIfStale(maxAgeMs: number): void;
+}
+
+function parseSnapshot(value: unknown): { models: PickerModelEntry[]; builtAt: number } | null {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as { models?: unknown; builtAt?: unknown };
+  if (typeof candidate.builtAt !== "number" || !Number.isFinite(candidate.builtAt) || !Array.isArray(candidate.models)) return null;
+  if (!candidate.models.every(model => model && typeof model === "object"
+    && typeof model.id === "string" && typeof model.name === "string"
+    && (model.contextWindow === undefined || typeof model.contextWindow === "number"))) return null;
+  return { models: candidate.models as PickerModelEntry[], builtAt: candidate.builtAt };
+}
+
+export function createPickerModelSnapshot(load: () => Promise<PickerRouteInput>, persistPath?: string): PickerModelSnapshot {
+  let snapshot: { models: PickerModelEntry[]; builtAt: number } | null = null;
+  if (persistPath) {
+    try { snapshot = parseSnapshot(JSON.parse(readFileSync(persistPath, "utf8")) as unknown); } catch { /* No usable prior snapshot. */ }
+  }
+  let pending: Promise<void> | null = null;
+  const refresh = (): Promise<void> => {
+    if (pending) return pending;
+    pending = (async () => {
+      try {
+        const models = buildPickerModels(await load());
+        const next = { models, builtAt: Date.now() };
+        if (persistPath) {
+          mkdirSync(dirname(persistPath), { recursive: true, mode: 0o700 });
+          writeFileSync(persistPath, JSON.stringify(next), { encoding: "utf8", mode: 0o600 });
+          chmodSync(persistPath, 0o600);
+        }
+        snapshot = next;
+      } catch { /* Keep the last good snapshot when discovery or persistence fails. */ }
+    })().finally(() => { pending = null; });
+    return pending;
+  };
+  return {
+    current: () => snapshot,
+    refresh,
+    refreshIfStale(maxAgeMs) {
+      if (!pending && (!snapshot || Date.now() - snapshot.builtAt >= maxAgeMs)) void refresh();
+    },
+  };
+}