pi-freeflow 1.38.5 → 1.40.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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
+
+- 7427771: Security, wire-path and automation fixes from the October 2026 review:
+  
+  - The local proxy now requires its own access token: every `/v1/*` and `/_*` request must carry `Authorization: Bearer <token>` (the token is written to the data directory on first start and the plugin supplies it automatically), the Host header must be loopback, and the daemon refuses to kill a process it cannot identify as its own. `GET /health` stays open for liveness checks. External tools that call the proxy directly must read the token file and send the header.
+  - A request for one model is never silently served by another: the internal Kilo 400 retry no longer substitutes a different model, so upstream verdicts reach the caller unchanged.
+  - Answers are no longer corrupted before they reach the client: a plain JSON reply that merely mentions `data:` is forwarded byte-identically instead of being replaced by an empty completion, a complete final SSE event that lost its trailing blank line is no longer dropped, and malformed tool arguments can no longer stall the proxy with a quadratic scan.
+  - Relay health reflects reality: an upstream 404 or 401 forwarded by a healthy relay no longer cools the pool, and a repeated 500 no longer resets the failing relay's health or steals the sticky slot.
+  - Cline logins: a rejected grant is parked instead of re-tried on every turn, a failed save is reported instead of being shown as saved, and logging out no longer leaves the removed token in the recovery file.
+  - Startup hooks and updates: the Windows logon task stores a command Windows can launch, a failed `systemctl --user enable` is reported, and auto-update no longer blocks the host while installing.
+  - Automation: the free-model health check has a timeout that fits a fully hanging catalog, a new guardrail keeps that budget honest, drift alerts close themselves once recovered, and the published-tarball check now also fails when the package ships a file the tree does not have.
+
+### Patch Changes
+
+- 152862b: Retire Muse Spark 1.2 contributor from the OpenCode Zen lineup — the model was deprecated upstream and now answers HTTP 410. The catalog, docs, and health checks move to the remaining 35 live models (12 on Zen), and the retired id is dead-listed so an old disk cache or an upstream merge cannot bring it back into the picker.
+
 ## 1.38.5
 
 ### Patch Changes

package/README.md

@@ -1,14 +1,14 @@
 # pi-freeflow
 
-> 36 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.
 
 [![npm version](https://img.shields.io/npm/v/pi-freeflow?style=flat-square&color=00E5FF)](https://www.npmjs.com/package/pi-freeflow)
 [![npm downloads](https://img.shields.io/npm/dm/pi-freeflow?style=flat-square)](https://www.npmjs.com/package/pi-freeflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Pi](https://img.shields.io/badge/Powered%20by-Pi-7c3aed?style=flat-square)](https://github.com/badlogic/pi-ai)
-[![Oh My Pi](https://img.shields.io/badge/Compatible-OMP-black?style=flat-square)](https://github.com/coder/oh-my-pi)
+[![Pi](https://img.shields.io/badge/Powered%20by-Pi-7c3aed?style=flat-square)](https://github.com/earendil-works/pi)
+[![Oh My Pi](https://img.shields.io/badge/Compatible-OMP-black?style=flat-square)](https://github.com/can1357/oh-my-pi)
 
 ---
 
@@ -16,11 +16,11 @@ Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handl
 
 | Feature | What it does | Cost |
 | :--- | :--- | :--- |
-| **36 free models** | 13 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** |
-| **Shared local proxy** | One daemon on `127.0.0.1:28180` serves every session on the machine, so parallel subagents reuse it instead of opening their own connections. | **$0** |
+| **Shared local proxy** | One daemon on `127.0.0.1:28180` serves every session on the machine, so parallel subagents reuse it instead of opening their own connections. Loopback-only and token-gated: hosts send the token automatically, external tools read `~/.pi/agent/token`. | **$0** |
 | **Logs you can read** | `~/.pi/agent/pi-freeflow.log`, rotated at 10MB. Tail it with `/freeflow logs`. | **$0** |
 
 ---
@@ -48,13 +48,13 @@ pi install npm:pi-freeflow
 **OMP, interactive:**
 ```bash
 omp
-/model → freeflow → muse-spark-1.2-contributor-free (1M) → max
+/model → freeflow → deepseek-v4.1-flash-free (1M) → max
 ```
 
 **OMP, one shot:**
 ```bash
-omp -p --model freeflow/muse-spark-1.2-contributor-free "build me a SaaS"
-omp -p --model freeflow/space-bunny:high "solve this bug"   # alias + thinking level
+omp -p --model freeflow/deepseek-v4.1-flash-free "build me a SaaS"
+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),
@@ -183,6 +183,7 @@ The same command set works identically in OMP and Pi:
 
 ```bash
 /freeflow status                  # View active relay, pool status, and candidates
+/freeflow hide|show               # Hide or restore the status-bar widget (also `widget hide`/`widget show`)
 /freeflow list                    # List all relays with real-time health badges
 /freeflow use <url|index|label>   # Switch active relay
 /freeflow url <url>               # Set the active relay URL directly
@@ -190,12 +191,16 @@ The same command set works identically in OMP and Pi:
 /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 and latency
-/freeflow on|off|auto|spread     # Relay mode (auto = enabled for freeflow, spread = rotate pool)
+/freeflow on|off|auto|sticky|spread  # Relay mode (auto/sticky = sticky primary, spread = rotate pool)
 /freeflow deploy <platform>       # Guided relay deploy: vercel|cloudflare|deno, token in-memory, auto-adds
 /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 reload models           # Alias of refresh
 /freeflow update                  # Check for and install a package update
+/freeflow autoupdate [on|off]     # View or toggle automatic background updates
+/freeflow install-startup         # Install the login-startup hook so the daemon comes up with your session
+/freeflow uninstall-startup       # Remove the login-startup hook
 /freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
 /freeflow kill                    # Stop the shared proxy daemon now (restarts on next use)
 /freeflow cline login               # Sign in through the browser, save to the per-user pool
@@ -208,52 +213,51 @@ The same command set works identically in OMP and Pi:
 
 ---
 
-### 36 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 (13 models), Responses and Chat 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` | ❌ |
-| `muse-spark-1.2-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
-| `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.
 
@@ -273,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) | ❌ | ❌ |
 
 ---
 
@@ -305,14 +309,14 @@ cat ~/.pi/agent/pi-freeflow.log | tail -n 50
 
 This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step and one runtime dependency (`undici`). Thinking and prompt normalization stay with the host (`pi-ai`).
 
-About 45k lines including tests: `src/` is roughly 17.7k across 27 files, and the 82 test files add roughly 27k more. The full suite (sandboxed, network-mocked) and typecheck pass before every release. See CHANGELOG.md.
+About 52k lines including tests: `src/` is roughly 19.4k across 30 files, and the 90 test files add roughly 32.4k more. The full suite (sandboxed, network-mocked) and typecheck pass before every release. See CHANGELOG.md.
 
 ---
 
 ### FAQ
 
 **Do I need API keys?**
-No. OpenCode and Kilo free models are both keyless: the proxy sends no `Authorization` header at all, and a placeholder credential is rejected rather than merely unused — `Bearer kilo-free` answers `401 INVALID_TOKEN`, while sending nothing answers 200 for every free catalog model. You never paste a key. Cline free models need a browser login instead: `/freeflow cline login` saves it to a per-user pool on your machine. OVHcloud AI Endpoints models need no account and no key at all.
+No. OpenCode and Kilo free models need no key of your own. The proxy strips the placeholder credential the host provider registers with — forwarding it upstream gets a `401` (for Kilo, `Bearer kilo-free` answers `401 INVALID_TOKEN`) — so your key, if any, never leaves the machine. For OpenCode Zen it then adds the fixed `Authorization: Bearer public` the current `/inference/v1` gateway requires; the Kilo and OVHcloud lanes go out with no `Authorization` header at all. You never paste a key. Cline free models need a browser login instead: `/freeflow cline login` saves it to a per-user pool on your machine. OVHcloud AI Endpoints models need no account and no key at all.
 
 **What if all relays hit rate limits?**
 The proxy tries direct upstream. If that is also rate-limited, the host shows the limit. That number is the shared upstream cap; without relays you would hit the same wall sooner.
@@ -378,7 +382,7 @@ pnpm smoke       # verifies extensions/index.ts loads without crashing
 #### Project structure
 
 ```
-├── models.ts                # 36-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.38.5",
+  "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",
@@ -52,13 +52,13 @@
     "docs:build": "vitepress build docs"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.27.0",
+    "@changesets/cli": "^3.0.3",
     "@types/node": "^22.13.9",
-    "js-yaml": "^4.1.0",
-    "typescript": "^5.8.2",
+    "js-yaml": "^5.5.0",
+    "typescript": "^7.0.2",
     "vitepress": "^1.6.4"
   },
   "dependencies": {
-    "undici": "7.30.0"
+    "undici": "7.30.1"
   }
 }

package/src/atomic-write.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+
+/** Block synchronously for ms without burning CPU. */
+function sleepSync(ms: number): void {
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Rename with bounded retry: Windows briefly locks the target when another
+ * process holds the file open, surfacing as EPERM/EACCES/EBUSY. Three attempts
+ * with a fixed 50ms backoff by default; any other error fails immediately.
+ */
+export function renameWithRetry(from: string, to: string, attempts = 3, delayMs = 50): 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 >= attempts) {
+    throw e;
+   }
+   sleepSync(delayMs);
+  }
+ }
+}
+
+/**
+ * Write `data` to `file` atomically: stage the bytes in a sibling temp file,
+ * then rename over the target, so a crash leaves either the old or the new
+ * file intact. The staged `<file>.<uuid>.tmp` is deliberately left in place
+ * when the rename never lands — it is the only copy of the bytes that failed
+ * to land, and relay-state's cleanupStaleTmpFiles reaps stale litter later.
+ *
+ * `mode` is applied to the staged file and re-applied to the final path
+ * (best-effort — Windows ignores POSIX modes), so secret-bearing files keep
+ * owner-only permissions.
+ */
+export function writeFileAtomic(file: string, data: string, opts?: { mode?: number }): void {
+ const tmp = `${file}.${randomUUID()}.tmp`;
+ fs.writeFileSync(tmp, data, opts?.mode ? { encoding: "utf8", mode: opts.mode } : "utf8");
+ if (opts?.mode) {
+  try {
+   fs.chmodSync(tmp, opts.mode);
+  } catch { }
+ }
+ renameWithRetry(tmp, file);
+ if (opts?.mode) {
+  try {
+   fs.chmodSync(file, opts.mode);
+  } catch { }
+ }
+}

package/src/catalog.ts

@@ -4,9 +4,9 @@
  * Provides 24-hour atomic disk caching with safe offline fallback to verified static definitions.
  */
 
-import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { writeFileAtomic } from "./atomic-write.ts";
 import {
  CATALOG_CACHE_FILE,
  CATALOG_CACHE_TTL_MS,
@@ -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",
@@ -130,6 +133,20 @@ export const DEAD_MODEL_IDS = new Set<string>([
  // muse-spark-1.3-contributor-free: decommissioned upstream (2026-10-17) — gone from
  // live Zen /v1/models list, answers HTTP 410 "Model muse-spark-1.3-contributor-free has been deprecated".
  "muse-spark-1.3-contributor-free",
+ // muse-spark-1.2-contributor-free: decommissioned upstream (2026-10-18) — answers
+ // HTTP 410 "Model muse-spark-1.2-contributor-free has been deprecated" while the
+ // 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.
@@ -169,7 +186,7 @@ export function sanitizeCatalogModels(models: RegisteredModel[]): RegisteredMode
 }
 /**
  * In-memory cache of currently active/available free models.
- * Initialized with all 36 verified models for 0ms instant availability.
+ * Initialized with all 32 verified models for 0ms instant availability.
  */
 let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
  ...m,
@@ -288,10 +305,11 @@ export function enrichModelDef(raw: RawModelItem, source: Upstream): RegisteredM
   maxTokens = 131_072;
  }
 
- // Muse Spark is served on the responses API upstream (both static catalogue
- // entries declare it). Every known id short-circuits above, so this only
- // decides for ids Zen lists dynamically — matching the family keeps a future
- // muse-spark id off the chat endpoint it would 500 on.
+ // Muse Spark is served on the responses API upstream (the Cline entry still
+ // declares it; the Zen 1.2/1.3 contributor ids were retired upstream). 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 {
@@ -333,39 +351,18 @@ export function readCatalogCache(): CatalogCacheData | null {
 }
 
 /**
- * Atomically write catalog cache data to disk using temporary file + rename.
+ * Atomically write catalog cache data to disk (temp file + rename, see
+ * src/atomic-write.ts).
  * Persists etag alongside models for subsequent If-None-Match conditional requests.
  * Note: fsync not needed — rename is atomic on same filesystem; crash leaves either old or new file intact.
  */
-function sleepSync(ms: number): void {
- Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-function renameWithRetry(from: string, to: string): void {
- const retryable: Record<string, true> = { EPERM: true, EACCES: true, EBUSY: true };
- for (let attempt = 1; ; attempt++) {
-  try {
-   fs.renameSync(from, to);
-   return;
-  } catch (e) {
-   const code = (e as NodeJS.ErrnoException | null)?.code;
-   if (!code || !retryable[code] || attempt >= 3) {
-    throw e;
-   }
-   sleepSync(50);
-  }
- }
-}
-
 export function writeCatalogCache(data: CatalogCacheData): void {
  try {
   const dir = path.dirname(CATALOG_CACHE_FILE);
   if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
   }
-  const tmpPath = `${CATALOG_CACHE_FILE}.${randomUUID()}.tmp`;
-  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf8");
-  renameWithRetry(tmpPath, CATALOG_CACHE_FILE);
+  writeFileAtomic(CATALOG_CACHE_FILE, JSON.stringify(data, null, 2));
  } catch (err) {
   logWarn("Could not persist catalog cache to disk", { error: String(err) });
  }
@@ -430,7 +427,14 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
     signal: AbortSignal.timeout(CATALOG_REFRESH_TIMEOUT_MS),
    });
    if (res.status === 304) {
-    // Not modified — skip merge, extend timestamp to avoid tight loop
+    // Not modified upstream, but the cached list is still the only record of
+    // dynamically discovered ids this process never merged (a 304 revalidates
+    // before any 200 merge), so overlay it exactly like the stale-cache paths
+    // below instead of returning the untouched in-memory catalog.
+    if (staleForEtag && Array.isArray(staleForEtag.models) && staleForEtag.models.length > 0) {
+     aliveCatalog = mergeCatalog(aliveCatalog, sanitizeCatalogModels(staleForEtag.models));
+    }
+    // Extend the timestamp to avoid a tight loop on the same 304
     if (staleForEtag && Array.isArray(staleForEtag.models)) {
      try {
       writeCatalogCache({ ...staleForEtag, timestamp: Date.now() });