pi-freeflow 1.5.0 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-freeflow 🌊
 
-> **21 free models. Up to 1M context. Zero API keys. Infinite scale via your own relay pool.**
+> **25 free models. Up to 1M context. Zero API keys. Infinite scale via your own relay pool.**
 
 Thin by design: model list + dumb relay + log. Host `pi-ai` owns thinking, normalization & provider magic. We just make it free, fast, and unbreakable.
 
@@ -18,7 +18,7 @@ Join devs bypassing rate limits with their own relay pools. BYO, add as many as
 
 | Feature | Description | Value | Cost |
 | :--- | :--- | :--- | :--- |
-| **21 Curated Free Models** | 7 OpenCode Zen + 14 KiloCode Gateway models, up to 1M context & 512K output | Ceiling Unlocked | **$0** |
+| **25 Curated Free Models** | 7 OpenCode Zen + 18 KiloCode Gateway models, up to 1M context & 512K output | Ceiling Unlocked | **$0** |
 | **BYO Relay Pool** | Round-robin load balancing across your Cloudflare Workers & Vercel Edges | Zero Rate Limits | **$0** (your free tiers) |
 | **Adaptive Health & Error Detection** | Auto-cooldown on 429 rate limits, 504 timeouts, and socket drops | 0ms Wasted Latency | **$0** |
 | **Stream Truncation Resilience** | Stateful SSE terminal tracking (`response.failed` / `response.incomplete` injection) | Zero Host Crashes | **$0** |
@@ -26,13 +26,13 @@ Join devs bypassing rate limits with their own relay pools. BYO, add as many as
 | **Auto-Enabled on Session** | Relay stays enabled in `auto` mode on session start and model switch | Zero Friction | **$0** |
 | **Interactive CLI Management** | 10+ `/freeflow` subcommands (`status`, `list`, `use`, `add`, `label`, `remove`, `deploy`, `logs`, `debug`) | Full Control | **$0** |
 | **Dumb Proxy That Never Breaks** | `127.0.0.1:28180`, host-normalized, pathname-guarded `/v1/models` | 100% Uptime | **$0** |
-| **Observable Real Logs** | `~/.pi/agent/pi-freeflow.log`, 5MB auto-rotation, real-time debug toggle | Observable | **$0** |
+| **Observable Real Logs** | `~/.pi/agent/pi-freeflow.log`, 10MB auto-rotation, real-time debug toggle | Observable | **$0** |
 
 Philosophy: **Thin by design.** We only ship model list + relay proxy + log. Host owns thinking & normalization.
 
 ---
 
-### 21 Curated Models, One Command
+### 25 Curated Models, One Command
 
 ```bash
 /model → freeflow → pick
@@ -43,35 +43,39 @@ Optimized for deep reasoning, long-horizon coding & autonomous agentic workflows
 
 | Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| `muse-spark-1.2-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal / low / medium / high / xhigh / max` | ✅ |
-| `mimo-v2.5-free` | Xiaomi MiMo | **1M** (1.048.576) | **131K** (131.072) | `low / medium / high` | ✅ |
-| `laguna-s-2.1-free` | Poolside | **1M** (1.048.576) | **131K** (131.072) | `low / high / max` | ❌ |
-| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `low / high / max` | ❌ |
-| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `low / high / max` | ❌ |
-| `hy3-free` | Tencent Hunyuan | **262K** (262.144) | **262K** (262.144) | `low / high / max` | ❌ |
+| `muse-spark-1.2-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
+| `mimo-v2.5-free` | Xiaomi MiMo | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh`\* | ✅ |
+| `laguna-s-2.1-free` | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal … xhigh` | ❌ |
+| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal … xhigh` | ❌ |
+| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal … xhigh` | ❌ |
+| `hy3-free` | Tencent Hunyuan | **262K** (262.144) | **128K** (128.000) | `minimal … xhigh` | ❌ |
 | `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
 
-#### KiloCode Gateway (14 Models), OpenRouter Compatible
+#### KiloCode Gateway (18 Models), OpenRouter Compatible
 Keyless access with `Bearer kilo-free`. Clean slash-free and colon-free CLI aliases supported.
 
 | Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
 | :--- | :--- | :--- | :--- | :--- | :--- |
 | `dots-3-note-preview` (`dots-studio/...:free`) | Dots Studio | **512K** (512.000) | **512K** (512.000) | `minimal…xhigh`\* | ✅ |
 | `step-3.7-flash` (`stepfun/...:free`) | StepFun | **262K** (262.144) | **262K** (262.144) | `minimal…xhigh`\* | ✅ |
-| `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | **256K** (256.000) | **65K** (65.536) | `minimal…xhigh`\* | ✅ |
-| `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **65K** (65.536) | `minimal…xhigh`\* | ❌ |
-| `nvidia/nemotron-3.5-lightning:free` | NVIDIA | **1M** (1.000.000) | **131K** (131.072) | `minimal…xhigh`\* | ❌ |
+| `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | **256K** (256.000) | **131K** (131.072) | `minimal…xhigh`\* | ✅ |
+| `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal…xhigh`\* | ❌ |
+| `nvidia/nemotron-3.5-lightning:free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
 | `nemotron-3-super` (`nvidia/...:free`) | NVIDIA | **262K** (262.144) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
-| `hy3:free` (`tencent/hy3:free`) | Tencent Hunyuan | **262K** (262.144) | **262K** (262.144) | ❌ *(none sent)* | ❌ |
+| `hy3:free` (`tencent/hy3:free`) | Tencent Hunyuan | **262K** (262.144) | **128K** (128.000) | `minimal…xhigh`\* | ❌ |
 | `north-mini-code` (`cohere/...:free`) | Cohere | **256K** (256.000) | **64K** (64.000) | `minimal…xhigh`\* | ❌ |
-| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **1M** (1.048.576) | **131K** (131.072) | `minimal…xhigh`\* | ❌ |
+| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
 | `laguna-xs-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `lfm-2.5` (`liquid/lfm-2.5-2.6b:free`) | Liquid AI | **128K** (128.000) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `kilo-auto` (`kilo-auto/free`) | Kilo Gateway Auto | **256K** (256.000) | **10K** (10.000) | ❌ *(non-thinking)* | ❌ |
-| `openrouter` (`openrouter/free`) | OpenRouter Free | **200K** (200.000) | **65K** (65.536) | ❌ *(non-thinking)* | ✅ |
+| `lfm-2.5` (`liquid/lfm-2.5-2.6b:free`) | Liquid AI | **65K** (65.536) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `kilo-auto` (`kilo-auto/free`) | Kilo Gateway Auto | **256K** (256.000) | **10K** (10.000) | `minimal…xhigh`\* | ❌ |
+| `openrouter` (`openrouter/free`) | OpenRouter Free | **200K** (200.000) | **65K** (65.536) | `minimal…xhigh`\* | ✅ |
 | `content-safety` (`nvidia/...:free`) | NVIDIA | **128K** (128.000) | **8K** (8.192) | ❌ *(non-thinking)* | ✅ |
+| `longcat-2.0` (`meituan/longcat-2.0-free`) | Meituan | **1M** (1.048.756) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
+| `minimax-m2.7` (`minimax/minimax-m2.7:free`) | MiniMax | **196K** (196.608) | **196K** (196.608) | `minimal…xhigh`\* | ❌ |
+| `minimax-m3` (`minimax/minimax-m3:free`) | MiniMax | **1M** (1.048.576) | **512K** (524.288) | `minimal…xhigh`\* | ❌ |
+| `ling-3.0-flash-fin` (`inclusionai/ling-3.0-flash-fin:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
 
-\* Levels are forwarded as-is through the OpenRouter-style nested `reasoning` parameter; effort mapping is decided by each model. hy3 accepts no reasoning parameter today.
+\* Levels are forwarded as-is through the OpenRouter-style nested `reasoning` parameter; effort mapping is decided by each model. (Verified live 2026-08-29: hy3 accepts flat `reasoning_effort`/nested `reasoning` and returns thinking — README previously said otherwise.) MiMo collapses `minimal→low` and `xhigh→high` upstream, so its selector shows 5 labels but only 3 distinct effort values.
 
 ---
 
@@ -101,12 +105,17 @@ Manage your relay pool directly from the OMP / Pi terminal:
 /freeflow status                  # View active relay, pool status, and candidates
 /freeflow list                    # List all relays with real-time health badges (✓ / ⚠️ [cooling])
 /freeflow use <url|index|label>   # Switch active relay
+/freeflow url <url>               # Set the active relay URL directly
 /freeflow add <url> [label]       # Add new relay to the pool
 /freeflow label <index|url> <name># Assign a friendly label to a relay
 /freeflow remove <index|url|label># Remove a relay from the pool
+/freeflow test <index|url|label>  # Probe a relay for reachability (HTTP 200 + latency)
 /freeflow on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
 /freeflow deploy <platform>       # Guided relay deploy: vercel|cloudflare|deno — token in-memory, auto-adds (Vercel 1M/mo recommended)
 /freeflow logs [lines]            # Inspect recent proxy logs
+/freeflow trace [req-id]          # Tail logs filtered by request correlation ID
+/freeflow refresh                 # Reload the model catalog from live upstreams
+/freeflow update                  # Check for and install a package update
 /freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
 ```
 
@@ -150,26 +159,7 @@ Default ships direct. Add relays via `/freeflow add <url> [label]`.
 ```bash
 /freeflow deploy cloudflare  # prompts token in-memory, auto-adds to pool
 ```
-*Manual fallback:* `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste snippet below → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
-
-```js
-// Only the 2 upstreams pi-freeflow talks to. Anything else = open proxy abuse.
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
-
-export default {
-  async fetch(req) {
-    const target = req.headers.get("x-relay-target");
-    const relayPath = req.headers.get("x-relay-path") || "/";
-    if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400 });
-    const cleanTarget = target.replace(/\/$/, "");
-    if (!ALLOWED_TARGETS.includes(cleanTarget)) return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
-    if (!relayPath.startsWith("/")) return new Response(JSON.stringify({ error: "Bad path" }), { status: 400 });
-    const headers = new Headers(req.headers);
-    headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
-    return fetch(cleanTarget + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
-  },
-};
-```
+*Manual fallback:* `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste the canonical worker source (see "Canonical worker source" below) → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
 
 **Option B: Vercel Edge Relay (1M req/mo) — Auto Deploy**
 ```bash
@@ -178,30 +168,9 @@ export default {
 ```
 *Manual fallback:* Push 2 files (`api/relay.js` + `vercel.json`) to GitHub $\to$ Import on `vercel.com` $\to$ `/freeflow add https://your.vercel.app vercel-relay-1`
 
-```js
-// api/relay.js
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
-export const config = { runtime: "edge" };
-export default async function handler(req) {
-  const target = req.headers.get("x-relay-target");
-  const relayPath = req.headers.get("x-relay-path") || "/";
-  if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) {
-    return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
-  }
-  const headers = new Headers(req.headers);
-  headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
-  const res = await fetch(target.replace(/\/$/, "") + relayPath, {
-    method: req.method,
-    headers,
-    body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined,
-    duplex: "half",
-  });
-  return new Response(res.body, { status: res.status, headers: res.headers });
-}
-```
+For `api/relay.js`, use the canonical worker source (see below); `vercel.json` stays:
 
 ```json
-// vercel.json
 { "rewrites": [{ "source": "/(.*)", "destination": "/api/relay" }] }
 ```
 
@@ -209,22 +178,29 @@ export default async function handler(req) {
 ```bash
 /freeflow deploy deno  # prompts token in-memory, auto-adds to pool
 ```
-*Manual fallback:* `dash.deno.com` → New Project → Playground → paste snippet below → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
+*Manual fallback:* `dash.deno.com` → New Project → Playground → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
 
-```ts
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+**Canonical worker source (all platforms)**
+
+The relay worker template is generated per deployment by `/freeflow deploy` and lives in [`src/deploy.ts`](src/deploy.ts): one hardened core plus thin Vercel / Cloudflare / Deno wrappers. Every deployment embeds its own shared secret and enforces the target allowlist (`https://opencode.ai`, `https://api.kilo.ai`), SSRF/private-host guard, relay-path validation, and a header denylist — `x-relay-auth` is checked by the worker and never forwarded upstream.
 
-Deno.serve(async (req) => {
-  const target = req.headers.get("x-relay-target");
-  const relayPath = req.headers.get("x-relay-path") || "/";
-  if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) {
-    return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
-  }
-  const headers = new Headers(req.headers);
-  headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
-  const res = await fetch(target.replace(/\/$/, "") + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
-  return new Response(res.body, { status: res.status, headers: res.headers });
-});
+```js
+// Minimal Cloudflare illustration. Prefer /freeflow deploy: the generated
+// worker (src/deploy.ts) is the signed/hardened source for all three
+// platforms. This example omits the SSRF guard, path validation, and auth.
+const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+export default {
+  async fetch(req) {
+    const target = req.headers.get("x-relay-target");
+    const relayPath = req.headers.get("x-relay-path") || "/";
+    if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) {
+      return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
+    }
+    const headers = new Headers(req.headers);
+    headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
+    return fetch(target.replace(/\/$/, "") + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
+  },
+};
 ```
 
 **Verify your pool:**
@@ -247,15 +223,15 @@ cat ~/.pi/agent/pi-freeflow.log | tail -n 50
 /freeflow debug on
 ```
 
-Log rotation at 5MB. Clean, parseable, real-time HTTP lifecycle tracking.
+Log rotation at 10MB. Clean, parseable, real-time HTTP lifecycle tracking.
 
 ---
 
 ### Design
 
-This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step and there are no runtime dependencies. Thinking and prompt normalization stay with the host (`pi-ai`).
+This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step. The only runtime dependency is `undici`, which powers the upstream fetch agent. Thinking and prompt normalization stay with the host (`pi-ai`).
 
-Current size: about 4.6k lines including tests. 16 tests pass, typecheck clean.
+Current size: about 11.3k lines including tests. 228 tests pass, typecheck clean.
 
 ---
 
@@ -284,7 +260,7 @@ Contributions welcome — bug fixes, new relay platforms, model additions, docs
 
 #### Prerequisites
 
-- **Node.js ≥ 22.6.0** (uses `--experimental-strip-types`, no build step)
+- **Node.js ≥ 22.19.0** (uses `--experimental-strip-types`, no build step)
 - **pnpm** (package manager)
 
 #### Setup & Verify
@@ -295,7 +271,7 @@ cd pi-freeflow
 pnpm install
 
 # run all three before opening a PR
-pnpm test        # 16 tests across 2 test files
+pnpm test        # 228 tests across 30 test files
 pnpm typecheck   # tsc --noEmit, must pass clean
 pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```
@@ -305,17 +281,17 @@ pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```
 src/
 ├── index.ts          # extension entry, lifecycle hooks
-├── models.ts         # 21-model catalog definitions
+├── models.ts         # 25-model catalog definitions
 ├── catalog.ts        # model catalog cache (24h disk)
 ├── proxy.ts          # local proxy server (127.0.0.1:28180)
 ├── relay.ts          # relay selection & round-robin
 ├── relay-state.ts    # relay pool state, health tracking
-├── rate-limiter.ts   # adaptive cooldown on 429/504/socket errors
+├── rate-limiter.ts   # in-memory sliding rate limiter (200/day, 200/hour)
 ├── stream-pipe.ts    # SSE stream piping & truncation resilience
 ├── commands.ts       # /freeflow CLI subcommands
 ├── deploy.ts         # guided relay deploy (vercel/cloudflare/deno)
-├── config.ts         # relay pool persistence
-├── logger.ts         # file logger with 5MB rotation
+├── config.ts         # constants, whitelists, paths, and runtime settings
+├── logger.ts         # file logger with 10MB rotation
 └── types.ts          # shared type definitions
 extensions/
 └── index.ts          # OMP/Pi extension manifest
@@ -325,7 +301,7 @@ test/
 
 #### Guidelines
 
-- **Stay thin.** No runtime dependencies. No build step. If it belongs in the host (`pi-ai`), don't add it here.
+- **Stay thin.** One runtime dependency (`undici`), no build step. If it belongs in the host (`pi-ai`), don't add it here.
 - **Test what you touch.** Every `src/*.ts` has a matching `test/*.test.ts`. Add or update tests for your change.
 - **Keep model IDs clean.** Slash-free, colon-free aliases for CLI compatibility. See existing patterns in `models.ts`.
 - **One concern per PR.** Bug fix? One PR. New relay platform? Separate PR. Easier to review, faster to merge.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",
@@ -24,7 +24,7 @@
   },
   "homepage": "https://github.com/trefeon/pi-freeflow#readme",
   "engines": {
-    "node": ">=22.6.0"
+    "node": ">=22.19.0"
   },
   "omp": {
     "extensions": [
@@ -52,7 +52,6 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.0",
-    "@earendil-works/pi-coding-agent": "^0.84.3",
     "@types/node": "^22.13.9",
     "typescript": "^5.8.2",
     "vitepress": "^1.6.4"

package/src/catalog.ts

@@ -10,6 +10,7 @@ import path from "node:path";
 import {
 	CATALOG_CACHE_FILE,
 	CATALOG_CACHE_TTL_MS,
+	CATALOG_REFRESH_TIMEOUT_MS,
 	KILO_CHAT_URL,
 	OPENCODE_API_URL,
 	opencodeHeaders,
@@ -17,12 +18,8 @@ import {
 import { log, logDebug, logWarn } from "./logger.ts";
 import {
 	ALL_MODELS,
-	KILO_MODELS,
 	KILO_MODEL_IDS,
-	KNOWN_MODELS,
 	MODEL_MAP,
-	OPENCODE_MODELS,
-	getAllRegisteredModels,
 } from "./models.ts";
 import type {
 	CatalogCacheData,
@@ -37,7 +34,7 @@ import type {
 export const DEAD_MODEL_IDS = new Set<string>(["deepseek-v4-flash-free", "x-preview-f-free"]);
 /**
  * In-memory cache of currently active/available free models.
- * Initialized with all 21 verified models for 0ms instant availability.
+ * Initialized with all 25 verified models for 0ms instant availability.
  */
 let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
 	...m,
@@ -178,9 +175,10 @@ export function readCatalogCache(): CatalogCacheData | null {
 		}
 		const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
 		const data = JSON.parse(raw) as CatalogCacheData;
-		if (Array.isArray(data.models)) {
-			data.models = data.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+		if (!Array.isArray(data.models)) {
+			return null;
 		}
+		data.models = data.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
 		if (Date.now() - data.timestamp < CATALOG_CACHE_TTL_MS) {
 			return data;
 		}
@@ -249,7 +247,12 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 			if (cachedEtag) {
 				headers["If-None-Match"] = cachedEtag;
 			}
-			const res = await fetch(`${OPENCODE_API_URL}/models`, { headers });
+			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)) {
@@ -291,14 +294,20 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 				return aliveCatalog;
 			}
 		} catch (err) {
-			logDebug("Conditional catalog fetch failed, falling back to cache", { error: String(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 = disk.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
-		if (filtered.length >= 21) {
+		if (filtered.length >= ALL_MODELS.length) {
 			aliveCatalog = filtered;
 			return aliveCatalog;
 		}
@@ -310,7 +319,7 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 			const stale = JSON.parse(raw) as CatalogCacheData;
 			if (Array.isArray(stale.models) && stale.models.length > 0) {
 				const filtered = stale.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
-				if (filtered.length >= 21) {
+				if (filtered.length >= ALL_MODELS.length) {
 					aliveCatalog = filtered;
 					return aliveCatalog;
 				}
@@ -319,6 +328,6 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 	} catch (err) {
 		logDebug("Failed reading stale catalog cache", { error: String(err) });
 	}
-	// No valid cache — return in-memory static 21 (host will refresh if needed)
+	// No valid cache — return in-memory static 25 (host will refresh if needed)
 	return aliveCatalog;
 }