pi-freeflow 1.23.3 → 1.24.0

package/src/catalog.ts

@@ -1,418 +1,417 @@
-/**
- * Dynamic catalog discovery, caching, and model enrichment for pi-freeflow
- *
- * Provides 1-hour atomic disk caching with safe offline fallback to verified static definitions.
- */
-
-import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import {
- CATALOG_CACHE_FILE,
- CATALOG_CACHE_TTL_MS,
- CATALOG_REFRESH_TIMEOUT_MS,
- KILO_CHAT_URL,
- OPENCODE_API_URL,
- opencodeHeaders,
-} from "./config.ts";
-import { log, logDebug, logWarn } from "./logger.ts";
-import {
- ALL_MODELS,
- MODEL_MAP,
- getModelUpstream,
-} from "./models.ts";
-import type {
- CatalogCacheData,
- RawModelItem,
- RegisteredModel,
- Upstream,
-} from "./types.ts";
-
-/**
- * Pruned model IDs that must never re-enter the catalog via disk cache or upstream merge.
- */
-export const DEAD_MODEL_IDS = new Set<string>([
- "deepseek-v4-flash-free",
- "x-preview-f-free",
- "hy3-free",
- "tencent/hy3:free",
- "meituan/longcat-2.0-free",
- "laguna-s-2.1-free",
- "minimax/minimax-m2.7:free",
- "minimax/minimax-m3:free",
- "thinkingmachines/inkling:free",
-]);
-/**
- * Free-tier allowlist for anything entering the picker via network or stale disk.
- * Upstream lists paid models alongside free ones (e.g. claude-fable-5-1,
- * claude-opus-4-*, gemini-3-*) so a bare upstream merge leaks paid entries that
- * fail with 401 Missing API key. Known static IDs without a free suffix
- * (e.g. big-pickle) stay allowed via MODEL_MAP.
- */
-export function isFreeCatalogId(id: string): boolean {
- if (typeof id !== "string" || id.length === 0) return false;
- if (DEAD_MODEL_IDS.has(id)) return false;
- return id.includes("-free") || id.includes(":free") || id.includes("/free") || MODEL_MAP.has(id);
-}
-/**
- * Purge paid/dead entries from a catalog list and repair known models against
- * the static definitions. Stale disk caches predate the paid filter and the
- * muse-spark-1.3 responses-api entry, so loading them verbatim replays a wrong
- * api (chat/completions for a responses-only model -> upstream 500) until the
- * 24h TTL expires. Repairing here self-heals on the next refresh without a
- * reinstall.
- */
-export function sanitizeCatalogModels(models: RegisteredModel[]): RegisteredModel[] {
- const out: RegisteredModel[] = [];
- for (const m of models) {
-  if (!m || typeof m.id !== "string" || !isFreeCatalogId(m.id)) continue;
-  const known = MODEL_MAP.get(m.id);
-  if (known) {
-   // A known id's upstream is a static fact: a stale cache entry must never
-   // relabel it (a Cline model advertised as opencode would register with the
-   // wrong compat settings).
-   out.push({ ...known, source: getModelUpstream(m.id) });
-  } else {
-   out.push(m);
-  }
- }
- return out;
-}
-/**
- * In-memory cache of currently active/available free models.
- * Initialized with all 31 verified models for 0ms instant availability.
- */
-let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
- ...m,
- source: getModelUpstream(m.id),
-}));
-/**
- * Get current in-memory alive catalog
- */
-export function getAliveCatalog(): RegisteredModel[] {
- return aliveCatalog;
-}
-
-/**
- * Set in-memory alive catalog
- */
-export function setAliveCatalog(catalog: RegisteredModel[]): void {
- aliveCatalog = catalog;
-}
-
-/**
- * Overlay a refreshed model list onto a base list without dropping base entries.
- * Fresh entries win on id collision; unknown fresh ids are appended after the base.
- * Guards the background refresh against a partial upstream cache removing
- * verified static models from provider registration.
- * Filters pruned dead IDs so they never re-enter via fresh upstream data.
- */
-export function mergeCatalog(
- base: RegisteredModel[],
- fresh: RegisteredModel[],
-): RegisteredModel[] {
- const filteredFresh = fresh.filter((m) => m && typeof m.id === "string" && isFreeCatalogId(m.id));
- const byId = new Map(base.map((m) => [m.id, m]));
- for (const m of filteredFresh) byId.set(m.id, m);
- // Sanitize the merged result so stale paid entries in a pre-fix base and
- // stale api fields on known models never survive the merge.
- return sanitizeCatalogModels([...byId.values()]);
-}
-
-/**
- * Format a clean, human-readable display name for any upstream model ID.
- */
-export function formatCleanDisplayName(id: string, customName?: string): string {
- if (customName && customName.trim()) {
-  return customName.trim();
- }
- const known = MODEL_MAP.get(id);
- if (known && known.name) {
-  return known.name;
- }
-
- // Strip provider prefix ("nvidia/", "stepfun/", "dots-studio/", etc.)
- let clean = id.replace(/^[a-zA-Z0-9_.-]+\//, "");
- // Strip variant suffixes
- clean = clean.replace(/:(free|preview|exacto|default|batch)$/i, "");
- clean = clean.replace(/-(free|contributor|preview)$/i, "");
-
- // Capitalize words with acronym preservation
- const parts = clean.split(/[-_]/).map((w) => {
-  const lower = w.toLowerCase();
-  if (lower === "gpt") return "GPT";
-  if (lower === "ai") return "AI";
-  if (lower === "lfm") return "LFM";
-  if (lower === "hy3") return "Hy3";
-  if (lower === "mimo") return "MiMo";
-  if (lower === "ocr") return "OCR";
-  return w.charAt(0).toUpperCase() + w.slice(1);
- });
-
- return parts.join(" ");
-}
-
-/**
- * Enrich a raw upstream model item into a fully typed RegisteredModel.
- */
-export function enrichModelDef(raw: RawModelItem, source: Upstream): RegisteredModel {
- const known = MODEL_MAP.get(raw.id);
- if (known) {
-  return { ...known, source };
- }
-
- const idLower = raw.id.toLowerCase();
- const hasVision =
-  idLower.includes("vision") ||
-  idLower.includes("vl") ||
-  idLower.includes("omni") ||
-  idLower.includes("note") ||
-  idLower.includes("image");
- const hasReasoning =
-  idLower.includes("reasoning") ||
-  idLower.includes("r1") ||
-  idLower.includes("o1") ||
-  idLower.includes("think") ||
-  idLower.includes("spark") ||
-  idLower.includes("flash") ||
-  idLower.includes("deepseek") ||
-  idLower.includes("glm") ||
-  idLower.includes("solar");
-
- let contextWindow =
-  typeof raw.context_length === "number" ? raw.context_length : 262_144;
- if (
-  idLower.includes("1m") ||
-  idLower.includes("ultra") ||
-  idLower.includes("lightning") ||
-  idLower.includes("mimo-v2.5") ||
-  idLower.includes("muse-spark")
- ) {
-  contextWindow = 1_048_576;
- }
-
- let maxTokens =
-  typeof raw.max_output_tokens === "number"
-   ? raw.max_output_tokens
-   : 65_536;
- if (idLower.includes("ultra") || idLower.includes("lightning")) {
-  maxTokens = 131_072;
- }
-
- // Muse Spark is served on the responses API upstream (both static catalogue
- // entries declare it). Every known id short-circuits above, so this only
- // decides for ids Zen lists dynamically — matching the family keeps a future
- // muse-spark id off the chat endpoint it would 500 on.
- const isResponses = idLower.includes("muse-spark");
-
- return {
-  id: raw.id,
-  name: formatCleanDisplayName(raw.id),
-  source,
-  reasoning: hasReasoning,
-  contextWindow,
-  maxTokens,
-  api: isResponses ? "openai-responses" : undefined,
-  input: hasVision ? ["text", "image"] : ["text"],
-  thinkingFormat: source === "kilo" && hasReasoning ? "openrouter" : undefined,
- };
-}
-
-/**
- * Read cached catalog data from disk if valid and unexpired.
- * Filters out pruned dead IDs so stale disk entries never repopulate the catalog.
- * Preserves etag for conditional If-None-Match requests.
- */
-export function readCatalogCache(): CatalogCacheData | null {
- try {
-  if (!fs.existsSync(CATALOG_CACHE_FILE)) {
-   return null;
-  }
-  const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
-  const data = JSON.parse(raw) as CatalogCacheData;
-  if (!Array.isArray(data.models)) {
-   return null;
-  }
-  data.models = sanitizeCatalogModels(data.models);
-  if (Date.now() - data.timestamp < CATALOG_CACHE_TTL_MS) {
-   return data;
-  }
- } catch (err) {
-  logDebug("Failed reading catalog cache", { error: String(err) });
- }
- return null;
-}
-
-/**
- * Atomically write catalog cache data to disk using temporary file + rename.
- * Persists etag alongside models for subsequent If-None-Match conditional requests.
- * Note: fsync not needed — rename is atomic on same filesystem; crash leaves either old or new file intact.
- */
-function sleepSync(ms: number): void {
- Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-function renameWithRetry(from: string, to: string): void {
- const retryable: Record<string, true> = { EPERM: true, EACCES: true, EBUSY: true };
- for (let attempt = 1; ; attempt++) {
-  try {
-   fs.renameSync(from, to);
-   return;
-  } catch (e) {
-   const code = (e as NodeJS.ErrnoException | null)?.code;
-   if (!code || !retryable[code] || attempt >= 3) {
-    throw e;
-   }
-   sleepSync(50);
-  }
- }
-}
-
-export function writeCatalogCache(data: CatalogCacheData): void {
- try {
-  const dir = path.dirname(CATALOG_CACHE_FILE);
-  if (!fs.existsSync(dir)) {
-   fs.mkdirSync(dir, { recursive: true });
-  }
-  const tmpPath = `${CATALOG_CACHE_FILE}.${randomUUID()}.tmp`;
-  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf8");
-  renameWithRetry(tmpPath, CATALOG_CACHE_FILE);
- } catch (err) {
-  logWarn("Could not persist catalog cache to disk", { error: String(err) });
- }
-}
-
-/**
- * Refresh free model catalog from OpenCode Zen and KiloCode Gateway endpoints.
- * Uses ETag conditional requests (If-None-Match) to avoid re-merging unchanged
- * catalogs; a 304 Not Modified response skips merge and returns the in-memory
- * catalog unchanged. Falls back gracefully to cached or static models if network
- * requests fail.
- */
-export async function refreshCatalog(force = false): Promise<RegisteredModel[]> {
- // Thin provider: serve fresh disk cache instantly when valid. The cache is
- // overlayed on the static base rather than replacing it, so a cache written
- // before a model was added to the catalog (or pruned from it) cannot drop
- // models the host still registers.
- const staticBase: RegisteredModel[] = ALL_MODELS.map((m) => ({ ...m, source: getModelUpstream(m.id) }));
- const disk = readCatalogCache();
- if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
-  const age = Date.now() - (disk.timestamp ?? 0);
-  if (!force && age < CATALOG_CACHE_TTL_MS) {
-   aliveCatalog = mergeCatalog(staticBase, sanitizeCatalogModels(disk.models));
-   return aliveCatalog;
-  }
- }
-
- // Resolve etag from fresh or stale cache for conditional request
- let cachedEtag: string | undefined = disk?.etag;
- let staleForEtag: CatalogCacheData | null = disk;
- if (!cachedEtag) {
-  try {
-   if (fs.existsSync(CATALOG_CACHE_FILE)) {
-    const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
-    const stale = JSON.parse(raw) as CatalogCacheData;
-    cachedEtag = stale.etag;
-    staleForEtag = stale;
-   }
-  } catch (err) {
-   logDebug("Failed reading stale catalog cache for etag", { error: String(err) });
-  }
- }
-
- // Attempt a fetch whenever there is cache material to revalidate: conditional
- // with If-None-Match when we have an etag, plain otherwise. A pre-fix cache
- // file with no etag must still go live (acquiring an etag and discovering
- // new free models) instead of serving stale indefinitely. Corrupt/missing
- // caches (staleForEtag null) skip the network and fall through to static.
- if (cachedEtag || force || staleForEtag) {
-  try {
-   const headers: Record<string, string> = { ...opencodeHeaders() };
-   if (cachedEtag) {
-    headers["If-None-Match"] = cachedEtag;
-   }
-   const res = await fetch(`${OPENCODE_API_URL}/models`, {
-    headers,
-    // A hung upstream must not freeze /freeflow refresh: abort after
-    // CATALOG_REFRESH_TIMEOUT_MS and fall back to cache below.
-    signal: AbortSignal.timeout(CATALOG_REFRESH_TIMEOUT_MS),
-   });
-   if (res.status === 304) {
-    // Not modified — skip merge, extend timestamp to avoid tight loop
-    if (staleForEtag && Array.isArray(staleForEtag.models)) {
-     try {
-      writeCatalogCache({ ...staleForEtag, timestamp: Date.now() });
-     } catch { }
-    }
-    return aliveCatalog;
-   }
-   if (res.ok) {
-    const newEtag = res.headers.get("etag") ?? res.headers.get("ETag") ?? cachedEtag;
-    const body: unknown = await res.json();
-    let rawList: RawModelItem[] = [];
-    if (Array.isArray(body)) {
-     rawList = body as RawModelItem[];
-    } else if (body !== null && typeof body === "object" && "data" in body) {
-     const dataVal = body.data as unknown;
-     if (Array.isArray(dataVal)) {
-      rawList = dataVal as RawModelItem[];
-     }
-    }
-    if (rawList.length > 0) {
-     const freeRawList = rawList.filter((r) => r && typeof r.id === "string" && isFreeCatalogId(r.id));
-     const fresh = freeRawList.map((r) => enrichModelDef(r, "opencode"));
-     const merged = mergeCatalog(aliveCatalog, fresh);
-     aliveCatalog = merged;
-     writeCatalogCache({
-      timestamp: Date.now(),
-      opencode: fresh.map((m) => m.id),
-      kilo: staleForEtag?.kilo ?? [],
-      models: merged,
-      etag: newEtag ?? cachedEtag,
-     });
-     return aliveCatalog;
-    }
-    // Empty payload but 200 — treat as no-op, return current
-    if (newEtag && newEtag !== cachedEtag && staleForEtag) {
-     writeCatalogCache({ ...staleForEtag, timestamp: Date.now(), etag: newEtag });
-    }
-    return aliveCatalog;
-   }
-  } catch (err) {
-   if ((err as Error)?.name === "AbortError") {
-    logWarn("Catalog refresh timed out — using cached/static fallback", {
-     timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,
-    });
-   } else {
-    logDebug("Conditional catalog fetch failed, falling back to cache", { error: String(err) });
-   }
-  }
- }
-
- // Stale cache still better than empty — return it without network (filtered)
- if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
-  const filtered = sanitizeCatalogModels(disk.models);
-  if (filtered.length >= ALL_MODELS.length) {
-   aliveCatalog = filtered;
-   return aliveCatalog;
-  }
- }
- // No valid fresh cache — try stale disk cache directly (readCatalogCache returns null when expired)
- try {
-  if (fs.existsSync(CATALOG_CACHE_FILE)) {
-   const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
-   const stale = JSON.parse(raw) as CatalogCacheData;
-   if (Array.isArray(stale.models) && stale.models.length > 0) {
-    const filtered = sanitizeCatalogModels(stale.models);
-    if (filtered.length >= ALL_MODELS.length) {
-     aliveCatalog = filtered;
-     return aliveCatalog;
-    }
-   }
-  }
- } catch (err) {
-  logDebug("Failed reading stale catalog cache", { error: String(err) });
- }
- // No valid cache — return in-memory static 27 (host will refresh if needed)
- return aliveCatalog;
-}
+/**
+ * Dynamic catalog discovery, caching, and model enrichment for pi-freeflow
+ *
+ * Provides 1-hour atomic disk caching with safe offline fallback to verified static definitions.
+ */
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+ CATALOG_CACHE_FILE,
+ CATALOG_CACHE_TTL_MS,
+ CATALOG_REFRESH_TIMEOUT_MS,
+ KILO_CHAT_URL,
+ OPENCODE_API_URL,
+ opencodeHeaders,
+} from "./config.ts";
+import { log, logDebug, logWarn } from "./logger.ts";
+import {
+ ALL_MODELS,
+ MODEL_MAP,
+ getModelUpstream,
+} from "./models.ts";
+import type {
+ CatalogCacheData,
+ RawModelItem,
+ RegisteredModel,
+ Upstream,
+} from "./types.ts";
+
+/**
+ * Pruned model IDs that must never re-enter the catalog via disk cache or upstream merge.
+ */
+export const DEAD_MODEL_IDS = new Set<string>([
+ "deepseek-v4-flash-free",
+ "x-preview-f-free",
+ "hy3-free",
+ "tencent/hy3:free",
+ "meituan/longcat-2.0-free",
+ "laguna-s-2.1-free",
+ "minimax/minimax-m2.7:free",
+ "minimax/minimax-m3:free",
+ "thinkingmachines/inkling:free",
+ "union-alpha",
+]);
+/**
+ * Free-tier allowlist for anything entering the picker via network or stale disk.
+ * Upstream lists paid models alongside free ones (e.g. claude-fable-5-1,
+ * claude-opus-4-*, gemini-3-*) so a bare upstream merge leaks paid entries that
+ * fail with 401 Missing API key. Known static IDs without a free suffix
+ * (e.g. big-pickle) stay allowed via MODEL_MAP.
+ */
+export function isFreeCatalogId(id: string): boolean {
+ if (typeof id !== "string" || id.length === 0) return false;
+ if (DEAD_MODEL_IDS.has(id)) return false;
+ return id.includes("-free") || id.includes(":free") || id.includes("/free") || MODEL_MAP.has(id);
+}
+/**
+ * Purge paid/dead entries from a catalog list and repair known models against
+ * the static definitions. Stale disk caches predate the paid filter and the
+ * muse-spark-1.3 responses-api entry, so loading them verbatim replays a wrong
+ * api (chat/completions for a responses-only model -> upstream 500) until the
+ * 24h TTL expires. Repairing here self-heals on the next refresh without a
+ * reinstall.
+ */
+export function sanitizeCatalogModels(models: RegisteredModel[]): RegisteredModel[] {
+ const out: RegisteredModel[] = [];
+ for (const m of models) {
+  if (!m || typeof m.id !== "string" || !isFreeCatalogId(m.id)) continue;
+  const known = MODEL_MAP.get(m.id);
+  if (known) {
+   // A known id's upstream is a static fact: a stale cache entry must never
+   // relabel it (a Cline model advertised as opencode would register with the
+   // wrong compat settings).
+   out.push({ ...known, source: getModelUpstream(m.id) });
+  } else {
+   out.push(m);
+  }
+ }
+ return out;
+}
+/**
+ * In-memory cache of currently active/available free models.
+ * Initialized with all 31 verified models for 0ms instant availability.
+ */
+let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
+ ...m,
+ source: getModelUpstream(m.id),
+}));
+/**
+ * Get current in-memory alive catalog
+ */
+export function getAliveCatalog(): RegisteredModel[] {
+ return aliveCatalog;
+}
+
+/**
+ * Set in-memory alive catalog
+ */
+export function setAliveCatalog(catalog: RegisteredModel[]): void {
+ aliveCatalog = catalog;
+}
+
+/**
+ * Overlay a refreshed model list onto a base list without dropping base entries.
+ * Fresh entries win on id collision; unknown fresh ids are appended after the base.
+ * Guards the background refresh against a partial upstream cache removing
+ * verified static models from provider registration.
+ * Filters pruned dead IDs so they never re-enter via fresh upstream data.
+ */
+export function mergeCatalog(
+ base: RegisteredModel[],
+ fresh: RegisteredModel[],
+): RegisteredModel[] {
+ const filteredFresh = fresh.filter((m) => m && typeof m.id === "string" && isFreeCatalogId(m.id));
+ const byId = new Map(base.map((m) => [m.id, m]));
+ for (const m of filteredFresh) byId.set(m.id, m);
+ // Sanitize the merged result so stale paid entries in a pre-fix base and
+ // stale api fields on known models never survive the merge.
+ return sanitizeCatalogModels([...byId.values()]);
+}
+
+/**
+ * Format a clean, human-readable display name for any upstream model ID.
+ */
+export function formatCleanDisplayName(id: string, customName?: string): string {
+ if (customName && customName.trim()) {
+  return customName.trim();
+ }
+ const known = MODEL_MAP.get(id);
+ if (known && known.name) {
+  return known.name;
+ }
+
+ // Strip provider prefix ("nvidia/", "stepfun/", "dots-studio/", etc.)
+ let clean = id.replace(/^[a-zA-Z0-9_.-]+\//, "");
+ // Strip variant suffixes
+ clean = clean.replace(/:(free|preview|exacto|default|batch)$/i, "");
+ clean = clean.replace(/-(free|contributor|preview)$/i, "");
+
+ // Capitalize words with acronym preservation
+ const parts = clean.split(/[-_]/).map((w) => {
+  const lower = w.toLowerCase();
+  if (lower === "gpt") return "GPT";
+  if (lower === "ai") return "AI";
+  if (lower === "lfm") return "LFM";
+  if (lower === "hy3") return "Hy3";
+  if (lower === "mimo") return "MiMo";
+  if (lower === "ocr") return "OCR";
+  return w.charAt(0).toUpperCase() + w.slice(1);
+ });
+
+ return parts.join(" ");
+}
+
+/**
+ * Enrich a raw upstream model item into a fully typed RegisteredModel.
+ */
+export function enrichModelDef(raw: RawModelItem, source: Upstream): RegisteredModel {
+ const known = MODEL_MAP.get(raw.id);
+ if (known) {
+  return { ...known, source };
+ }
+
+ const idLower = raw.id.toLowerCase();
+ const hasVision =
+  idLower.includes("vision") ||
+  idLower.includes("vl") ||
+  idLower.includes("omni") ||
+  idLower.includes("note") ||
+  idLower.includes("image");
+ const hasReasoning =
+  idLower.includes("reasoning") ||
+  idLower.includes("r1") ||
+  idLower.includes("o1") ||
+  idLower.includes("think") ||
+  idLower.includes("spark") ||
+  idLower.includes("flash") ||
+  idLower.includes("deepseek") ||
+  idLower.includes("glm") ||
+  idLower.includes("solar");
+
+ let contextWindow =
+  typeof raw.context_length === "number" ? raw.context_length : 262_144;
+ if (
+  idLower.includes("1m") ||
+  idLower.includes("ultra") ||
+  idLower.includes("lightning") ||
+  idLower.includes("mimo-v2.5") ||
+  idLower.includes("muse-spark")
+ ) {
+  contextWindow = 1_048_576;
+ }
+
+ let maxTokens =
+  typeof raw.max_output_tokens === "number"
+   ? raw.max_output_tokens
+   : 65_536;
+ if (idLower.includes("ultra") || idLower.includes("lightning")) {
+  maxTokens = 131_072;
+ }
+
+ // Muse Spark is served on the responses API upstream (both static catalogue
+ // entries declare it). Every known id short-circuits above, so this only
+ // decides for ids Zen lists dynamically — matching the family keeps a future
+ // muse-spark id off the chat endpoint it would 500 on.
+ const isResponses = idLower.includes("muse-spark");
+
+ return {
+  id: raw.id,
+  name: formatCleanDisplayName(raw.id),
+  source,
+  reasoning: hasReasoning,
+  contextWindow,
+  maxTokens,
+  api: isResponses ? "openai-responses" : undefined,
+  input: hasVision ? ["text", "image"] : ["text"],
+  thinkingFormat: source === "kilo" && hasReasoning ? "openrouter" : undefined,
+ };
+}
+
+/**
+ * Read cached catalog data from disk if valid and unexpired.
+ * Filters out pruned dead IDs so stale disk entries never repopulate the catalog.
+ * Preserves etag for conditional If-None-Match requests.
+ */
+export function readCatalogCache(): CatalogCacheData | null {
+ try {
+  if (!fs.existsSync(CATALOG_CACHE_FILE)) {
+   return null;
+  }
+  const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
+  const data = JSON.parse(raw) as CatalogCacheData;
+  if (!Array.isArray(data.models)) {
+   return null;
+  }
+  data.models = sanitizeCatalogModels(data.models);
+  if (Date.now() - data.timestamp < CATALOG_CACHE_TTL_MS) {
+   return data;
+  }
+ } catch (err) {
+  logDebug("Failed reading catalog cache", { error: String(err) });
+ }
+ return null;
+}
+
+/**
+ * Atomically write catalog cache data to disk using temporary file + rename.
+ * Persists etag alongside models for subsequent If-None-Match conditional requests.
+ * Note: fsync not needed — rename is atomic on same filesystem; crash leaves either old or new file intact.
+ */
+function sleepSync(ms: number): void {
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function renameWithRetry(from: string, to: string): void {
+ const retryable: Record<string, true> = { EPERM: true, EACCES: true, EBUSY: true };
+ for (let attempt = 1; ; attempt++) {
+  try {
+   fs.renameSync(from, to);
+   return;
+  } catch (e) {
+   const code = (e as NodeJS.ErrnoException | null)?.code;
+   if (!code || !retryable[code] || attempt >= 3) {
+    throw e;
+   }
+   sleepSync(50);
+  }
+ }
+}
+
+export function writeCatalogCache(data: CatalogCacheData): void {
+ try {
+  const dir = path.dirname(CATALOG_CACHE_FILE);
+  if (!fs.existsSync(dir)) {
+   fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = `${CATALOG_CACHE_FILE}.${randomUUID()}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf8");
+  renameWithRetry(tmpPath, CATALOG_CACHE_FILE);
+ } catch (err) {
+  logWarn("Could not persist catalog cache to disk", { error: String(err) });
+ }
+}
+
+/**
+ * Refresh free model catalog from OpenCode Zen and KiloCode Gateway endpoints.
+ * Uses ETag conditional requests (If-None-Match) to avoid re-merging unchanged
+ * catalogs; a 304 Not Modified response skips merge and returns the in-memory
+ * catalog unchanged. Falls back gracefully to cached or static models if network
+ * requests fail.
+ */
+export async function refreshCatalog(force = false): Promise<RegisteredModel[]> {
+ // Thin provider: serve fresh disk cache instantly when valid. The cache is
+ // overlayed on the static base rather than replacing it, so a cache written
+ // before a model was added to the catalog (or pruned from it) cannot drop
+ // models the host still registers.
+ const staticBase: RegisteredModel[] = ALL_MODELS.map((m) => ({ ...m, source: getModelUpstream(m.id) }));
+ const disk = readCatalogCache();
+ if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
+  const age = Date.now() - (disk.timestamp ?? 0);
+  if (!force && age < CATALOG_CACHE_TTL_MS) {
+   aliveCatalog = mergeCatalog(staticBase, sanitizeCatalogModels(disk.models));
+   return aliveCatalog;
+  }
+ }
+
+ // Resolve etag from fresh or stale cache for conditional request
+ let cachedEtag: string | undefined = disk?.etag;
+ let staleForEtag: CatalogCacheData | null = disk;
+ if (!cachedEtag) {
+  try {
+   if (fs.existsSync(CATALOG_CACHE_FILE)) {
+    const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
+    const stale = JSON.parse(raw) as CatalogCacheData;
+    cachedEtag = stale.etag;
+    staleForEtag = stale;
+   }
+  } catch (err) {
+   logDebug("Failed reading stale catalog cache for etag", { error: String(err) });
+  }
+ }
+
+ // Attempt a fetch whenever there is cache material to revalidate: conditional
+ // with If-None-Match when we have an etag, plain otherwise. A pre-fix cache
+ // file with no etag must still go live (acquiring an etag and discovering
+ // new free models) instead of serving stale indefinitely. Corrupt/missing
+ // caches (staleForEtag null) skip the network and fall through to static.
+ if (cachedEtag || force || staleForEtag) {
+  try {
+   const headers: Record<string, string> = { ...opencodeHeaders() };
+   if (cachedEtag) {
+    headers["If-None-Match"] = cachedEtag;
+   }
+   const res = await fetch(`${OPENCODE_API_URL}/models`, {
+    headers,
+    // A hung upstream must not freeze /freeflow refresh: abort after
+    // CATALOG_REFRESH_TIMEOUT_MS and fall back to cache below.
+    signal: AbortSignal.timeout(CATALOG_REFRESH_TIMEOUT_MS),
+   });
+   if (res.status === 304) {
+    // Not modified — skip merge, extend timestamp to avoid tight loop
+    if (staleForEtag && Array.isArray(staleForEtag.models)) {
+     try {
+      writeCatalogCache({ ...staleForEtag, timestamp: Date.now() });
+     } catch { }
+    }
+    return aliveCatalog;
+   }
+   if (res.ok) {
+    const newEtag = res.headers.get("etag") ?? res.headers.get("ETag") ?? cachedEtag;
+    const body: unknown = await res.json();
+    let rawList: RawModelItem[] = [];
+    if (Array.isArray(body)) {
+     rawList = body as RawModelItem[];
+    } else if (body !== null && typeof body === "object" && "data" in body) {
+     const dataVal = body.data as unknown;
+     if (Array.isArray(dataVal)) {
+      rawList = dataVal as RawModelItem[];
+     }
+    }
+    if (rawList.length > 0) {
+     const freeRawList = rawList.filter((r) => r && typeof r.id === "string" && isFreeCatalogId(r.id));
+     const fresh = freeRawList.map((r) => enrichModelDef(r, "opencode"));
+     const merged = mergeCatalog(aliveCatalog, fresh);
+     aliveCatalog = merged;
+     writeCatalogCache({
+      timestamp: Date.now(),
+      opencode: fresh.map((m) => m.id),
+      kilo: staleForEtag?.kilo ?? [],
+      models: merged,
+      etag: newEtag ?? cachedEtag,
+     });
+     return aliveCatalog;
+    }
+    // Empty payload but 200 — treat as no-op, return current
+    if (newEtag && newEtag !== cachedEtag && staleForEtag) {
+     writeCatalogCache({ ...staleForEtag, timestamp: Date.now(), etag: newEtag });
+    }
+    return aliveCatalog;
+   }
+  } catch (err) {
+   if ((err as Error)?.name === "AbortError") {
+    logWarn("Catalog refresh timed out — using cached/static fallback", {
+     timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,
+    });
+   } else {
+    logDebug("Conditional catalog fetch failed, falling back to cache", { error: String(err) });
+   }
+  }
+ }
+
+ // Stale cache still better than empty — overlay it on the static base rather
+ // than returning it as the catalog. A cache written before an id existed in
+ // the static list can hold as many entries as the static set while missing
+ // ids we ship today, so no "the cache is big enough" guard can be trusted;
+ // the overlay keeps the static ids and adds whatever the cache knows.
+ if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
+  aliveCatalog = mergeCatalog(staticBase, sanitizeCatalogModels(disk.models));
+  return aliveCatalog;
+ }
+ // No valid fresh cache — try stale disk cache directly (readCatalogCache returns null when expired)
+ try {
+  if (fs.existsSync(CATALOG_CACHE_FILE)) {
+   const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
+   const stale = JSON.parse(raw) as CatalogCacheData;
+   if (Array.isArray(stale.models) && stale.models.length > 0) {
+    aliveCatalog = mergeCatalog(staticBase, sanitizeCatalogModels(stale.models));
+    return aliveCatalog;
+   }
+  }
+ } catch (err) {
+  logDebug("Failed reading stale catalog cache", { error: String(err) });
+ }
+ // No usable cache — return the in-memory static-backed catalog (host will refresh if needed)
+ return aliveCatalog;
+}