pi-freeflow 1.38.5 → 1.39.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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.
+> 35 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** |
+| **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** |
 | **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,12 +48,12 @@ 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/deepseek-v4.1-flash-free "build me a SaaS"
 omp -p --model freeflow/space-bunny:high "solve this bug"   # alias + thinking level
 ```
 
@@ -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,21 +213,20 @@ The same command set works identically in OMP and Pi:
 
 ---
 
-### 36 models, one command
+### 35 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
+#### OpenCode Zen (12 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` | ✅ |
@@ -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                # 35-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.39.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,
@@ -130,6 +130,11 @@ 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",
 ]);
 /**
  * Free-tier allowlist for anything entering the picker via network or stale disk.
@@ -169,7 +174,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 35 verified models for 0ms instant availability.
  */
 let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
  ...m,
@@ -288,10 +293,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 +339,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 +415,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() });

package/src/client.ts

@@ -52,8 +52,10 @@ import {
  reprobeBasePortAlive,
  startProxy,
 } from "./proxy.ts";
-import { compareVersions } from "./update-checker.ts";
+import { compareVersions } from "./update-core.ts";
+import { isDaemonIdentityBody } from "./health.ts";
 import type { DaemonHealthSnapshot } from "./health.ts";
+import { tokenAuthHeaders } from "./token.ts";
 
 const CLIENT_ID = randomUUID();
 
@@ -81,7 +83,7 @@ let lastUaRefreshAt = 0;
 /** Test-injected fetch for the background UA refresh; null = global fetch. */
 let uaRefreshFetch: typeof fetch | null = null;
 
-export interface DaemonRuntime {
+interface DaemonRuntime {
  execPath: string;
  args: string[];
  runtimeType: "bun" | "node";
@@ -250,7 +252,7 @@ async function controlCall(
  try {
   const res = await fetch(`http://${HOST}:${port}${endpoint}`, {
    method: "POST",
-   headers: { "content-type": "application/json" },
+   headers: { "content-type": "application/json", ...tokenAuthHeaders() },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(getControlTimeoutMs()),
   });
@@ -524,7 +526,7 @@ async function triggerRecovery(port: number, why: string): Promise<void> {
  * stopHeartbeat → busy-ruled kill → ensureDaemon when the daemon is stale or
  * degraded. Healthy ticks reset backoff/breaker and track the busy edge.
  */
-export async function watchdogCheck(port: number): Promise<void> {
+async function watchdogCheck(port: number): Promise<void> {
  if (ensuring) return;
  if (isBreakerHalted()) return;
  let health: Awaited<ReturnType<typeof getDaemonHealth>>;
@@ -618,7 +620,7 @@ async function killStaleDaemon(
  * stdio "ignore". Returns the fd, or null when the file is unavailable
  * (the spawn then falls back to ignore).
  */
-export function openDaemonLogFd(): number | null {
+function openDaemonLogFd(): number | null {
  try {
   fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
   return fs.openSync(LOG_FILE, "a");
@@ -627,58 +629,56 @@ export function openDaemonLogFd(): number | null {
  }
 }
 
-export type DarkHolderProbe = {
- /** True when GET /v1/models answers with a JSON catalog on the port. */
+type DarkHolderProbe = {
+ /** True when GET /health identifies a pi-freeflow daemon on the port. */
  alive: boolean;
  /** 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.
+  * True when GET /health answers in OUR daemon's identity shape (service +
+  * the bound port). 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.
+ * True when a /health response body carries OUR daemon's identity: the
+ * pi-freeflow service marker plus the port it is bound to (src/health.ts
+ * builds both 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;
+ return isDaemonIdentityBody(port, body);
 }
 
 /**
  * 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.
+ * sequence it replaces: an identity-answering daemon is live, a refused port
+ * is free, and only a bound-but-silent holder is asked again with a longer
+ * budget (a slow daemon still counts as ours).
  */
 export async function probeDarkHolder(port: number): Promise<DarkHolderProbe> {
- if (await isProxyAlive(port)) return { alive: true, bound: true, healthOurs: false };
+ if (await isProxyAlive(port)) return { alive: true, bound: true, healthOurs: true };
  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.
+ * Fetch GET /health and keep the verdict only when the body is OUR daemon's
+ * identity shape. Same request as proxy.isProxyAlive but with the longer
+ * daemon budget, so a slow-but-ours daemon is not mistaken for a stranger.
  */
 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`, {
+  const res = await fetch(`http://${HOST}:${port}/health`, {
    signal: AbortSignal.timeout(2500),
   });
   if (!res.ok) return false;
-  return isOurDaemonHealthBody(port, await res.json());
+  return isDaemonIdentityBody(port, await res.json());
  } catch {
   return false;
  }
@@ -686,13 +686,13 @@ async function probeOurHealth(port: number): Promise<boolean> {
 
 /**
  * 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
+ * succeeds) yet does not answer GET /health in OUR identity shape. A live
+ * daemon — stale, busy, even mid-stream — always answers it 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.
+ * answering /health with anything but our identity (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;
@@ -725,6 +725,9 @@ async function reclaimDarkHolder(port: number): Promise<boolean> {
   await new Promise<void>((r) => setTimeout(r, 200));
   if (await isProxyAlive(port)) return true;
  }
+ if (await isPortBound(port)) {
+  logWarn(`port :${port} is still held by a process we could not (and must not) kill — starting the in-process proxy instead`);
+ }
  return false;
 }
 
@@ -773,7 +776,7 @@ export function proxyDownMessage(port: number): string {
  );
 }
 
-export type ProxyReadiness = { ok: true; port: number } | { ok: false; port: number; reason: string };
+type ProxyReadiness = { ok: true; port: number } | { ok: false; port: number; reason: string };
 
 /**
  * Health probe before requests: when the loopback answers, no respawn runs.
@@ -800,7 +803,7 @@ export async function ensureProxyReady(
 /** 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 {
+function isUnderNodeModules(filePath: string): boolean {
  return filePath.split(/[\\/]/).includes("node_modules");
 }
 
@@ -923,7 +926,7 @@ export function materializeDaemonSources(scriptPath: string, cacheDir?: string):
  return finalEntry;
 }
 
-export interface DaemonChild {
+interface DaemonChild {
  pid?: number;
  exitCode: number | null;
  signalCode: string | null;
@@ -931,7 +934,7 @@ export interface DaemonChild {
  on(event: "error", listener: (err: Error) => void): unknown;
 }
 
-export type DaemonSpawner = (
+type DaemonSpawner = (
  command: string,
  args: string[],
  options: Parameters<typeof spawn>[2],
@@ -1145,19 +1148,10 @@ export function getClientPort(): number {
  return attachedPort || PORT;
 }
 
-export function getClientId(): string {
- return CLIENT_ID;
-}
-
 export function hasFallbackServer(): boolean {
  return fallbackServer !== null;
 }
 
-/** Test seam: true when client heartbeat timer is active. */
-export function isHeartbeatActive(): boolean {
- return heartbeatTimer !== null;
-}
-
 export function _resetClientForTest(): void {
  stopHeartbeatInternal();
  heartbeatPort = 0;