pi-freeflow 1.38.0 → 1.38.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.38.1
+
+### Patch Changes
+
+- Add the Nemotron 3.5 Super VL free model and enable the max thinking level on Cat Jam — both live-verified through the proxy; align the README and docs with the shipped catalog.
+- The first-run welcome now names the local proxy port actually in use instead of the default port.
+- Streaming requests now pass through replies that arrive in a non-streaming format instead of dropping the answer, concurrent startups share a single connection attempt instead of racing, and a foreign process squatting the local proxy port is no longer mistaken for the daemon we own.
+- Following logs now reads only the lines appended since the last tick instead of re-reading the whole log file every second, so `/freeflow logs --follow` stays light even on large logs.
+- Fix a batch of verified edge cases: non-ASCII streaming text is no longer corrupted when a character spans network chunks, assistant text stays visible on the responses path when it is served from a chat-only upstream, tool-argument repair also works on strict tool schemas, a relay that rejects our auth rolls to the next egress instead of being marked healthy, the update flow restarts the proxy it is actually attached to, and daemon/health state handling no longer loops or reads stale data.
+
 ## 1.38.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.
+> 36 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** | 11 from OpenCode Zen, 14 from KiloCode Gateway, 2 from Cline, 8 from OVHcloud AI Endpoints, context windows up to 1M. Full list below. | **$0** |
+| **36 free models** | 12 from OpenCode Zen, 14 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 Cloudflare Workers, Deno Deploy, and Vercel Edge relays. 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 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** |
@@ -197,24 +197,25 @@ The same command set works identically in OMP and Pi:
 
 ---
 
-### 35 models, one command
+### 36 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 (11 models), Responses and Chat API
+#### OpenCode Zen (12 models), Responses and Chat 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 … xhigh` | ❌ |
+| `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` | ✅ |
 | `muse-spark-1.3-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` | ❌ |
 | `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` | ✅ |
@@ -258,13 +259,11 @@ Each account can only be saved once: an extra login for an account you already h
 | `cline-free/muse-spark-1.3-contributor` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal…xhigh`\* | ✅ |
 | `z-ai/glm-5.3-flash` | Zhipu AI | **1M** (1.048.576) | **131K** (131.072) | `low/high/max` | ✅ |
 #### OVHcloud AI Endpoints (8 models), OpenAI compatible
-#### OVHcloud AI Endpoints (9 models), OpenAI compatible
 
 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.
 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.
-All nine 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 |
 | :--- | :--- | :--- | :--- | :--- | :--- |
@@ -274,7 +273,7 @@ All nine talk the normal chat API. Hosts that prefer the responses API work too
 | `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-7b-v0.3` (`ovh-free/Mistral-7B-Instruct-v0.3`) | Mistral AI | **64K** (65.536) | **64K** (65.536) | ❌ | ❌ |
+| `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) | ❌ | ❌ |
 
 ---
@@ -295,7 +294,7 @@ 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 43k lines including tests: `src/` is roughly 17k across 27 files, and the 78 test files add roughly 26k more. The full suite (sandboxed, network-mocked) and typecheck pass before every release. See CHANGELOG.md.
+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.
 
 ---
 
@@ -368,9 +367,8 @@ pnpm smoke       # verifies extensions/index.ts loads without crashing
 #### Project structure
 
 ```
-├── models.ts                # 34-model catalog definitions
+├── models.ts                # 36-model catalog definitions
 ├── index.ts                 # extension entry, lifecycle hooks
-├── models.ts                # 37-model catalog definitions
 ├── catalog.ts               # model catalog cache (24h disk)
 ├── proxy.ts                 # local proxy server (127.0.0.1:28180)
 ├── client.ts                # session-side daemon attach/spawn and heartbeat

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.38.0",
+  "version": "1.38.1",
   "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",
@@ -54,6 +54,7 @@
   "devDependencies": {
     "@changesets/cli": "^2.27.0",
     "@types/node": "^22.13.9",
+    "js-yaml": "^4.1.0",
     "typescript": "^5.8.2",
     "vitepress": "^1.6.4"
   },

package/src/catalog.ts

@@ -1,7 +1,7 @@
 /**
  * Dynamic catalog discovery, caching, and model enrichment for pi-freeflow
  *
- * Provides 1-hour atomic disk caching with safe offline fallback to verified static definitions.
+ * Provides 24-hour atomic disk caching with safe offline fallback to verified static definitions.
  */
 
 import { randomUUID } from "node:crypto";
@@ -11,7 +11,6 @@ import {
  CATALOG_CACHE_FILE,
  CATALOG_CACHE_TTL_MS,
  CATALOG_REFRESH_TIMEOUT_MS,
- KILO_CHAT_URL,
  OPENCODE_API_URL,
  opencodeHeaders,
 } from "./config.ts";
@@ -353,7 +352,10 @@ export function writeCatalogCache(data: CatalogCacheData): void {
 }
 
 /**
- * Refresh free model catalog from OpenCode Zen and KiloCode Gateway endpoints.
+ * Refresh the free model catalog from the OpenCode Zen listing. Only Zen is
+ * fetched — Kilo ids stay static (merged from ALL_MODELS; the cache's kilo
+ * field is preserved but never re-fetched), so Kilo entries change only in
+ * src/models.ts.
  * Uses ETag conditional requests (If-None-Match) to avoid re-merging unchanged
  * catalogs; a 304 Not Modified response skips merge and returns the in-memory
  * catalog unchanged. Falls back gracefully to cached or static models if network

package/src/client.ts

@@ -62,6 +62,11 @@ let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 let watchdogTimer: ReturnType<typeof setInterval> | null = null;
 let heartbeatPort = 0;
 let ensuring = false;
+/**
+ * In-flight ensureDaemon() attempt. Every concurrent caller awaits this same
+ * promise instead of guessing a port; ensureDaemon clears it on settle.
+ */
+let ensureInFlight: Promise<number> | null = null;
 let fallbackServer: http.Server | null = null;
 /** First tick (Date.now()) the daemon has looked continuously busy; 0 = idle. */
 let busySince = 0;
@@ -434,14 +439,25 @@ export function _resetRecoveryForTest(): void {
 /** Recovery-decision shape; canonical definition lives in health.ts. */
 export type HealthForRecovery = DaemonHealthSnapshot;
 
+/**
+ * Older-version guard: only a daemon strictly older than this build is worth
+ * recovering. shouldReplaceDaemon deliberately leaves a NEWER daemon running,
+ * so recovering from one could never succeed (watchdog → recover → refused →
+ * reattach → watchdog, until the breaker parks into the in-process fallback).
+ * Null/undefined version (pre-version daemon) is not older on its own.
+ */
+function isOlderDaemonVersion(version: string | null | undefined): boolean {
+ return version != null && compareVersions(version, PKG_VERSION) < 0;
+}
+
 /**
  * Watchdog decision matrix (pure, testable). Recover when the daemon is gone,
- * serves a stale version, or reports a degraded failed-SSE window. Missing
+ * serves an older version, or reports a degraded failed-SSE window. Missing
  * sseDegraded (pre-window daemon) never triggers on its own.
  */
 export function shouldRecoverOnHealth(health: HealthForRecovery): boolean {
  if (health === null) return true;
- if (health.version !== null && health.version !== PKG_VERSION) return true;
+ if (isOlderDaemonVersion(health.version)) return true;
  if (health.sseDegraded === true) return true;
  return false;
 }
@@ -535,7 +551,7 @@ export async function watchdogCheck(port: number): Promise<void> {
   return;
  }
  if (health && (health.activeRequests ?? 0) > 0 && !isStuckBusy(busySince, health.lastBytesAt ?? 0)) return;
- void triggerRecovery(port, health === null ? "daemon gone" : health.version !== PKG_VERSION ? `stale v${health.version}` : "failed-SSE degraded").catch((e) => logWarn("watchdog recovery failed", { error: String(e) }));
+ void triggerRecovery(port, health === null ? "daemon gone" : isOlderDaemonVersion(health.version) ? `stale v${health.version}` : "failed-SSE degraded").catch((e) => logWarn("watchdog recovery failed", { error: String(e) }));
 }
 
 async function shouldReplaceDaemon(port: number, remoteVer: string): Promise<boolean> {
@@ -616,22 +632,72 @@ export type DarkHolderProbe = {
  alive: boolean;
  /** True when a TCP connection to the port succeeds (something holds it). */
  bound: boolean;
- /** Full /_health snapshot, or null when the holder answers nothing. */
- health: HealthForRecovery;
+ /**
+  * True when GET /_health answers in OUR daemon's shape. A stranger squatting
+  * the loopback port can answer `{}` or arbitrary JSON: that is not a daemon
+  * of ours, whatever it claims.
+  */
+ healthOurs: boolean;
 };
 
+/**
+ * True when a /_health response body carries OUR daemon's shape: a JSON object
+ * whose numeric `port` names the port it is bound to (src/health.ts builds it
+ * from the listening socket). Anything else is a stranger on the loopback port
+ * — attaching to it would route the user's prompts into a process we do not
+ * own, so it must never be read as a daemon.
+ */
+export function isOurDaemonHealthBody(port: number, body: unknown): boolean {
+ if (!body || typeof body !== "object") return false;
+ const reported = (body as { port?: unknown }).port;
+ return typeof reported === "number" && reported === port;
+}
+
+/**
+ * Probe whatever holds `port` for the three facts the reclaim decision needs.
+ * Ordered cheap-to-expensive and short-circuiting exactly like the inline
+ * sequence it replaces: a models-answering daemon is live, a refused port is
+ * free, and only a bound-but-model-silent holder is asked for /_health.
+ */
+export async function probeDarkHolder(port: number): Promise<DarkHolderProbe> {
+ if (await isProxyAlive(port)) return { alive: true, bound: true, healthOurs: false };
+ if (!(await isPortBound(port))) return { alive: false, bound: false, healthOurs: false };
+ return { alive: false, bound: true, healthOurs: await probeOurHealth(port) };
+}
+
+/**
+ * Fetch /_health and keep the verdict only when the body is OUR daemon's
+ * shape. Same request and budget as proxy.getDaemonHealth, minus its snapshot
+ * mapping — which drops `port`, the one field that tells our daemon apart
+ * from a stranger answering arbitrary JSON.
+ */
+async function probeOurHealth(port: number): Promise<boolean> {
+ if (!Number.isInteger(port) || port < 1 || port > 65535) return false;
+ try {
+  const res = await fetch(`http://${HOST}:${port}/_health`, {
+   signal: AbortSignal.timeout(2500),
+  });
+  if (!res.ok) return false;
+  return isOurDaemonHealthBody(port, await res.json());
+ } catch {
+  return false;
+ }
+}
+
 /**
  * Pure decision: reclaim a base port that is actually held (TCP connect
- * succeeds) yet answers neither /v1/models nor /_health. A live daemon —
- * stale, busy, even mid-stream — always answers both from its event loop, so
- * a dark holder cannot be serving traffic and replacing it cannot interrupt a
- * real stream. A FREE port is not a dark holder: treating it as one cost a
- * blind ~2s kill-and-poll on every cold start (issue #52).
+ * succeeds) yet answers neither /v1/models nor /_health in OUR shape. A live
+ * daemon — stale, busy, even mid-stream — always answers both from its event
+ * loop, so a dark holder cannot be serving traffic and replacing it cannot
+ * interrupt a real stream. A FREE port is not a dark holder: treating it as
+ * one cost a blind ~2s kill-and-poll on every cold start (issue #52). A holder
+ * answering /_health with anything but our shape (a stranger's `{}`) is dark:
+ * it is not a daemon of ours, so it is reclaimed rather than attached to.
  */
 export function shouldReclaimDarkHolder(probe: DarkHolderProbe): boolean {
  if (probe.alive) return false;
  if (!probe.bound) return false;
- if (probe.health !== null) return false;
+ if (probe.healthOurs) return false;
  return true;
 }
 
@@ -643,18 +709,17 @@ export function shouldReclaimDarkHolder(probe: DarkHolderProbe): boolean {
  * stale-replace path owns versioned daemons.
  */
 async function reclaimDarkHolder(port: number): Promise<boolean> {
- const alive = await isProxyAlive(port);
- if (alive) return true;
- if (!(await isPortBound(port))) return false; // port is free — spawn fresh
- const health = await getDaemonHealth(port);
- if (!shouldReclaimDarkHolder({ alive, bound: true, health })) return true;
+ const probe = await probeDarkHolder(port);
+ if (probe.alive) return true;
+ if (!probe.bound) return false; // port is free — spawn fresh
+ if (!shouldReclaimDarkHolder(probe)) return true;
  if (NO_KILL_ENV && process.env[NO_KILL_ENV] === "1") {
   logInfo(
-   `proxy on :${port} answers neither health nor models — leaving it alone (replacement disabled by env)`,
+   `proxy on :${port} answers neither our health nor models — leaving it alone (replacement disabled by env)`,
   );
   return false;
  }
- logWarn(`proxy on :${port} holds the port but answers nothing — replacing dark holder`);
+ logWarn(`proxy on :${port} holds the port but answers nothing of ours — replacing dark holder`);
  await killPortHolder(port);
  for (let i = 0; i < 10; i++) {
   await new Promise<void>((r) => setTimeout(r, 200));
@@ -982,9 +1047,27 @@ async function probeAndMaybeReplace(
  * Returns the port the caller should use for its ProviderConfig.
  */
 export async function ensureDaemon(): Promise<number> {
+ if (ensureInFlight) return ensureInFlight;
  if (ensuring) return attachedPort || PORT;
  ensuring = true;
+ const attempt = ensureDaemonAttempt();
+ ensureInFlight = attempt;
  try {
+  return await attempt;
+ } finally {
+  if (ensureInFlight === attempt) ensureInFlight = null;
+  ensuring = false;
+ }
+}
+
+/**
+ * One ensure/attach attempt: probe → attach → spawn → dark-holder reclaim →
+ * in-process fallback. Split out of ensureDaemon so concurrent callers share
+ * the same promise instead of reading a half-settled port. Keeps `ensuring`
+ * latched for the whole attempt so the heartbeat/watchdog/recovery ticks stay
+ * out of the way (they early-return on it).
+ */
+async function ensureDaemonAttempt(): Promise<number> {
   const primary = await probeAndMaybeReplace(PORT, "proxy daemon");
   if (primary !== null) {
    await attachTo(primary);
@@ -1056,9 +1139,6 @@ export async function ensureDaemon(): Promise<number> {
    logWarn("in-process fallback bind failed", { error: String(e) });
    return PORT;
   }
- } finally {
-  ensuring = false;
- }
 }
 
 export function getClientPort(): number {
@@ -1083,6 +1163,7 @@ export function _resetClientForTest(): void {
  heartbeatPort = 0;
  attachedPort = 0;
  ensuring = false;
+ ensureInFlight = null;
  lastSpawnAt = 0;
  daemonSpawner = spawn;
  _resetUaRefreshForTest();

package/src/cline-accounts.ts

@@ -362,10 +362,20 @@ function diskMtime(): number {
  * file (mtime moved). Never throws; corrupt reads come back empty.
  */
 export function loadPool(): ClinePoolState {
- const m = diskMtime();
- if (cached && m === cachedMtime) return cached;
- cached = readPoolFile();
- cachedMtime = diskMtime();
+ const before = diskMtime();
+ if (cached && before === cachedMtime) return cached;
+ let loaded = readPoolFile();
+ let stamp = diskMtime();
+ // The read is only trustworthy when the file did not move across it. Reading
+ // first and stamping afterwards latches pre-read content under the post-write
+ // mtime, which hides the change until the next write. Re-read once; the mtime
+ // observed after that read is the one the returned pool is cached under.
+ if (stamp !== before) {
+  loaded = readPoolFile();
+  stamp = diskMtime();
+ }
+ cached = loaded;
+ cachedMtime = stamp;
  return cached;
 }
 
@@ -409,6 +419,32 @@ function accountCountIn(raw: string): number {
  }
 }
 
+/** 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 pool file open, surfacing as EPERM/EACCES/EBUSY. Three
+ * attempts with a fixed 50ms backoff; any other error fails immediately.
+ */
+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);
+  }
+ }
+}
+
 /** Atomically persist the pool with owner-only permissions. Never logs secrets. */
 export function savePool(pool: ClinePoolState): void {
  try {
@@ -424,7 +460,7 @@ export function savePool(pool: ClinePoolState): void {
   try {
    fs.chmodSync(tmp, 0o600);
   } catch { }
-  fs.renameSync(tmp, CLINE_POOL_FILE);
+  renameWithRetry(tmp, CLINE_POOL_FILE);
   // Compare the pool just written too, so growth is never the copy that lags.
   keepLargestBackup(serialized);
   cached = pool;