pi-freeflow 1.37.1 → 1.38.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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
+
+- Follow pi's config-dir global: data files (relay state, logs, caches — including the staged daemon sources) now root at `PI_CODING_AGENT_DIR` when set, instead of always `~/.pi/agent`. CI and containers can relocate pi's config dir once and the extension writes alongside it. A leading `~` in either override expands to the home directory, and `PI_FREEFLOW_DATA_DIR` still overrides everything.
+
+### Patch Changes
+
+- Startup no longer stalls for several seconds when the extension is installed as a package and runs under Node.js: the detached proxy daemon is now launched from a staged copy of its sources (Node refuses to strip types for files under `node_modules`), a daemon that exits immediately is detected instead of being awaited for the full ready timeout, and a free base port is no longer mistaken for an unresponsive port holder.
+
 ## 1.37.1
 
 ### Patch 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.37.1",
+  "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

@@ -40,12 +40,14 @@ import {
  RECOVERY_BACKOFF_BASE_MS,
  RECOVERY_BACKOFF_CAP_MS,
  refreshOpenCodeUserAgent,
+ resolveDaemonSrcCacheDir,
 } from "./config.ts";
 import { logInfo, logWarn } from "./logger.ts";
 import {
  getDaemonHealth,
  getDaemonVersion,
  isProxyAlive,
+ isPortBound,
  killPortHolder,
  reprobeBasePortAlive,
  startProxy,
@@ -60,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;
@@ -432,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;
 }
@@ -533,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> {
@@ -610,42 +628,98 @@ export function openDaemonLogFd(): number | null {
 }
 
 export type DarkHolderProbe = {
- /** True when GET /v1/models answers on the port. */
+ /** True when GET /v1/models answers with a JSON catalog on the port. */
  alive: boolean;
- /** Full /_health snapshot, or null when the holder answers nothing. */
- health: HealthForRecovery;
+ /** True when a TCP connection to the port succeeds (something holds it). */
+ bound: boolean;
+ /**
+  * 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;
 };
 
 /**
- * Pure decision: reclaim a base port whose holder 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.
+ * 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 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.health !== null) return false;
+ if (!probe.bound) return false;
+ if (probe.healthOurs) return false;
  return true;
 }
 
 /**
  * Dislodge a dark holder from the base port so a fresh daemon can bind it.
- * Returns true when a healthy proxy answers afterwards (attach to it);
- * false when the caller should spawn fresh (port presumably free).
- * Honors the no-kill env opt-out; a live holder is never touched here —
- * the stale-replace path owns versioned daemons.
+ * Returns true when a healthy proxy answers afterwards (attach to it); false
+ * when the caller should spawn fresh (the port is free — nothing to reclaim).
+ * Honors the no-kill env opt-out; a live holder is never touched here — the
+ * stale-replace path owns versioned daemons.
  */
 async function reclaimDarkHolder(port: number): Promise<boolean> {
- const alive = await isProxyAlive(port);
- const health = alive ? null : await getDaemonHealth(port);
- if (!shouldReclaimDarkHolder({ alive, 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));
@@ -723,26 +797,185 @@ export async function ensureProxyReady(
  return { ok: false, port, reason: proxyDownMessage(port) };
 }
 
+/** True when any path segment of `filePath` is `node_modules`. Node refuses to
+ * strip types for files under such a path (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING),
+ * so a Node-spawned daemon must run from a staged copy elsewhere. */
+export function isUnderNodeModules(filePath: string): boolean {
+ return filePath.split(/[\\/]/).includes("node_modules");
+}
+
+function readPackageJsonObject(dir: string): Record<string, unknown> | null {
+ try {
+  const raw: unknown = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  return raw && typeof raw === "object" ? (raw as Record<string, unknown>) : null;
+ } catch {
+  return null;
+ }
+}
+
+/** Resolve a dependency's package directory the way Node would: walk up the
+ *  node_modules chain from the importing package's root. */
+function resolvePackageDir(name: string, fromDir: string): string | null {
+ let dir = fromDir;
+ for (; ;) {
+  const pkgJson = path.join(dir, "node_modules", name, "package.json");
+  if (fs.existsSync(pkgJson)) return path.dirname(pkgJson);
+  const parent = path.dirname(dir);
+  if (parent === dir) return null;
+  dir = parent;
+ }
+}
+
+/** Link (or copy, when linking is unavailable) each runtime dependency beside
+ *  the staged sources so bare imports such as `undici` still resolve. */
+function stageRuntimeDependencies(pkgRoot: string, pkgJson: Record<string, unknown>, stagedDir: string): void {
+ const deps = pkgJson.dependencies;
+ if (!deps || typeof deps !== "object") return;
+ const nodeModulesDir = path.join(stagedDir, "node_modules");
+ for (const name of Object.keys(deps as Record<string, unknown>)) {
+  const target = resolvePackageDir(name, pkgRoot);
+  if (target === null) {
+   logWarn("daemon dependency not found for staging", { dependency: name });
+   continue;
+  }
+  try {
+   fs.mkdirSync(nodeModulesDir, { recursive: true });
+   // Junction on Windows (no elevated privileges needed); dir symlink elsewhere.
+   fs.symlinkSync(target, path.join(nodeModulesDir, name), process.platform === "win32" ? "junction" : "dir");
+  } catch {
+   try {
+    fs.cpSync(target, path.join(nodeModulesDir, name), { recursive: true, dereference: true });
+   } catch (e) {
+    logWarn("daemon dependency staging failed", { dependency: name, error: String(e) });
+   }
+  }
+ }
+}
+
+/** Best-effort prune of staged daemon sources from earlier versions (1 day TTL). */
+function pruneStaleDaemonSrcDirs(root: string, currentVersion: string): void {
+ try {
+  const now = Date.now();
+  for (const entry of fs.readdirSync(root)) {
+   if (entry === currentVersion) continue;
+   const full = path.join(root, entry);
+   try {
+    if (now - fs.statSync(full).mtimeMs > 24 * 60 * 60 * 1000) {
+     fs.rmSync(full, { recursive: true, force: true });
+    }
+   } catch { }
+  }
+ } catch { }
+}
+
+/**
+ * Materialize the daemon's sources outside node_modules so a Node runtime can
+ * execute `src/daemon.ts` (Node refuses type stripping for any file under a
+ * node_modules path, and this package ships TypeScript sources). Copies
+ * `src/` + `package.json` into a per-version cache directory, stages the
+ * runtime dependencies beside them, and returns the staged daemon entry.
+ * Returns the input path unchanged when the script is already outside
+ * node_modules (dev checkouts) or the package root is unreadable.
+ */
+export function materializeDaemonSources(scriptPath: string, cacheDir?: string): string {
+ if (!isUnderNodeModules(scriptPath)) return scriptPath;
+ const pkgRoot = path.dirname(path.dirname(scriptPath));
+ const pkgJson = readPackageJsonObject(pkgRoot);
+ const version = pkgJson !== null && typeof pkgJson.version === "string" ? pkgJson.version : "";
+ if (pkgJson === null || !version) return scriptPath;
+
+ const root = cacheDir ?? resolveDaemonSrcCacheDir();
+ const finalDir = path.join(root, version);
+ const finalEntry = path.join(finalDir, "src", "daemon.ts");
+ if (fs.existsSync(finalEntry) && fs.existsSync(path.join(finalDir, "package.json"))) {
+  pruneStaleDaemonSrcDirs(root, version);
+  return finalEntry;
+ }
+
+ const tmpDir = `${finalDir}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+ try {
+  fs.mkdirSync(path.join(tmpDir, "src"), { recursive: true });
+  fs.cpSync(path.join(pkgRoot, "src"), path.join(tmpDir, "src"), { recursive: true });
+  fs.copyFileSync(path.join(pkgRoot, "package.json"), path.join(tmpDir, "package.json"));
+  stageRuntimeDependencies(pkgRoot, pkgJson, tmpDir);
+  try {
+   fs.renameSync(tmpDir, finalDir);
+   logInfo(`staged proxy daemon sources outside node_modules at ${finalDir}`);
+  } catch (e) {
+   // A concurrent starter won the rename (or the dir appeared meanwhile):
+   // its copy is byte-identical for the same version, so reuse it.
+   try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+   } catch { }
+   if (!fs.existsSync(finalEntry)) {
+    logWarn("daemon source staging failed", { error: String(e), dir: finalDir });
+    return scriptPath;
+   }
+  }
+ } catch (e) {
+  try {
+   fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch { }
+  logWarn("daemon source staging failed — spawning from the installed path", { error: String(e), dir: tmpDir });
+  return scriptPath;
+ }
+ pruneStaleDaemonSrcDirs(root, version);
+ return finalEntry;
+}
+
+export interface DaemonChild {
+ pid?: number;
+ exitCode: number | null;
+ signalCode: string | null;
+ unref(): void;
+ on(event: "error", listener: (err: Error) => void): unknown;
+}
+
+export type DaemonSpawner = (
+ command: string,
+ args: string[],
+ options: Parameters<typeof spawn>[2],
+) => DaemonChild;
+
+let daemonSpawner: DaemonSpawner = spawn;
+/** Children that failed to launch (spawn error) — the ready-wait treats them as exited. */
+const failedDaemonSpawns = new WeakSet<DaemonChild>();
+
+/** Test seam: replace the child spawner used for detached daemon starts. */
+export function _setDaemonSpawnForTest(spawner: DaemonSpawner | null): void {
+ daemonSpawner = spawner ?? spawn;
+}
+
+/** True once a spawned daemon child has exited (exit code or signal). */
+export function hasChildExited(child: Pick<DaemonChild, "exitCode" | "signalCode">): boolean {
+ return child.exitCode !== null || child.signalCode !== null;
+}
+
 let lastSpawnAt = 0;
 const SPAWN_THROTTLE_MS = 2_000;
 
-function spawnDaemonProcess(): boolean {
+function spawnDaemonProcess(): DaemonChild | null {
  const now = Date.now();
  if (now - lastSpawnAt < SPAWN_THROTTLE_MS) {
   logWarn("daemon spawn throttled — recent spawn still pending");
-  return false;
+  return null;
  }
  const runtime = resolveDaemonRuntime();
  if (!runtime) {
   logWarn(
    `cannot spawn detached proxy daemon: no node or bun runtime found (process.execPath "${process.execPath}" is not a JS runtime) — falling back to in-process proxy`,
   );
-  return false;
+  return null;
  }
+ // Node refuses to strip types for files under node_modules, so stage the
+ // sources elsewhere before spawning with a Node runtime (issue #52).
+ const scriptArg = runtime.args[runtime.args.length - 1] ?? "";
+ const stagedScript = runtime.runtimeType === "node" ? materializeDaemonSources(scriptArg) : scriptArg;
+ const args = stagedScript === scriptArg ? runtime.args : [...runtime.args.slice(0, -1), stagedScript];
  lastSpawnAt = now;
  const logFd = openDaemonLogFd();
  try {
-  const child = spawn(runtime.execPath, runtime.args, {
+  const child = daemonSpawner(runtime.execPath, args, {
    detached: true,
    stdio: logFd === null ? "ignore" : ["ignore", logFd, logFd],
    windowsHide: true,
@@ -753,15 +986,16 @@ function spawnDaemonProcess(): boolean {
   });
   child.unref();
   logInfo(
-   `spawned proxy daemon process (pid ${child.pid ?? "unknown"}) using ${runtime.runtimeType} (${runtime.execPath}) for :${PORT}`,
+   `spawned proxy daemon process (pid ${child.pid ?? "unknown"}) using ${runtime.runtimeType} (${runtime.execPath}) for :${PORT}${stagedScript === scriptArg ? "" : " [staged sources]"}`,
   );
   child.on("error", (err) => {
+   failedDaemonSpawns.add(child);
    logWarn("daemon spawn failed", { error: String(err), execPath: runtime.execPath });
   });
-  return true;
+  return child;
  } catch (e) {
   logWarn("daemon spawn failed", { error: String(e), execPath: runtime.execPath });
-  return false;
+  return null;
  } finally {
   if (logFd !== null) {
    try {
@@ -771,10 +1005,22 @@ function spawnDaemonProcess(): boolean {
  }
 }
 
-async function waitForReady(port: number, timeoutMs: number): Promise<boolean> {
+export async function waitForReady(
+	port: number,
+	timeoutMs: number,
+	child?: DaemonChild | null,
+): Promise<boolean> {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
 		if (await isProxyAlive(port, 150)) return true;
+		if (child && (hasChildExited(child) || failedDaemonSpawns.has(child))) {
+			logWarn("daemon child exited before becoming ready", {
+				port,
+				exitCode: child.exitCode,
+				signalCode: child.signalCode,
+			});
+			return false;
+		}
 		await new Promise<void>((r) => setTimeout(r, 80));
 	}
 	return false;
@@ -801,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);
@@ -812,16 +1076,17 @@ export async function ensureDaemon(): Promise<number> {
 
 
 		if (isSpawnEnabled()) {
-			const spawned = spawnDaemonProcess();
-   if (spawned) {
-    const ready = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS);
+			const child = spawnDaemonProcess();
+   if (child) {
+    const ready = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS, child);
     if (ready) {
      const ver = await getDaemonVersion(PORT);
      if (ver !== null && ver !== PKG_VERSION) {
       if (await killStaleDaemon(PORT, ver, "proxy daemon")) {
        lastSpawnAt = 0; // kill-confirmed retry bypasses the spawn throttle
-       if (spawnDaemonProcess()) {
-        const retryReady = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS);
+       const retryChild = spawnDaemonProcess();
+       if (retryChild) {
+        const retryReady = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS, retryChild);
         if (retryReady) {
          await attachTo(PORT);
          return PORT;
@@ -836,13 +1101,14 @@ export async function ensureDaemon(): Promise<number> {
       return PORT;
      }
     } else {
-     // The spawn never answered: it crashed instantly or a dark holder owns
-     // the base port (bind fails, probes fail).
+     // The spawn never answered: the child exited before binding (e.g. Node
+     // refusing type stripping under a node_modules path) or a dark holder
+     // owns the base port (bind fails, probes fail).
      if (await reclaimDarkHolder(PORT)) {
       await attachTo(PORT);
       return PORT;
      }
-     logWarn("daemon spawn did not become ready — is the port blocked?");
+     logWarn("daemon spawn did not become ready — child exited or the port is blocked");
     }
    }
    // Fall through to the in-process fallback below — never hand the caller
@@ -873,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 {
@@ -900,7 +1163,9 @@ export function _resetClientForTest(): void {
  heartbeatPort = 0;
  attachedPort = 0;
  ensuring = false;
+ ensureInFlight = null;
  lastSpawnAt = 0;
+ daemonSpawner = spawn;
  _resetUaRefreshForTest();
  _resetRecoveryForTest();
  if (fallbackServer) {