pi-freeflow 1.22.2 → 1.22.4

package/src/catalog.ts

@@ -8,39 +8,39 @@ 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,
+ 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,
+ ALL_MODELS,
+ MODEL_MAP,
+ getModelUpstream,
 } from "./models.ts";
 import type {
-	CatalogCacheData,
-	RawModelItem,
-	RegisteredModel,
-	Upstream,
+ 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",
+ "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.
@@ -50,9 +50,9 @@ export const DEAD_MODEL_IDS = new Set<string>([
  * (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);
+ 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
@@ -63,38 +63,41 @@ export function isFreeCatalogId(id: string): boolean {
  * 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) {
-			out.push({ ...known, source: m.source ?? getModelUpstream(m.id) });
-		} else {
-			out.push(m);
-		}
-	}
-	return out;
+ 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),
+ ...m,
+ source: getModelUpstream(m.id),
 }));
 /**
  * Get current in-memory alive catalog
  */
 export function getAliveCatalog(): RegisteredModel[] {
-	return aliveCatalog;
+ return aliveCatalog;
 }
 
 /**
  * Set in-memory alive catalog
  */
 export function setAliveCatalog(catalog: RegisteredModel[]): void {
-	aliveCatalog = catalog;
+ aliveCatalog = catalog;
 }
 
 /**
@@ -105,113 +108,114 @@ export function setAliveCatalog(catalog: RegisteredModel[]): void {
  * Filters pruned dead IDs so they never re-enter via fresh upstream data.
  */
 export function mergeCatalog(
-	base: RegisteredModel[],
-	fresh: RegisteredModel[],
+ 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()]);
+ 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;
-	}
+ 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, "");
+ // 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);
-	});
+ // 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(" ");
+ 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 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");
+ 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 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;
-	}
+ let maxTokens =
+  typeof raw.max_output_tokens === "number"
+   ? raw.max_output_tokens
+   : 65_536;
+ if (idLower.includes("ultra") || idLower.includes("lightning")) {
+  maxTokens = 131_072;
+ }
 
-	const isResponses =
-		raw.id === "muse-spark-1.2-contributor-free" ||
-		raw.id === "muse-spark-1.3-contributor-free" ||
-		raw.id === "cline-free/muse-spark-1.3-contributor";
+ // 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,
-	};
+ 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,
+ };
 }
 
 /**
@@ -220,23 +224,23 @@ export function enrichModelDef(raw: RawModelItem, source: Upstream): RegisteredM
  * 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;
+ 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;
 }
 
 /**
@@ -245,37 +249,37 @@ export function readCatalogCache(): CatalogCacheData | null {
  * 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);
+ 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);
-		}
-	}
+ 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) });
-	}
+ 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) });
+ }
 }
 
 /**
@@ -286,125 +290,129 @@ export function writeCatalogCache(data: CatalogCacheData): void {
  * requests fail.
  */
 export async function refreshCatalog(force = false): Promise<RegisteredModel[]> {
-	// Thin provider: serve fresh disk cache instantly when valid
-	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 = sanitizeCatalogModels(disk.models);
-			return aliveCatalog;
-		}
-	}
+ // 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) });
-		}
-	}
+ // 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) });
-			}
-		}
-	}
+ // 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;
+ // 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;
 }