pi-freeflow 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.40.0
+
+### Minor Changes
+
+- Streaming turns now survive a relay rate limit: a 429 error frame that arrives before any tool call is held, the relay is cooled, and the same turn resumes once on a sibling relay. Pre-stream 429s still roll before any client bytes, and tool-call turns keep the authentic verdict to avoid duplicate execution.
+
+### Patch Changes
+
+- Reconcile the remaining free-model specs with the highest published twin values, keeping lane hard caps authoritative:
+
+  - Cat Jam now advertises its 1,048,576-token window: the endpoint refuses a 1.05M prompt with `context_length_exceeded` (max 1,048,576), and a 900,337-token needle probe recalled correctly.
+  - Nemotron 3 Ultra (both lanes) now declares the 1,000,000-token lane cap; larger prompts are refused.
+  - Nemotron 3.5 and Super now carry the highest published 235,929 output ceiling below the window.
+  - Thinking selectors now expose only the depths published by the free or paid twin's datasheet; unlisted rungs stay locked off. The 3.6/3.8 Qwens add `minimal`, the other OVH reasoning rows expose `medium`, Inkling Small adds `max`, and Exo follows its paid twin's `minimal..xhigh` union.
+  - OVH output ceilings follow the highest published twin value below the window: 235,929 for the 397B and 3.8 Qwens, 65,536 for the 9B, 3.6 and both gpt-oss models, and 32,768 for Mistral and Llama.
+  - Remove Space Bunny: the free endpoint answers `410 ModelDeprecated` and points at `minimax-m3.1-flash-free`.
+  - Declare only text and image inputs. The host catalog has no video or audio input type, so upstream video/audio/PDF support (MiMo, GLM 5.3 Flash, Nemotron Super VL, Nano Omni) is documented in the README instead of being advertised in the picker.
+- Rate-limit rotation is now silent: a relay that answers 429 is cooled and deprioritized without a per-relay warning toast or per-relay WARN line while the pool still has a candidate. A pool-wide 429 burst alert still warns when many relays rate-limit in one minute. The rate-limit message appears only when no relay or direct fallback served the turn, including the existing 403-salvage path.
+- Model specs refreshed against the latest upstream catalogs. Free and paid variants of the same model now share the highest published context window, output ceiling, and input modalities, so a picker entry no longer understates what the model accepts.
+- Drop two Kilo models that stopped answering, so the picker only offers what is actually served: `nvidia/nemotron-3-super-120b-a12b:free` answers `404 Function ... Not found for account ...` from its Nvidia provider, and `thinkingmachines/inkling-small:free` answers `404 The requested model is currently unavailable`. Both verdicts reproduce from two independent egress IPs while the sibling Nvidia ids answer `200` with the same request shape. The catalog is 32 models; both ids stay on the retired list so a stale cache cannot bring them back.
+
 ## 1.39.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # pi-freeflow
 
-> 35 free models with up to 1M context. No API keys to manage. Add your own relays to spread requests across more IPs.
+> 32 free models with up to 1M context. No API keys to manage. Add your own relays to spread requests across more IPs.
 
 Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handles thinking, normalization, and provider behavior.
 
@@ -16,7 +16,7 @@ Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handl
 
 | Feature | What it does | Cost |
 | :--- | :--- | :--- |
-| **35 free models** | 12 from OpenCode Zen, 13 from KiloCode Gateway, 2 from Cline, 8 from OVHcloud AI Endpoints, context windows up to 1M. Full list below. | **$0** |
+| **32 free models** | 11 from OpenCode Zen, 11 from KiloCode Gateway, 2 from Cline, 8 from OVHcloud AI Endpoints, context windows up to 1M. Full list below. | **$0** |
 | **Relay pool** | Route requests through your own relays: a self-hosted egress pool (many egress IPs on one small host) or Cloudflare Workers / Deno Deploy / Vercel Edge workers. Traffic spreads across the pool, or stays on one sticky relay. A relay that rate-limits, times out, or drops the connection cools down while healthy ones take its traffic. | **$0** beyond your host or platforms' free tiers |
 | **Automatic fallback** | When every relay is cooling down, requests go direct to upstream instead of failing. | **$0** |
 | **Short model names** | Most models have a slash-free, colon-free alias, plus an optional `:effort` suffix for thinking depth. You type `freeflow/<name>`; the two Cline models have no alias and must be typed in full. | **$0** |
@@ -54,7 +54,7 @@ omp
 **OMP, one shot:**
 ```bash
 omp -p --model freeflow/deepseek-v4.1-flash-free "build me a SaaS"
-omp -p --model freeflow/space-bunny:high "solve this bug"   # alias + thinking level
+omp -p --model freeflow/longcat:high "solve this bug"   # alias + thinking level
 ```
 
 **Pi, interactive:**
@@ -65,7 +65,7 @@ pi
 
 **Pi, one shot:**
 ```bash
-pi -p --model freeflow/space-bunny:high "solve this bug"
+pi -p --model freeflow/longcat:high "solve this bug"
 ```
 
 Model IDs accept a full canonical ID, a short alias (see the tables below),
@@ -213,51 +213,51 @@ The same command set works identically in OMP and Pi:
 
 ---
 
-### 35 models, one command
+### 32 models, one command
 
 ```bash
 /model → freeflow → pick
 ```
 
-Every model specification is reconciled against [models.dev](https://models.dev/), [OpenRouter](https://openrouter.ai/), and OMP's built-in catalog, configured with the highest verified context, output ceiling, and reasoning capabilities across twin models.
-#### OpenCode Zen (12 models), Chat Completions API
+Every model specification is reconciled against [models.dev](https://models.dev/), [OpenRouter](https://openrouter.ai/), and OMP's built-in catalog on 2026-10-20: a free and a non-free variant of the same model share the highest published context window, output ceiling, and input modalities across its twins. The catalog follows that published spec even where a free lane enforces a lower runtime cap; the authentic upstream error is surfaced above it. (Measured runtime caps: MiMo ~348K, GLM 5.3 Flash ~297K, Laguna S 262K.) Lane-published hard caps stay authoritative where the lane refuses above them: OVH's advertised context windows, the 1,000,000-token Nemotron 3 Ultra ceiling, and Dots3-Note's 393,216 served window (its only provider refused a 460,800 output budget on 2026-10-20).
+
+The host catalog carries text and image inputs only. Upstream video and audio support (MiMo: audio + video; GLM 5.3 Flash: video + PDF; Nemotron Super VL and Nano Omni: video) is therefore not selectable from the picker and is not declared in `input`.
+
+#### OpenCode Zen (11 models), Chat Completions API
 
 Good defaults for long coding sessions and agentic work.
 
 | Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| `cat-jam-free` | Cat Jam | **256K** (262.144) | **131K** (131.072) | `low … max` | ❌ |
-| `mimo-v2.6-flash-free` | Xiaomi MiMo | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh`\* | ✅ |
-| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal … xhigh` | ❌ |
-| `nemotron-3.5-super-vl-free` | NVIDIA | **1M** (1.000.000) | **131K** (131.072) | `minimal … xhigh` | ✅ |
-| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal … xhigh` | ❌ |
+| `cat-jam-free` | Cat Jam | **1M** (1.048.576) | **131K** (131.072) | `low … max` | ❌ |
+| `mimo-v2.6-flash-free` | Xiaomi MiMo | **1M** (1.048.576) | **128K** (131.072) | `minimal … xhigh`\* | ✅ |
+| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **235K** (235.929) | `minimal … xhigh` | ❌ |
+| `nemotron-3.5-super-vl-free` | NVIDIA | **1M** (1.048.576) | **235K** (235.929) | `minimal … xhigh` | ✅ |
+| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **182K** (182.520) | `minimal … xhigh` | ❌ |
 | `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
-| `space-bunny-free` | Stealth preview (lab undisclosed) | **1M** (1.048.576) | **512K** (524.288) | `low … max` | ✅ |
-| `longcat-2.5-preview-free` | Meituan LongCat | **1M** (1.000.000) | **131K** (131.072) | `minimal … max` | ✅ |
-| `glm-5.3-flash-free` | Zhipu AI | **1M** (1.000.000) | **32K** (32.000) | `minimal … max` | ✅ |
+| `longcat-2.5-preview-free` | Meituan LongCat | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
+| `glm-5.3-flash-free` | Zhipu AI | **1M** (1.048.576) | **131K** (131.072) | `low / high / max` | ✅ |
 | `beam-free` | Reflection AI | **1M** (1.048.576) | **131K** (131.072) | `low … max` | ❌ |
-| `exo-free` | Undisclosed | **1M** (1.048.576) | **131K** (131.072) | `high` | ✅ |
-| `deepseek-v4.1-flash-free` | DeepSeek | **1M** (1.000.000) | **384K** (384.000) | `minimal … max` | ✅ |
+| `exo-free` | Undisclosed | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
+| `deepseek-v4.1-flash-free` | DeepSeek | **1M** (1.048.576) | **393K** (393.216) | `low / high / max` | ✅ |
 
-#### KiloCode Gateway (13 models), OpenRouter compatible
+#### KiloCode Gateway (11 models), OpenRouter compatible
 
 Keyless access. Short aliases work for every row (the full ID is in parentheses).
 
 | 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`\* | ✅ |
-| `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`\* | ❌ |
+| `dots-3-note-preview` (`dots-studio/...:free`) | Dots Studio | **384K** (393.216) | **256K** (262.144) | `minimal…xhigh`\* | ✅ |
+| `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | **262K** (262.144) | **65K** (65.536) | `minimal…xhigh`\* | ✅ |
+| `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **182K** (182.520) | `minimal…xhigh`\* | ❌ |
+| `nvidia/nemotron-3.5-lightning:free` | NVIDIA | **1M** (1.000.000) | **235K** (235.929) | `minimal…xhigh`\* | ❌ |
 | `north-mini-code` (`cohere/...:free`) | Cohere | **256K** (256.000) | **64K** (64.000) | `minimal…xhigh`\* | ❌ |
-| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **1M** (1.048.576) | **131K** (131.072) | `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 | **65K** (65.536) | **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) | `minimal…xhigh`\* | ❌ |
 | `openrouter` (`openrouter/free`) | OpenRouter Free | **200K** (200.000) | **65K** (65.536) | `minimal…xhigh`\* | ✅ |
 | `glyph-cluster` (`stealth/glyph-cluster`) | Stealth preview (lab undisclosed) | **256K** (256.000) | **256K** (256.000) | `minimal…xhigh`\* | ❌ |
-| `inkling-small` (`thinkingmachines/inkling-small:free`) | Thinking Machines | **1M** (1.048.576) | **262K** (262.144) | `minimal…xhigh`\* | ✅ |
 
 \* Levels are forwarded as-is through the OpenRouter-style nested `reasoning` parameter; effort mapping is decided by each model. MiMo collapses `minimal→low` and `xhigh→high` upstream, so its selector shows 5 labels but only 3 distinct effort values.
 
@@ -277,19 +277,19 @@ Each account can only be saved once: an extra login for an account you already h
 
 Anonymous access — no account, no key, nothing to sign in to. Direct only (never through the relay pool), because OVH has no per-IP gate for relays to route around. OVH rate-limits anonymous callers per IP, so a burst of parallel subagents can hit `429 API rate limit exceeded`; the model list itself never costs anything.
 
-Pick them with the slash-free short name (the full ID is in parentheses). Only `low` and `high` thinking levels are offered, because those are the two OVH confirmed.
+Pick them with the slash-free short name (the full ID is in parentheses). The lane's rows publish `low`/`medium`/`high`; the 3.6 and 3.8 Qwens add `minimal`, and nothing on this lane offers `xhigh`/`max`.
 All eight talk the normal chat API. Hosts that prefer the responses API work too — the proxy maps that shape to chat and maps the answer back, so tool calls and streamed output behave exactly as they do on the other providers.
 
 | Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| `gpt-oss-120b` (`ovh-free/gpt-oss-120b`) | OpenAI | **128K** (131.072) | **32K** (32.768) | `low/high` | ❌ |
-| `gpt-oss-20b` (`ovh-free/gpt-oss-20b`) | OpenAI | **128K** (131.072) | **32K** (32.768) | `low/high` | ❌ |
-| `qwen3.5-397b` (`ovh-free/Qwen3.5-397B-A17B`) | Alibaba Qwen | **256K** (262.144) | **64K** (65.536) | `low/high` | ✅ |
-| `qwen3.5-9b` (`ovh-free/Qwen3.5-9B`) | Alibaba Qwen | **256K** (262.144) | **64K** (65.536) | `low/high` | ✅ |
-| `qwen3.6-27b` (`ovh-free/Qwen3.6-27B`) | Alibaba Qwen | **256K** (262.144) | **64K** (65.536) | `low/high` | ✅ |
-| `qwen3.8-27b` (`ovh-free/Qwen3.8-27B`) | Alibaba Qwen | **256K** (262.144) | **32K** (32.768) | `low/high` | ✅ |
-| `mistral-small-3.2` (`ovh-free/Mistral-Small-3.2-24B-Instruct-2506`) | Mistral AI | **128K** (131.072) | **16K** (16.384) | ❌ | ✅ |
-| `llama-3.3-70b` (`ovh-free/Meta-Llama-3_3-70B-Instruct`) | Meta | **128K** (131.072) | **16K** (16.384) | ❌ | ❌ |
+| `gpt-oss-120b` (`ovh-free/gpt-oss-120b`) | OpenAI | **128K** (131.072) | **65K** (65.536) | `low/medium/high` | ❌ |
+| `gpt-oss-20b` (`ovh-free/gpt-oss-20b`) | OpenAI | **128K** (131.072) | **65K** (65.536) | `low/medium/high` | ❌ |
+| `qwen3.5-397b` (`ovh-free/Qwen3.5-397B-A17B`) | Alibaba Qwen | **256K** (262.144) | **235K** (235.929) | `low/medium/high` | ✅ |
+| `qwen3.5-9b` (`ovh-free/Qwen3.5-9B`) | Alibaba Qwen | **256K** (262.144) | **65K** (65.536) | `low/medium/high` | ✅ |
+| `qwen3.6-27b` (`ovh-free/Qwen3.6-27B`) | Alibaba Qwen | **256K** (262.144) | **65K** (65.536) | `minimal … high` | ✅ |
+| `qwen3.8-27b` (`ovh-free/Qwen3.8-27B`) | Alibaba Qwen | **256K** (262.144) | **235K** (235.929) | `minimal … high` | ✅ |
+| `mistral-small-3.2` (`ovh-free/Mistral-Small-3.2-24B-Instruct-2506`) | Mistral AI | **128K** (131.072) | **32K** (32.768) | ❌ | ✅ |
+| `llama-3.3-70b` (`ovh-free/Meta-Llama-3_3-70B-Instruct`) | Meta | **128K** (131.072) | **32K** (32.768) | ❌ | ❌ |
 
 ---
 
@@ -382,7 +382,7 @@ pnpm smoke       # verifies extensions/index.ts loads without crashing
 #### Project structure
 
 ```
-├── models.ts                # 35-model catalog definitions
+├── models.ts                # 32-model catalog definitions
 ├── index.ts                 # extension entry, lifecycle hooks
 ├── catalog.ts               # model catalog cache (24h disk)
 ├── proxy.ts                 # local proxy server (127.0.0.1:28180)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.39.0",
+  "version": "1.40.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",

package/src/catalog.ts

@@ -101,6 +101,9 @@ export const DEAD_MODEL_IDS = new Set<string>([
  "inclusionai/ling-3.0-flash-fin:free",
  "mimo-v2.5-free",
  "stealth/space-bunny-alpha",
+ // space-bunny-free: deprecated on the Zen free tier (2026-10-20) — the
+ // endpoint answers 410 ModelDeprecated and points at minimax-m3.1-flash-free.
+ "space-bunny-free",
  "qwen/qwen3.8-27b:free",
  "nvidia/nemotron-3.5-content-safety:free",
  "fledge-alpha-free",
@@ -135,6 +138,15 @@ export const DEAD_MODEL_IDS = new Set<string>([
  // same request shape on the surviving Zen models answers 200. Retired from the
  // static catalog the same day; the Cline Muse Spark 1.3 entry is unaffected.
  "muse-spark-1.2-contributor-free",
+ // nvidia/nemotron-3-super-120b-a12b:free: dead route (2026-10-21) — Kilo answers
+ // 404 "Function '<uuid>': Not found for account ..." from its Nvidia provider on
+ // every attempt, from two independent egress IPs, while sibling Nvidia ids answer
+ // 200 with the same request shape.
+ "nvidia/nemotron-3-super-120b-a12b:free",
+ // thinkingmachines/inkling-small:free: gone upstream (2026-10-21) — Kilo answers
+ // HTTP 404 "The requested model is currently unavailable" (unavailable_model) on
+ // every attempt, from two independent egress IPs; it is no longer served.
+ "thinkingmachines/inkling-small:free",
 ]);
 /**
  * Free-tier allowlist for anything entering the picker via network or stale disk.
@@ -174,7 +186,7 @@ export function sanitizeCatalogModels(models: RegisteredModel[]): RegisteredMode
 }
 /**
  * In-memory cache of currently active/available free models.
- * Initialized with all 35 verified models for 0ms instant availability.
+ * Initialized with all 32 verified models for 0ms instant availability.
  */
 let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
  ...m,

package/src/health.ts

@@ -47,6 +47,8 @@ interface HealthData {
 	lastBytesAt: number;
 	/** Mid-stream turns the upstream model itself failed (model fault, never a relay fault). */
 	midStreamModelFaults: number;
+	/** Mid-stream turns held on a retriable rate-limit frame (whether or not the rescue served). */
+	midStreamRateLimitFaults: number;
 	/** Mid-stream turns cut by the relay/transport (relay fault, rotated away from). */
 	midStreamRelayTruncations: number;
 }
@@ -104,6 +106,7 @@ export function getHealthData(portOverride?: number, activeRequests = 0): Health
 		sseDegraded: sse.degraded,
 		lastBytesAt: getLastForwardedByteAt(),
 		midStreamModelFaults: midStreamFaults.modelFaults,
+		midStreamRateLimitFaults: midStreamFaults.rateLimitFaults,
 		midStreamRelayTruncations: midStreamFaults.relayTruncations,
 	};
 }

package/src/models.ts

@@ -1,10 +1,10 @@
 /**
  * Static model definitions and upstream routing catalogs for pi-freeflow
  *
- * Defines the 35 verified free models (live-verified 2026-10-18):
- * - 12 OpenCode Zen models (all Chat Completions — the last Responses model,
+ * Defines the 32 verified free models (live-verified 2026-10-21):
+ * - 11 OpenCode Zen models (all Chat Completions — the last Responses model,
  *   muse-spark-1.2-contributor-free, was deprecated upstream 2026-10-18)
- * - 13 KiloCode Keyless Gateway models (OpenRouter format)
+ * - 11 KiloCode Keyless Gateway models (OpenRouter format)
  * - 2 Cline direct-only models (per-user pool; one is Responses API)
  * - 8 OVHcloud AI Endpoints models (keyless, direct-only)
  */
@@ -20,11 +20,11 @@ export const OPENCODE_MODELS: ModelDef[] = [
   id: "cat-jam-free",
   name: "Cat Jam [OpenCode]",
   reasoning: true,
-  // Context is 262_144, NOT the 1M an acceptance probe suggests: the gateway
-  // answers 200 to oversized prompts and silently truncates. A needle planted
-  // at the end of a 248,232-token prompt is recalled; at 250,272 it is not.
-  // Cross-checked against the published spec, which agrees.
-  contextWindow: 262_144,
+  // Confirmed 2026-10-20: the endpoint refuses a 1.05M-token prompt with
+  // "maximum context length is 1048576 tokens", and a 900,337-token needle
+  // probe recalled correctly. The earlier ~250K miss was recall, not
+  // truncation.
+  contextWindow: 1_048_576,
   maxTokens: 131_072,
   input: ["text"],
   // Effort ladder live-probed 2026-10-16: the gateway enumerates
@@ -46,9 +46,14 @@ export const OPENCODE_MODELS: ModelDef[] = [
   id: "mimo-v2.6-flash-free",
   name: "MiMo V2.6 Flash [OpenCode]",
   reasoning: true,
+  // Built-in catalog spec: 1,048,576 context / 131,072 output (the origin
+  // model and every paid twin agree). The free lane enforces a lower runtime
+  // cap in practice (measured ~348K; 349K is refused), but the catalog follows
+  // the model's built-in highest spec, so the authentic upstream error is what
+  // a caller sees above the lane's cap.
   contextWindow: 1_048_576,
   maxTokens: 131_072,
- input: ["text", "image", "video"],
+ input: ["text", "image"],
   thinkingLevelMap: {
    off: null,
    minimal: "low",
@@ -63,8 +68,11 @@ export const OPENCODE_MODELS: ModelDef[] = [
   id: "nemotron-3-ultra-free",
   name: "Nemotron 3 Ultra [OpenCode]",
   reasoning: true,
+  // The lane itself caps at 1,000,000 (a 1.29M-token request is refused with
+  // "maximum context length is 1000000 tokens"); the 1,048,576 figure belongs
+  // to a different provider row and is not served here.
   contextWindow: 1_000_000,
-  maxTokens: 128_000,
+  maxTokens: 182_520,
   input: ["text"],
   thinkingLevelMap: {
    off: null,
@@ -81,7 +89,9 @@ export const OPENCODE_MODELS: ModelDef[] = [
   name: "Nemotron 3.5 Lightning [OpenCode]",
   reasoning: true,
   contextWindow: 1_000_000,
-  maxTokens: 262_144,
+  // Highest published output below the window (OpenRouter/Kilo paid twins);
+  // the 262,144 figures repeat the context as the output cap.
+  maxTokens: 235_929,
   input: ["text"],
   thinkingLevelMap: {
    off: null,
@@ -100,11 +110,15 @@ export const OPENCODE_MODELS: ModelDef[] = [
   // merge registered it via the enrichModelDef heuristic, which guesses
   // reasoning:false and no effort map for this id (no magic substring) — that
   // is why the picker offered no thinking levels at all.
-  // Context: models.dev's opencode twin and the NVIDIA family origin both
-  // publish 1,048,576; declared 1,000,000 like its Zen siblings, and no
-  // recall probe has raised it. maxTokens 131,072 per models.dev — the
-  // gateway accepted 131,072 through 524,288 on probe, and acceptance is not
-  // a cap, so the published figure stays the budget.
+  // Context: 1,048,576 — the value both the models.dev opencode twin and the
+  // NVIDIA family origin publish, adopted 2026-10-20 (this entry previously
+  // carried the round 1M). maxTokens 235,929 is the highest output ceiling
+  // published across the free and paid twins; the gateway also accepted
+  // 131,072 through 524,288 on probe, and acceptance is not a cap, so the
+  // published figure stays the budget.
+  // The upstream twin advertises video, but the host's ModelInputType has no
+  // video member, so only text and image are declared. Video remains
+  // documented in the README; it is not selectable in the picker.
   // Effort ladder probed level-by-level 2026-10-16: minimal/low/medium/high/
   // xhigh all answer 200 with reasoning (an unsupported value answers 400, so
   // the gateway validates per model); `max` also 200s but stays hidden
@@ -116,8 +130,8 @@ export const OPENCODE_MODELS: ModelDef[] = [
   id: "nemotron-3.5-super-vl-free",
   name: "Nemotron 3.5 Super VL [OpenCode]",
   reasoning: true,
-  contextWindow: 1_000_000,
-  maxTokens: 131_072,
+  contextWindow: 1_048_576,
+  maxTokens: 235_929,
   input: ["text", "image"],
   thinkingLevelMap: {
    off: null,
@@ -146,28 +160,13 @@ export const OPENCODE_MODELS: ModelDef[] = [
    max: "max",
   },
  },
- {
-  id: "space-bunny-free",
-  name: "Space Bunny Free [OpenCode]",
-  reasoning: true,
-  contextWindow: 1_048_576,
-  maxTokens: 524_288,
- input: ["text", "image", "video"],
-  thinkingLevelMap: {
-   off: null,
-   minimal: null,
-   low: "low",
-   medium: "medium",
-   high: "high",
-   xhigh: "xhigh",
-   max: "max",
-  },
- },
  {
   id: "longcat-2.5-preview-free",
   name: "LongCat 2.5 Preview [OpenCode]",
   reasoning: true,
-  contextWindow: 1_000_000,
+  // Raised 2026-10-20 (spec reconciliation): 1,048,576 ctx per the published
+  // twin, replacing the round 1M this entry used to declare.
+  contextWindow: 1_048_576,
   maxTokens: 131_072,
   input: ["text", "image"],
   thinkingLevelMap: {
@@ -177,41 +176,44 @@ export const OPENCODE_MODELS: ModelDef[] = [
    medium: "medium",
    high: "high",
    xhigh: "xhigh",
-   max: "max",
+   max: null,
   },
  },
  {
   // Added 2026-10-16 (issue #71 drift): Zen v1.19.2 added this free id;
   // served through the fingerprint path (chat 200 with tools + stream).
-  // Not published on pi.dev yet, and models.dev's 200,000 context is
-  // contradicted by probe: a marker planted at 90% depth (~250K words) is
-  // recalled, and only above ~1M words does the gateway refuse with
-  // context_length_exceeded. Declared 1,000,000 like its Zen siblings and
-  // the Kilo twin (z-ai/glm-5.3-flash, 1,048,576 in this catalog); the
-  // 450K/700K-word recall probes timed out upstream and stayed inconclusive.
-  // maxTokens 32,000 per models.dev — the gateway accepted up to 131,072,
-  // and acceptance is not a cap, so the published figure stays the budget.
-  // Effort ladder probed level-by-level 2026-10-16: minimal/low/medium/high/
-  // xhigh/max all answer 200 (an unsupported value answers 400
-  // [invalid_value], so the gateway validates per model), and minimal vs max
-  // visibly changes reasoning length. Chat is the only native shape
-  // (/v1/responses answers 400 "Model does not support this protocol"),
-  // so `api` stays unset. Vision verified live (a 1x1 PNG reads back as a
-  // colour); video/pdf from the published entry stay unverified and are not
-  // offered.
+  // Context is 1,048,576 — the published twin value, adopted 2026-10-20
+  // (models.dev's 200,000 figure for the free id is a stale under-report: a
+  // marker planted at 90% depth of a ~250K-word prompt is recalled, and only
+  // above ~1M words does the gateway refuse with context_length_exceeded).
+  // It now matches the non-free twin (z-ai/glm-5.3-flash, Cline lane,
+  // 1,048,576 in this catalog); the 450K/700K-word recall probes timed out upstream and stayed
+  // inconclusive. maxTokens 131,072 is the highest output published across the
+  // twins — models.dev's free entry claims only 32,000, while the gateway
+  // accepted up to 131,072; acceptance is not a cap, so the twin figure stays
+  // the budget.
+  // Effort ladder: the free and paid datasheets both publish low/high/max
+  // (models.dev opencode + OMP's committed row); the other rungs stay null.
+  // Chat is the only native shape (/v1/responses answers 400
+  // "Model does not support this protocol"), so `api` stays unset. Vision is
+  // published. Video and PDF are documented upstream capabilities, but the
+  // host carries no input type for them, so neither is declared.
   id: "glm-5.3-flash-free",
   name: "GLM-5.3 Flash [OpenCode]",
   reasoning: true,
-  contextWindow: 1_000_000,
-  maxTokens: 32_000,
+  // Built-in catalog spec: 1,048,576 context. The free lane's runtime cap is
+  // lower (296,517 accepted, 298,556 refused), but the catalog follows the
+  // model's built-in highest spec and surfaces the upstream error.
+  contextWindow: 1_048_576,
+  maxTokens: 131_072,
   input: ["text", "image"],
   thinkingLevelMap: {
    off: null,
-   minimal: "minimal",
+   minimal: null,
    low: "low",
-   medium: "medium",
+   medium: null,
    high: "high",
-   xhigh: "xhigh",
+   xhigh: null,
    max: "max",
   },
  },
@@ -263,47 +265,54 @@ export const OPENCODE_MODELS: ModelDef[] = [
   contextWindow: 1_048_576,
   maxTokens: 131_072,
   input: ["text", "image"],
+  // The free datasheet lists only `high`, but the paid twin publishes
+  // minimal..xhigh, so the shared-model union exposes those rungs; `max` is
+  // not published by either and stays null.
   thinkingLevelMap: {
    off: null,
-   minimal: null,
-   low: null,
-   medium: null,
+   minimal: "minimal",
+   low: "low",
+   medium: "medium",
    high: "high",
-   xhigh: null,
+   xhigh: "xhigh",
    max: null,
   },
  },
 {
   // Added 2026-10-15: new free model on the OpenCode Zen lane. Live-verified by
   // probe, NOT copied from the published catalog — the entry for this exact
-  // free id claims 200,000 context, which the gateway contradicts (see below).
+  // free id claimed 200,000 context, which the gateway contradicts (see below).
+  // The reconciled twin spec (2026-10-20) now publishes the full 1M, so the
+  // declared number is the 1,048,576 the twin states rather than the round 1M
+  // this entry used to carry.
   id: "deepseek-v4.1-flash-free",
   name: "DeepSeek V4.1 Flash [OpenCode]",
   reasoning: true,
-  // 1,048,576 measured, not assumed: a marker planted mid-prompt is still
-  // recalled through prompt_tokens=1,030,800, and the gateway turns an
-  // oversized request away with an empty-bodied 400 somewhere above ~1.05M.
-  // The published 200k belongs to the paid deepseek-v4-flash-free, a different
-  // model with a confusingly similar name. Acceptance is not capability; here
-  // the two agree, which is why this is the declared number.
-  contextWindow: 1_000_000,
-  // 384,000 output tokens per https://models.dev/models/deepseek/deepseek-v4.1-flash/
-  // and live gateway boundary probe (gateway accepts up to 393,216 = 384KiB, rejects 393,217+ with 400).
-  maxTokens: 384_000,
+  // 1,048,576, matching both the published twin and the probe: a marker
+  // planted mid-prompt is still recalled through prompt_tokens=1,030,800, and
+  // the gateway turns an oversized request away with an empty-bodied 400
+  // somewhere above ~1.05M. The stale 200k figure described a different,
+  // confusingly similar paid id; the reconciled twin now agrees with the probe.
+  contextWindow: 1_048_576,
+  // 393,216 output tokens: the live gateway boundary (it accepts 393,216 =
+  // 384 * 1024 and rejects 393,217+ with 400), which is also the highest
+  // figure published across the twins — models.dev rounds it down to 384,000,
+  // and the boundary probe is what the request budget is set to.
+  maxTokens: 393_216,
   // Chat Completions only — a Responses-shaped request is refused with
   // 400 ModelProtocolUnsupported. `api` left unset, which means chat.
   input: ["text", "image"],
   // Vision verified live (a 1x1 PNG reads back as "Pink"). Video is not
   // advertised for this model upstream, so it is not offered here.
-  // Every effort level is accepted and visibly changes reasoning length, so
-  // the whole ladder stays selectable; `off` is always null.
+  // Effort ladder: both datasheets publish exactly low/high/max; the other
+  // rungs stay null instead of exposing an unlisted value.
   thinkingLevelMap: {
    off: null,
-   minimal: "minimal",
+   minimal: null,
    low: "low",
-   medium: "medium",
+   medium: null,
    high: "high",
-   xhigh: "xhigh",
+   xhigh: null,
    max: "max",
   },
 },
@@ -333,10 +342,15 @@ const KILO_REASONING_MAP: ThinkingLevelMap = {
 export const KILO_MODELS: ModelDef[] = [
  {
   id: "dots-studio/dots-3-note-preview:free",
-  name: "Dots3-Note Preview (512K) [Kilo]",
-  reasoning: true,
-  contextWindow: 512_000,
-  maxTokens: 512_000,
+  name: "Dots3-Note Preview (384K) [Kilo]",
+  reasoning: true,
+  // Kilo publishes 512,000 ctx / 460,800 out, but the only provider behind
+  // this free id (atlas-cloud) serves a 393,216-token total window. Re-probed
+  // 2026-10-20: with a 20-token prompt, max_tokens 393,195 answers 200 and
+  // 460,800 answers 400 "bad request". Declared values are the served window
+  // and an output budget that keeps prompt headroom under it.
+  contextWindow: 393_216,
+  maxTokens: 262_144,
   input: ["text", "image"],
   thinkingFormat: "openrouter",
   thinkingLevelMap: KILO_REASONING_MAP,
@@ -345,9 +359,12 @@ export const KILO_MODELS: ModelDef[] = [
   id: "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
   name: "Nemotron 3 Nano Omni [Kilo]",
   reasoning: true,
-  contextWindow: 256_000,
-  maxTokens: 131_072,
- input: ["text", "image", "video"],
+  // Reconciled 2026-10-20: 262,144 ctx and 65,536 output per the model's own
+  // published spec; the previous 256,000 / 131,072 pair was a rounded-down
+  // context with an output figure the spec does not carry.
+  contextWindow: 262_144,
+  maxTokens: 65_536,
+ input: ["text", "image"],
   thinkingFormat: "openrouter",
   thinkingLevelMap: KILO_REASONING_MAP,
  },
@@ -355,8 +372,10 @@ export const KILO_MODELS: ModelDef[] = [
   id: "nvidia/nemotron-3-ultra-550b-a55b:free",
   name: "Nemotron 3 Ultra 550B [Kilo]",
   reasoning: true,
+  // The gateway caps this id at 1,000,000 (a 1.11M-token request is refused
+  // with "maximum context length is 1000000 tokens").
   contextWindow: 1_000_000,
-  maxTokens: 128_000,
+  maxTokens: 182_520,
   input: ["text"],
   thinkingFormat: "openrouter",
   thinkingLevelMap: KILO_REASONING_MAP,
@@ -366,17 +385,9 @@ export const KILO_MODELS: ModelDef[] = [
   name: "Nemotron 3.5 Lightning [Kilo]",
   reasoning: true,
   contextWindow: 1_000_000,
-  maxTokens: 262_144,
-  input: ["text"],
-  thinkingFormat: "openrouter",
-  thinkingLevelMap: KILO_REASONING_MAP,
- },
- {
-  id: "nvidia/nemotron-3-super-120b-a12b:free",
-  name: "Nemotron 3 Super 120B [Kilo]",
-  reasoning: true,
-  contextWindow: 262_144,
-  maxTokens: 262_144,
+  // Highest published output below the window (OpenRouter/Kilo paid twins);
+  // the 262,144 figures repeat the context as the output cap.
+  maxTokens: 235_929,
   input: ["text"],
   thinkingFormat: "openrouter",
   thinkingLevelMap: KILO_REASONING_MAP,
@@ -395,8 +406,11 @@ export const KILO_MODELS: ModelDef[] = [
   id: "poolside/laguna-s-2.1:free",
   name: "Laguna S 2.1 [Kilo]",
   reasoning: true,
-  contextWindow: 262_144,
-  maxTokens: 32_768,
+  // Built-in catalog spec: 1,048,576 context. The free gateway's runtime cap
+  // is 262,144; the catalog follows the model's built-in highest spec and
+  // surfaces the upstream error above that cap.
+  contextWindow: 1_048_576,
+  maxTokens: 131_072,
   input: ["text"],
   thinkingFormat: "openrouter",
   thinkingLevelMap: KILO_REASONING_MAP,
@@ -415,7 +429,9 @@ export const KILO_MODELS: ModelDef[] = [
   id: "liquid/lfm-2.5-2.6b:free",
   name: "Liquid LFM 2.5 [Kilo]",
   reasoning: true,
-  contextWindow: 65_536,
+  // Raised 2026-10-20 to the 128,000 ctx the published twin advertises; the
+  // 32,768 output ceiling is unchanged.
+  contextWindow: 128_000,
   maxTokens: 32_768,
   input: ["text"],
   thinkingFormat: "openrouter",
@@ -441,16 +457,6 @@ export const KILO_MODELS: ModelDef[] = [
   thinkingFormat: "openrouter",
   thinkingLevelMap: KILO_REASONING_MAP,
  },
- {
-  id: "thinkingmachines/inkling-small:free",
-  name: "Inkling Small [Kilo]",
-  reasoning: true,
-  contextWindow: 1_048_576,
-  maxTokens: 262_144,
-  input: ["text", "image"],
-  thinkingFormat: "openrouter",
-  thinkingLevelMap: KILO_REASONING_MAP,
- },
  {
   // Added 2026-10-09: live on Kilo free list (isFree:true, 0/0 pricing,
   // 256K ctx) + keyless chat 200.
@@ -496,7 +502,7 @@ export const CLINE_MODELS: ModelDef[] = [
   contextWindow: 1_048_576,
   maxTokens: 131_072,
   api: "openai-responses",
- input: ["text", "image", "video"],
+ input: ["text", "image"],
   thinkingLevelMap: {
    off: null,
    minimal: "minimal",
@@ -513,7 +519,7 @@ export const CLINE_MODELS: ModelDef[] = [
   reasoning: true,
  contextWindow: 1_048_576,
   maxTokens: 131_072,
- input: ["text", "image", "video"],
+ input: ["text", "image"],
   thinkingLevelMap: CLINE_FLASH_REASONING_MAP,
  },
 ];
@@ -530,7 +536,22 @@ const OVH_REASONING_MAP: ThinkingLevelMap = {
  off: null,
  minimal: null,
  low: "low",
- medium: null,
+ medium: "medium",
+ high: "high",
+ xhigh: null,
+ max: null,
+};
+
+/**
+ * Qwen3.6/Qwen3.8 on OVH publish one extra rung: models.dev's ovhcloud row
+ * lists none/minimal/low/medium/high, unlike the 3.5 pairs and gpt-oss which
+ * start at low. No xhigh/max on either.
+ */
+const OVH_QWEN_REASONING_MAP: ThinkingLevelMap = {
+ off: null,
+ minimal: "minimal",
+ low: "low",
+ medium: "medium",
  high: "high",
  xhigh: null,
  max: null,
@@ -555,14 +576,15 @@ export const OVH_MODEL_PREFIX = "ovh-free/";
  * natively too (with store:false injected). Anthropic messages is not served
  * (`/v1/messages` answers 404 unknown_url upstream).
  *
- * Specs (measured live 2026-10-13 and cross-checked against every twin
- * provider carrying a spec): contextWindow is OVH's advertised value;
- * maxTokens is deliberately the conservative FLOOR across twin providers —
- * per-provider output caps for the same model range from 4K to 256K, and a
- * cap that is too low never breaks a request while one that is too high lets
- * a host ask for an output the provider refuses. OVH itself enforces only
- * `context - prompt` (verified by binary search), so these are safe request
- * budgets rather than a refusal boundary.
+ * Specs (datasheets only, reconciled 2026-10-20): contextWindow is OVH's own
+ * advertised value — the lane hard-caps there, so a twin advertising a larger
+ * window on another provider is not served here and must not be copied in.
+ * maxTokens is the highest output published by a twin below the window (the
+ * `/v1/models` max_completion_tokens field repeats the context, so that echo
+ * is discarded): 235,929 for the 397B and 3.8, 65,536 for the 9B, 3.6 and
+ * both gpt-oss models. Effort rungs come from models.dev's ovhcloud rows,
+ * not from wire probes: gpt-oss and the 3.5 Qwens list low/medium/high, the
+ * 3.6/3.8 add minimal.
  *
  * Vision was probed with a generated solid-colour PNG sent as a data URL,
  * twice with two different colours to defeat a memorised answer: the four
@@ -578,7 +600,7 @@ export const OVH_MODELS: ModelDef[] = [
   name: "GPT-OSS 120B [OVH]",
   reasoning: true,
   contextWindow: 131_072,
-  maxTokens: 32_768,
+  maxTokens: 65_536,
   input: ["text"],
   thinkingLevelMap: OVH_REASONING_MAP,
  },
@@ -587,7 +609,7 @@ export const OVH_MODELS: ModelDef[] = [
   name: "GPT-OSS 20B [OVH]",
   reasoning: true,
   contextWindow: 131_072,
-  maxTokens: 32_768,
+  maxTokens: 65_536,
   input: ["text"],
   thinkingLevelMap: OVH_REASONING_MAP,
  },
@@ -596,7 +618,7 @@ export const OVH_MODELS: ModelDef[] = [
   name: "Qwen3.5 397B A17B [OVH]",
   reasoning: true,
   contextWindow: 262_144,
-  maxTokens: 65_536,
+  maxTokens: 235_929,
   input: ["text", "image"],
   thinkingLevelMap: OVH_REASONING_MAP,
  },
@@ -616,23 +638,23 @@ export const OVH_MODELS: ModelDef[] = [
   contextWindow: 262_144,
   maxTokens: 65_536,
   input: ["text", "image"],
-  thinkingLevelMap: OVH_REASONING_MAP,
+  thinkingLevelMap: OVH_QWEN_REASONING_MAP,
  },
  {
   id: "ovh-free/Qwen3.8-27B",
   name: "Qwen3.8 27B [OVH]",
   reasoning: true,
   contextWindow: 262_144,
-  maxTokens: 32_768,
+  maxTokens: 235_929,
   input: ["text", "image"],
-  thinkingLevelMap: OVH_REASONING_MAP,
+  thinkingLevelMap: OVH_QWEN_REASONING_MAP,
  },
  {
   id: "ovh-free/Mistral-Small-3.2-24B-Instruct-2506",
   name: "Mistral Small 3.2 24B [OVH]",
   reasoning: false,
   contextWindow: 131_072,
-  maxTokens: 16_384,
+  maxTokens: 32_768,
   input: ["text", "image"],
  },
  {
@@ -640,7 +662,7 @@ export const OVH_MODELS: ModelDef[] = [
   name: "Meta Llama 3.3 70B Instruct [OVH]",
   reasoning: false,
   contextWindow: 131_072,
-  maxTokens: 16_384,
+  maxTokens: 32_768,
   input: ["text"],
  },
 ];
@@ -672,16 +694,13 @@ export const MODEL_ALIASES: Record<string, string> = {
  "nemotron-3-nano-omni": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
  "nemotron-3-ultra-550b": "nvidia/nemotron-3-ultra-550b-a55b:free",
  "nemotron-3.5-lightning": "nvidia/nemotron-3.5-lightning:free",
- "nemotron-3-super": "nvidia/nemotron-3-super-120b-a12b:free",
  "north-mini-code": "cohere/north-mini-code:free",
  "lfm-2.5": "liquid/lfm-2.5-2.6b:free",
  "glm-5.3-flash": "glm-5.3-flash-free",
  "exo": "exo-free",
  "glyph-cluster": "stealth/glyph-cluster",
- "inkling-small": "thinkingmachines/inkling-small:free",
  "mimo-v2.6-flash": "mimo-v2.6-flash-free",
  "nemotron-3.5-super-vl": "nemotron-3.5-super-vl-free",
- "space-bunny": "space-bunny-free",
  "longcat-2.5-preview": "longcat-2.5-preview-free",
  "longcat": "longcat-2.5-preview-free",
  "beam": "beam-free",
@@ -739,7 +758,7 @@ export const OVH_MODEL_IDS = new Set<string>([
   .map(([alias]) => alias),
 ]);
 /**
- * Combined list of all 35 static free models (canonical)
+ * Combined list of all 34 static free models (canonical)
  */
 export const ALL_MODELS: ModelDef[] = [...OPENCODE_MODELS, ...KILO_MODELS, ...CLINE_MODELS, ...OVH_MODELS];
 

package/src/proxy.ts

@@ -1794,25 +1794,42 @@ export function startProxy(
           streamCloak,
           {
            upstreamContentType: response.headers.get("content-type"),
-           refire: async () => {
+           refire: async (reason) => {
             if (midStreamRefires >= 1) return null;
             midStreamRefires += 1;
             const cutter = servedIssuer ?? "direct";
+            const why =
+             reason === "rate_limit"
+              ? "rate-limited"
+              : reason === "model"
+               ? "model-failed"
+               : "truncated";
             log(
-             "warn",
-             `responses stream truncated on ${cutter === "direct" ? "direct upstream" : `relay ${cutter}`} — re-firing once on next relay`,
-             { model: (parsedBody as Record<string, unknown> | null)?.model, path: req.url, relay: cutter },
+             reason === "rate_limit" ? "info" : "warn",
+             `responses stream ${why} on ${cutter === "direct" ? "direct upstream" : `relay ${cutter}`} — re-firing once on next relay`,
+             { model: (parsedBody as Record<string, unknown> | null)?.model, path: req.url, relay: cutter, reason },
              reqId,
             );
             let retryRes: Response;
             // Mark the cutter BEFORE re-sending: candidate ordering partitions
             // healthy-first, so only a pre-marked (cooling) cutter guarantees
             // the re-fire rolls to a sibling instead of retrying the relay
-            // that just dropped us. A mark here is deserved either way — the
-            // relay demonstrably cut a live stream. (If the re-fire itself
-            // finds nothing usable, the pipe fallthrough may add its own mark
-            // on socket-error paths; bounded by the 4x escalation cap.)
-            if (cutter !== "direct") markRelayFailure(cutter, 0, "stream truncated mid-stream");
+            // that just dropped us. A 429 cools for the rate-limit window; a
+            // truncation/model fault keeps the existing relay-rotation mark.
+            // (If the re-fire itself finds nothing usable, the pipe
+            // fallthrough may add its own mark on socket-error paths; bounded
+            // by the 4x escalation cap.)
+            if (cutter !== "direct") {
+             markRelayFailure(
+              cutter,
+              reason === "rate_limit" ? 429 : 0,
+              reason === "rate_limit"
+               ? "upstream rate-limited mid-stream"
+               : reason === "model"
+                ? "upstream model failed mid-stream"
+                : "stream truncated mid-stream",
+             );
+            }
             try {
              retryRes = await sendViaRelay(bodyForUpstream);
              if (responsesRequest) {

package/src/relay.ts

@@ -186,6 +186,8 @@ export async function relayFetch(
 	const disabledRelays: string[] = [];
 	/** Bare-500 roll-once cap: one extra attempt per relayFetch turn. */
 	let sawBare500 = false;
+	/** True only while every candidate that produced a response answered 429. */
+	let rateLimitOnly = true;
 	const u = new URL(url);
 	const relayTarget = `${u.protocol}//${u.host}`;
 	const relayPath = `${u.pathname}${u.search}`;
@@ -218,6 +220,7 @@ export async function relayFetch(
 	for (let i = 0; i < candidates.length; i++) {
 		if (hedgeSkipNext) {
 			hedgeSkipNext = false;
+			rateLimitOnly = false;
 			continue;
 		}
 		let targetUrl = candidates[i];
@@ -385,6 +388,7 @@ export async function relayFetch(
 			// Not a relay health signal, so no failure marking — try the next
 			// relay (a different host may accept it), else the direct fallback.
 			if (res.status === 413) {
+				rateLimitOnly = false;
 				lastResponse?.body?.cancel().catch(() => {});
 				lastResponse = res;
 				lastResponseRelay = targetUrl;
@@ -418,6 +422,7 @@ export async function relayFetch(
 					!res.headers.get("content-type")?.includes("json"));
 
 			if (isRelayEdge404) {
+				rateLimitOnly = false;
 				markRelayFailure(targetUrl, 404, "Deployment or route not found on relay host");
 				lastResponse?.body?.cancel().catch(() => {});
 				lastResponse = res;
@@ -454,6 +459,7 @@ export async function relayFetch(
 					disabledBody = null;
 				}
 				if (isRelayDeploymentDisabled(res, disabledBody)) {
+					rateLimitOnly = false;
 					markRelayFailure(targetUrl, 402, "Deployment disabled (DEPLOYMENT_DISABLED) on relay host");
 					disabledRelays.push(targetUrl);
 					lastResponse?.body?.cancel().catch(() => {});
@@ -481,12 +487,29 @@ export async function relayFetch(
 				lastResponse?.body?.cancel().catch(() => {});
 				lastResponse = res;
 				lastResponseRelay = targetUrl;
+				if (res.status === 429) {
+					// A 429 is a transient per-relay rate limit, not a terminal
+					// verdict: the request is already moving to the next candidate.
+					// Keep the per-relay rotation silent (no warning toast, no
+					// per-relay WARN line) so the host never flashes "rate limited"
+					// while a sibling relay serves. A pool-wide 429 burst alert may
+					// still fire from markRelayFailure; the final verdict is logged
+					// once when the pool and direct fallback cannot serve the turn.
+					log(
+						"info",
+						`relay ${targetUrl} rate-limited in ${elapsed}s — auto-rotating to next relay`,
+						{ upstream: url, status: 429 },
+						rid,
+					);
+					continue;
+				}
 				log(
 					"warn",
 					`relay ${targetUrl} returned HTTP ${res.status} in ${elapsed}s — rolling to next relay`,
 					{ upstream: url, status: res.status },
 					rid,
 				);
+				rateLimitOnly = false;
 				const now = Date.now();
 				if (now - lastRollNotify > ROLL_NOTIFY_MS) {
 					lastRollNotify = now;
@@ -502,6 +525,7 @@ export async function relayFetch(
 			// relay-fault signal (413 precedent: roll without health penalty), so
 			// retry once on the next candidate instead of surfacing.
 			if (res.status === 500) {
+				rateLimitOnly = false;
 				if (!sawBare500) {
 					sawBare500 = true;
 					lastResponse?.body?.cancel().catch(() => {});
@@ -552,6 +576,7 @@ export async function relayFetch(
 			// below instead of cooling a healthy relay. Non-401/403 client errors
 			// keep their non-penalizing terminal path below too.
 			if (res.status === 403 || (res.status === 401 && (await isRelayAuthRejection(res)))) {
+				rateLimitOnly = false;
 				const authRejected = res.status === 401;
 				markRelayFailure(
 					targetUrl,
@@ -643,6 +668,7 @@ export async function relayFetch(
 			}
 			const elapsed = ((Date.now() - attemptStart) / 1000).toFixed(1);
 			lastError = err;
+			rateLimitOnly = false;
 			const errMsg =
 				(err as Error)?.name === "AbortError"
 					? `relay header timeout (${Math.round(UPSTREAM_HEADER_TIMEOUT_MS / 1000)}s exceeded)`
@@ -661,10 +687,21 @@ export async function relayFetch(
 	// Full fallback: attempt direct fetch to upstream
 	const directStart = Date.now();
 	try {
-		log("warn", "relays bypassed/exhausted — attempting direct fetch to upstream", {
-			upstream: url,
-			sizeKB: bodySizeKB,
-		}, rid);
+		// A pool that only produced 429s is still in the middle of a transient
+		// rate-limit episode; trying direct is recovery, not a warning-worthy
+		// failure. Other exhaustion causes keep their WARN.
+		const exhaustedByRateLimit = lastResponse?.status === 429 && rateLimitOnly;
+		log(
+			exhaustedByRateLimit ? "info" : "warn",
+			exhaustedByRateLimit
+				? "all relays rate-limited — trying direct upstream"
+				: "relays bypassed/exhausted — attempting direct fetch to upstream",
+			{
+				upstream: url,
+				sizeKB: bodySizeKB,
+			},
+			rid,
+		);
 
 		const directHeaders = new Headers(opts.headers);
 		directHeaders.delete("x-relay-target");

package/src/stream-pipe.ts

@@ -80,6 +80,63 @@ const DETERMINISTIC_FAILURE_MARKERS = [
  "moderation",
 ];
 
+/**
+ * A 429-shaped mid-stream error frame is a per-egress rate limit, not a
+ * terminal verdict: another relay IP may serve the same turn immediately.
+ * Kept separate from isTransientModelFailureFrame (which owns model flakes),
+ * and still vetoed by hard request/auth/quota verdicts so a billable or
+ * malformed request is never replayed as relay trouble.
+ */
+const RATE_LIMIT_MARKERS = [
+ "rate_limit",
+ "rate limit",
+ "too many requests",
+ '"status":429',
+ '"code":429',
+ "shared free-tier ip quota",
+];
+const RATE_LIMIT_HARD_MARKERS = [
+ "invalid_request",
+ "invalid_response",
+ "invalid_reasoning",
+ "previous_response",
+ "freetiererror",
+ "insufficient_quota",
+ "billing",
+ "authentication",
+ "invalid_api_key",
+ "permission",
+ "moderation",
+];
+
+/**
+ * True when an SSE block carries an upstream-issued rate-limit error (HTTP
+ * 429 / rate_limit_exceeded / "too many requests"). Requires an error-shaped
+ * frame so ordinary model prose mentioning "rate limit" never triggers a
+ * replay; hard billing/auth/request verdicts always win.
+ */
+export function isRetriableRateLimitFrame(s: string): boolean {
+ const lower = s.toLowerCase();
+ // A successful terminal echoes the full response object, whose `error` is
+ // null; it can contain the model's prose ("HTTP 429 means rate limit") and
+ // must never be replayed. Only a real error object/event may be held.
+ if (lower.includes('"type":"response.completed"') || lower.includes('"status":"completed"')) {
+  return false;
+ }
+ if (
+  !lower.includes('"error":{') &&
+  !lower.includes('"error":"') &&
+  !lower.includes('"status":"failed"') &&
+  !lower.includes("response.failed") &&
+  !lower.includes('"type":"error"')
+ ) {
+  return false;
+ }
+ if (RATE_LIMIT_HARD_MARKERS.some((m) => lower.includes(m))) return false;
+ return RATE_LIMIT_MARKERS.some((m) => lower.includes(m));
+}
+
+
 /**
  * True when scanned SSE text carries an upstream-issued response.failed frame
  * for a TRANSIENT model fault (server_error class). Text-only turns holding
@@ -130,16 +187,18 @@ function endsOnFinishedSseLine(tail: string): boolean {
 // model-fault frames vs relay-fault truncations. Relay-health marks stay the
 // rotation mechanism; these counters attribute blame for status/logs.
 let midStreamModelFaults = 0;
+let midStreamRateLimitFaults = 0;
 let midStreamRelayTruncations = 0;
 
 /** Current mid-stream fault split. */
-export function getMidStreamFaultStats(): { modelFaults: number; relayTruncations: number } {
- return { modelFaults: midStreamModelFaults, relayTruncations: midStreamRelayTruncations };
+export function getMidStreamFaultStats(): { modelFaults: number; rateLimitFaults: number; relayTruncations: number } {
+ return { modelFaults: midStreamModelFaults, rateLimitFaults: midStreamRateLimitFaults, relayTruncations: midStreamRelayTruncations };
 }
 
 /** Test-only: reset the mid-stream fault split. */
 export function _resetMidStreamFaultStatsForTest(): void {
  midStreamModelFaults = 0;
+ midStreamRateLimitFaults = 0;
  midStreamRelayTruncations = 0;
 }
 
@@ -819,21 +878,24 @@ export function rewriteSseBlock(
  if (cloak.pathname.endsWith("/messages")) return rewriteMessagesBlock(block, state, cloak);
  return rewriteChatBlock(block, state, cloak);
 }
+export type MidStreamRefireReason = "truncation" | "model" | "rate_limit";
 /**
  * Options for pipeUpstreamStream.
  */
 export interface StreamPipeOptions {
  /**
-  * Mid-stream resume hook. Invoked at most once per turn, only when the
-  * upstream truncates (clean FIN without a terminal marker, premature
-  * socket close, or a genuine stream error) while the client is still
-  * attached. Return a replacement upstream readable to continue THIS turn
-  * on it — no synthetic terminal is injected and the client response stays
-  * open. Return null (or throw) to keep the existing terminate behavior:
-  * a synthetic response.incomplete/failed plus relay-health accounting.
+  * Mid-stream resume hook. Invoked at most once per turn when the upstream
+  * truncates (clean FIN without a terminal marker, premature socket close,
+  * or a genuine stream error), emits a transient model-failure frame, or
+  * emits a retriable rate-limit frame, while the client is still attached.
+  * Return a replacement upstream readable to continue THIS turn on it — no
+  * synthetic terminal is injected and the client response stays open.
+  * Return null (or throw) to keep the existing terminate behavior: a held
+  * failure frame is released, a synthetic response.incomplete/failed is
+  * injected when needed, and the response is ended exactly once.
   * Client aborts and clean terminal markers never reach this hook.
   */
- refire?: () => Promise<Readable | null>;
+ refire?: (reason?: MidStreamRefireReason) => Promise<Readable | null>;
  /**
   * Content-type the upstream sent for this response, passed through verbatim.
   * A value that is present and not an SSE type (text/event-stream) switches
@@ -955,31 +1017,46 @@ export function pipeUpstreamStream(
    s.includes("[DONE]")
   );
  };
- // Held transient model-failure frame (raw chunk or rewritten block text):
+ // Held transient failure frame (raw chunk or rewritten block text):
  // withheld from the client while one silent resume is attempted. Dropped on
  // success, forwarded verbatim (as the genuine upstream verdict) when the
  // resume is vetoed, unavailable, or fails. Null outside a hold.
  let heldFailureChunk: string | Buffer | null = null;
+ let heldFailureReason: "model" | "rate_limit" = "model";
  /**
-  * Hold an upstream-issued transient model-failure frame for one silent
-  * resume on a sibling relay. Returns true when held (caller must NOT
-  * forward the frame); false keeps the existing terminate behavior. Tool
-  * turns always veto: a regenerated turn would re-execute forwarded calls.
+  * Hold an upstream-issued transient failure frame for one silent resume on
+  * a sibling relay. Returns true when held (caller must NOT forward the
+  * frame); false keeps the existing terminate behavior. Tool turns always
+  * veto: a regenerated turn would re-execute forwarded calls.
   */
- const holdModelFailureForRefire = (chunk: string | Buffer): boolean => {
+ const holdFailureForRefire = (
+  chunk: string | Buffer,
+  reason: "model" | "rate_limit",
+ ): boolean => {
   if (refirePending || heldFailureChunk !== null || sawToolCall) return false;
   if (clientAborted || refireUsed || !opts?.refire || res.writableEnded || res.destroyed) return false;
   refireUsed = true;
   refirePending = true;
   heldFailureChunk = chunk;
-  midStreamModelFaults += 1;
-  log(
-   "warn",
-   "upstream model failed this turn mid-stream (model fault) — retrying once on the next relay",
-   { totalChunks, totalBytes },
-   rid,
-  );
-  void rescueHeldModelFailure();
+  heldFailureReason = reason;
+  if (reason === "rate_limit") {
+   midStreamRateLimitFaults += 1;
+   log(
+    "info",
+    "upstream rate-limited this turn mid-stream — retrying once on the next relay",
+    { totalChunks, totalBytes },
+    rid,
+   );
+  } else {
+   midStreamModelFaults += 1;
+   log(
+    "warn",
+    "upstream model failed this turn mid-stream (model fault) — retrying once on the next relay",
+    { totalChunks, totalBytes },
+    rid,
+   );
+  }
+  void rescueHeldFailure(heldFailureReason);
   return true;
  };
  /**
@@ -1008,16 +1085,16 @@ export function pipeUpstreamStream(
   } catch { }
  };
  /**
-  * Resume a held model-failure turn on the replacement stream from
+  * Resume a held transient-failure turn on the replacement stream from
   * opts.refire (rotation marking lives there, shared with the truncation
   * path). Success drops the held frame; the stale cut stream's later
   * events are neutered by the generation check in watch().
   */
- const rescueHeldModelFailure = async (): Promise<void> => {
+ const rescueHeldFailure = async (reason: "model" | "rate_limit"): Promise<void> => {
   const refire = opts?.refire;
   let next: Readable | null = null;
   try {
-   next = refire ? await refire() : null;
+   next = refire ? await refire(reason) : null;
   } catch {
    next = null;
   }
@@ -1027,6 +1104,17 @@ export function pipeUpstreamStream(
     next?.destroy();
    } catch { }
    releaseHeldFailure();
+   // The cut stream's FIN/close may already have been consumed while the
+   // rescue was in flight (both handlers return early on refirePending), so
+   // nothing else will terminate this response. A held terminal frame sets
+   // hasTerminalEvent in releaseHeldFailure; a non-terminal chat/error frame
+   // still gets the synthetic terminal before the socket closes.
+   if (!hasTerminalEvent) {
+    ensureTerminalEvent(false, "mid-stream rescue failed", false, true);
+   }
+   try {
+    if (!res.writableEnded) res.end();
+   } catch { }
    return;
   }
   heldFailureChunk = null;
@@ -1040,7 +1128,12 @@ export function pipeUpstreamStream(
   try {
    if (!cut.destroyed) cut.destroy();
   } catch { }
-  log("debug", "mid-stream model-fault refire: continuing turn on replacement stream", { totalChunks, totalBytes }, rid);
+  log(
+   "debug",
+   `mid-stream ${reason === "rate_limit" ? "rate-limit" : "model-fault"} refire: continuing turn on replacement stream`,
+   { totalChunks, totalBytes },
+   rid,
+  );
  };
  /**
   * Write one payload to the client with the shared backpressure/flush
@@ -1083,6 +1176,9 @@ export function pipeUpstreamStream(
   * delivery guarantees.
   */
  const forwardText = (text: string): void => {
+  // A hold/refire can start inside a multi-block chunk; the cut stream's
+  // remaining blocks must not interleave with the replacement turn.
+  if (refirePending) return;
   const buf = Buffer.from(text, "utf8");
   const scanBuf =
    terminalScanCarry.length > 0
@@ -1090,11 +1186,19 @@ export function pipeUpstreamStream(
     : buf;
   const scanned = scanBuf.toString("utf8");
   if (!sawToolCall && TOOL_CALL_MARKERS.some((m) => scanned.includes(m))) sawToolCall = true;
+  // A 429-shaped frame is a per-egress rate limit: hold it for one silent
+  // resume on a sibling relay before the client ever sees a rate-limit error.
+  // Classify the CURRENT complete block, not the terminal scan carry: the
+  // carry may splice a previous block's "error" key into this one.
+  // Tool turns, a spent resume budget, or a hard verdict keep it terminal.
+  if (!hasTerminalEvent && isRetriableRateLimitFrame(text) && holdFailureForRefire(text, "rate_limit")) {
+   return;
+  }
   if (!hasTerminalEvent && checkTerminalEvent(scanned)) {
    // Upstream-issued transient model failure on a text-only turn: hold the
    // frame for one silent resume instead of terminating (tool turns veto
-   // inside holdModelFailureForRefire and keep the terminal below).
-   if (isTransientModelFailureFrame(scanned) && holdModelFailureForRefire(text)) return;
+   // inside holdFailureForRefire and keep the terminal below).
+   if (isTransientModelFailureFrame(scanned) && holdFailureForRefire(text, "model")) return;
    hasTerminalEvent = true;
   }
   terminalScanCarry = Buffer.from(scanBuf.subarray(Math.max(0, scanBuf.length - 32)));
@@ -1166,7 +1270,7 @@ export function pipeUpstreamStream(
   refirePending = true;
   let next: Readable | null = null;
   try {
-   next = await opts.refire();
+   next = await opts.refire("truncation");
   } catch {
    next = null;
   }
@@ -1394,6 +1498,9 @@ export function pipeUpstreamStream(
   const flushed = flushBufferedToolArgs(cloakState, cloak);
   if (flushed !== null) forwardText(flushed);
  }
+  // A tail-framed failure frame may have started a hold during the flush
+  // above; the rescue owns the turn now. Do not inject a terminal or end.
+  if (refirePending || heldFailureChunk !== null) return;
   if (hasTerminalEvent) recordOnce(false);
   const elapsed = ((Date.now() - startAt) / 1000).toFixed(1);
   if (!hasTerminalEvent && totalChunks > 0) {
@@ -1447,6 +1554,9 @@ export function pipeUpstreamStream(
    const flushed = flushBufferedToolArgs(cloakState, cloak);
    if (flushed !== null) forwardText(flushed);
   }
+   // A tail-framed failure frame may have started a hold during the flush
+   // above; the rescue owns the turn now.
+   if (refirePending || heldFailureChunk !== null) return;
    if (bodyGate !== "sse") {
     // Non-SSE passthrough: same relay-fault accounting as the SSE path's
     // mid-body close (a genuine upstream socket death, not a client

package/src/types.ts

@@ -16,7 +16,7 @@ export type ThinkingLevel =
 
 export type ThinkingLevelMap = Partial<Record<ThinkingLevel, string | null>>;
 
-export type ModelInputType = "text" | "image" | "video";
+export type ModelInputType = "text" | "image";
 
 export interface ModelDef {
  id: string;