pi-freeflow 1.37.1 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.37.1",
+  "version": "1.38.0",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",

package/src/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,
@@ -610,35 +612,42 @@ 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;
+ /** 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;
 };
 
 /**
- * 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.
+ * 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).
  */
 export function shouldReclaimDarkHolder(probe: DarkHolderProbe): boolean {
  if (probe.alive) return false;
+ if (!probe.bound) return false;
  if (probe.health !== null) 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;
+ 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;
  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)`,
@@ -723,26 +732,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 +921,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 +940,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;
@@ -812,16 +993,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 +1018,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
@@ -901,6 +1084,7 @@ export function _resetClientForTest(): void {
  attachedPort = 0;
  ensuring = false;
  lastSpawnAt = 0;
+ daemonSpawner = spawn;
  _resetUaRefreshForTest();
  _resetRecoveryForTest();
  if (fallbackServer) {

package/src/commands.ts

@@ -10,7 +10,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { getClientPort, isJsRuntimeExecutable, resolveDaemonRuntime } from "./client.ts";
+import { getClientPort, isJsRuntimeExecutable, materializeDaemonSources, resolveDaemonRuntime } from "./client.ts";
 import { refreshCatalog, setAliveCatalog } from "./catalog.ts";
 import { DAEMON_SPAWN_ENV, DATA_DIR_ENV, DEBUG_STATE_FILE, HOST, LOG_FILE, PORT, RELAY_STATE_FILE } from "./config.ts";
 import {
@@ -130,13 +130,17 @@ export function getStartupPlan(opts?: {
  const platform = opts?.platform ?? process.platform;
  const home = opts?.homeDir ?? os.homedir();
  const script = daemonEntryForStartup(opts?.scriptPath);
+ // A Node runtime cannot strip types for files under node_modules, so the
+ // hook must point at staged sources when the package is installed (issue #52).
+ // Bun runs TypeScript anywhere — keep its command side-effect free.
+ const nodeEntry = (): string => materializeDaemonSources(script);
  let quoted: string;
  if (opts?.execPath) {
   const type = isJsRuntimeExecutable(opts.execPath);
   if (type === "bun") {
    quoted = `"${opts.execPath}" "${script}"`;
   } else {
-   quoted = `"${opts.execPath}" --experimental-strip-types "${script}"`;
+   quoted = `"${opts.execPath}" --experimental-strip-types "${nodeEntry()}"`;
   }
  } else {
   const runtime = resolveDaemonRuntime({ scriptPath: script });
@@ -144,10 +148,10 @@ export function getStartupPlan(opts?: {
    if (runtime.runtimeType === "bun") {
     quoted = `"${runtime.execPath}" "${script}"`;
    } else {
-    quoted = `"${runtime.execPath}" --experimental-strip-types "${script}"`;
+    quoted = `"${runtime.execPath}" --experimental-strip-types "${nodeEntry()}"`;
    }
   } else {
-   quoted = `"node" --experimental-strip-types "${script}"`;
+   quoted = `"node" --experimental-strip-types "${nodeEntry()}"`;
   }
  }
  if (platform === "win32") {

package/src/config.ts

@@ -295,19 +295,44 @@ export const STRIP_HEADERS = new Set([
 ]);
 
 /** Env override that re-roots ALL pi-freeflow data files (tests/CI sandbox).
- *  Unset → ~/.pi/agent. */
+ *  Unset → pi's agent dir (PI_CODING_AGENT_DIR, else ~/.pi/agent). */
 export const DATA_DIR_ENV = "PI_FREEFLOW_DATA_DIR";
 
+/** Env var pi itself uses to re-root its config dir: pi names it
+ *  `<APP_NAME>_CODING_AGENT_DIR` (stock pi → PI_CODING_AGENT_DIR, else
+ *  ~/.pi/agent). Freeflow data files follow it so CI/containers only need to
+ *  relocate one root instead of granting write access to a hardcoded home
+ *  path; when another host (e.g. the omp plugin loader) does not set it, the
+ *  ~/.pi/agent default keeps the shared daemon/log location. */
+export const AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+
+/** Expand a leading ~ the way pi expands its own agent-dir value. */
+function expandHome(value: string): string {
+ if (value === "~") return homedir();
+ if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(homedir(), value.slice(2));
+ return value;
+}
+
 function dataDirOverride(): string | null {
  const d = process.env[DATA_DIR_ENV];
- return typeof d === "string" && d.trim() !== "" ? d : null;
+ return typeof d === "string" && d.trim() !== "" ? expandHome(d) : null;
+}
+
+function defaultAgentDir(): string {
+ const d = process.env[AGENT_DIR_ENV];
+ if (typeof d === "string" && d.trim() !== "") return expandHome(d);
+ return path.join(homedir(), ".pi", "agent");
+}
+
+function dataFilePath(name: string): string {
+ const override = dataDirOverride();
+ if (override) return path.join(override, name);
+ return path.join(defaultAgentDir(), name);
 }
 
 export function resolveRelayStatePath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-relay-state.json");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow-relay-state.json");
+  return dataFilePath("pi-freeflow-relay-state.json");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -319,9 +344,7 @@ export function resolveRelayStatePath(): string {
 
 export function resolveLogFilePath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow.log");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow.log");
+  return dataFilePath("pi-freeflow.log");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -331,16 +354,27 @@ export function resolveLogFilePath(): string {
  }
 }
 
-export function resolveCatalogCachePath(): string {
+/**
+ * Root directory for staged daemon sources — copies taken outside
+ * node_modules because Node's type stripping refuses files under a
+ * node_modules path (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING, issue #52).
+ * Version subdirectories live inside it.
+ */
+export function resolveDaemonSrcCacheDir(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-catalog-cache.json");
+  return dataFilePath("pi-freeflow-daemon-src");
+ } catch {
   return path.join(
-   homedir(),
-   ".pi",
-   "agent",
-   "pi-freeflow-catalog-cache.json",
+   path.dirname(fileURLToPath(import.meta.url)),
+   "..",
+   ".pi-freeflow-daemon-src",
   );
+ }
+}
+
+export function resolveCatalogCachePath(): string {
+ try {
+  return dataFilePath("pi-freeflow-catalog-cache.json");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -352,9 +386,7 @@ export function resolveCatalogCachePath(): string {
 
 export function resolveDebugStatePath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-debug.json");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow-debug.json");
+  return dataFilePath("pi-freeflow-debug.json");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -366,9 +398,7 @@ export function resolveDebugStatePath(): string {
 
 export function resolveUpdateCachePath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-update.json");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow-update.json");
+  return dataFilePath("pi-freeflow-update.json");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -380,9 +410,7 @@ export function resolveUpdateCachePath(): string {
 
 export function resolveOnboardedFlagPath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-onboarded");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow-onboarded");
+  return dataFilePath("pi-freeflow-onboarded");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -394,9 +422,7 @@ export function resolveOnboardedFlagPath(): string {
 
 export function resolveUpstreamHealthPath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-upstream-health.json");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow-upstream-health.json");
+  return dataFilePath("pi-freeflow-upstream-health.json");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),
@@ -408,9 +434,7 @@ export function resolveUpstreamHealthPath(): string {
 
 export function resolveSessionPinPath(): string {
  try {
-  const override = dataDirOverride();
-  if (override) return path.join(override, "pi-freeflow-session-pins.json");
-  return path.join(homedir(), ".pi", "agent", "pi-freeflow-session-pins.json");
+  return dataFilePath("pi-freeflow-session-pins.json");
  } catch {
   return path.join(
    path.dirname(fileURLToPath(import.meta.url)),

package/src/proxy.ts

@@ -10,6 +10,7 @@ import fs from "node:fs";
 import { execSync } from "node:child_process";
 import * as http from "node:http";
 import * as https from "node:https";
+import net from "node:net";
 import { handleHealthRequest, isLoopbackIP } from "./health.ts";
 import type { DaemonHealthSnapshot } from "./health.ts";
 import { registerClient, renewClient, touchActivity, unregisterClient } from "./lease.ts";
@@ -828,6 +829,31 @@ export async function isProxyAlive(port: number, timeoutMs = 600): Promise<boole
  }
 }
 
+/**
+ * True when a TCP connection to the loopback port succeeds — something holds
+ * the port (our daemon, a stale daemon, or an unrelated process). A free port
+ * refuses the connection immediately; the dark-holder reclaim path uses this
+ * to tell "nothing bound" apart from "bound but unresponsive" (issue #52: the
+ * blind kill-and-poll cost ~2s on every cold start).
+ */
+export async function isPortBound(port: number, timeoutMs = 250): Promise<boolean> {
+ if (!Number.isInteger(port) || port < 1 || port > 65535) return false;
+ return await new Promise<boolean>((resolve) => {
+  const socket = net.connect({ host: HOST, port });
+  let settled = false;
+  const settle = (value: boolean): void => {
+   if (settled) return;
+   settled = true;
+   socket.destroy();
+   resolve(value);
+  };
+  socket.setTimeout(timeoutMs, () => settle(false));
+  socket.once("connect", () => settle(true));
+  socket.once("error", () => settle(false));
+ });
+}
+
+
 let activeRequests = 0;
 
 /** Current in-flight proxied requests (guard for stale-daemon replacement). */

package/src/relay-state.ts

@@ -1,7 +1,8 @@
 /**
  * Persistent relay state manager and failover ordering for pi-freeflow
  *
- * Handles atomic state writes to ~/.pi/agent/pi-freeflow-relay-state.json.
+ * Handles atomic state writes to pi's agent dir (PI_CODING_AGENT_DIR,
+ * default ~/.pi/agent) under pi-freeflow-relay-state.json.
  */
 
 import { randomUUID } from "node:crypto";