pi-freeflow 1.9.5 → 1.9.6

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to pi-freeflow. Public, user-visible behavior only.
 
+## 1.9.6 - 2026-09-03
+
+### Fixes
+- **Hiding the status widget now sticks.** `/freeflow hide` survives restarts, new sessions, and background update notices — previously the widget could reappear on the next session.
+- **Calmer startup with many sessions.** Sessions starting at the same time now converge on a single background proxy instead of each spawning its own; a spawn that never becomes ready falls back to in-process mode instead of running untracked.
+- **Survives daemon restarts mid-session.** If the background proxy is replaced while sessions run, connected sessions re-register automatically instead of silently losing their lease (which could retire the daemon mid-use).
+- **Stale-version cleanup targets the right process.** Windows port matching is now exact, and Linux without `lsof`/`fuser` resolves the holder via `/proc` instead of giving up.
+- **`/freeflow logs --follow` no longer runs forever.** The live tail stops when the session ends and caps burst output; the update/install subprocess now has a 2-minute timeout.
+
+### Validation
+- `npx tsc --noEmit` clean, `npm test` 299 (298 pass + 1 Linux-only skip) + smoke green on Windows; stress harness 7/7 on Windows and Linux `acerblue-local`. **`macOS not tested`** this cycle.
+
 ## 1.9.5 - 2026-09-03
 
 ### Changes

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "pi-freeflow",
-  "type": "module",
-  "version": "1.9.5",
-  "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",
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "oh-my-pi",
-    "omp",
-    "free-models",
-    "opencode",
-    "kilocode",
-    "ai-models",
-    "relay"
-  ],
-  "author": "trefeon",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/trefeon/pi-freeflow.git"
-  },
-  "homepage": "https://github.com/trefeon/pi-freeflow#readme",
-  "engines": {
-    "node": ">=22.19.0"
-  },
-  "omp": {
-    "extensions": [
-      "./extensions"
-    ]
-  },
-  "pi": {
-    "extensions": [
-      "./extensions"
-    ]
-  },
-  "files": [
-    "extensions",
-    "src",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --experimental-strip-types --import ./test/setup.mjs --test --test-concurrency=1 test/**/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "smoke": "node --experimental-strip-types -e \"import('./extensions/index.ts').then(() => console.log('✓ Smoke test passed: extensions/index.ts loaded successfully')).catch(err => { console.error(err); process.exit(1); })\"",
-    "changeset": "changeset",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.27.0",
-    "@types/node": "^22.13.9",
-    "typescript": "^5.8.2",
-    "vitepress": "^1.6.4"
-  },
-  "dependencies": {}
-}
+{
+  "name": "pi-freeflow",
+  "type": "module",
+  "version": "1.9.6",
+  "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",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "oh-my-pi",
+    "omp",
+    "free-models",
+    "opencode",
+    "kilocode",
+    "ai-models",
+    "relay"
+  ],
+  "author": "trefeon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trefeon/pi-freeflow.git"
+  },
+  "homepage": "https://github.com/trefeon/pi-freeflow#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "omp": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2",
+    "vitepress": "^1.6.4"
+  },
+  "dependencies": {},
+  "scripts": {
+    "test": "node --experimental-strip-types --import ./test/setup.mjs --test --test-concurrency=1 test/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node --experimental-strip-types -e \"import('./extensions/index.ts').then(() => console.log('✓ Smoke test passed: extensions/index.ts loaded successfully')).catch(err => { console.error(err); process.exit(1); })\"",
+    "changeset": "changeset",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
+  }
+}

package/src/client.ts

@@ -63,7 +63,7 @@ function isSpawnEnabled(): boolean {
 	return process.env[DAEMON_SPAWN_ENV] !== "0";
 }
 
-type ControlResult = "ok" | "legacy" | "gone";
+type ControlResult = "ok" | "unknown" | "legacy" | "gone";
 
 async function controlCall(
 	port: number,
@@ -77,7 +77,12 @@ async function controlCall(
 			body: JSON.stringify(payload),
 			signal: AbortSignal.timeout(1500),
 		});
-		return res.ok ? "ok" : "legacy";
+		if (!res.ok) return "legacy";
+		try {
+			const data: unknown = await res.json();
+			if (data && typeof data === "object" && "ok" in data && data.ok === false) return "unknown";
+		} catch {}
+		return "ok";
 	} catch {
 		return "gone";
 	}
@@ -122,6 +127,9 @@ async function beatOnce(port: number): Promise<void> {
 	const result = await controlCall(port, "/_client/heartbeat", { id: CLIENT_ID });
 	if (result === "gone") {
 		void ensureDaemon();
+	} else if (result === "unknown") {
+		// Daemon restarted since attach: re-register our lease.
+		await attachTo(port);
 	}
 }
 
@@ -259,13 +267,22 @@ export async function ensureDaemon(): Promise<number> {
 		}
 
 		if (isSpawnEnabled()) {
+			// Cross-process race guard: a sibling session may be spawning right
+			// now (singleflight is per-process). Jitter + re-probe converts most
+			// cold-start races into attach instead of N detached spawns.
+			await new Promise<void>((r) => setTimeout(r, 100 + Math.random() * 200));
+			if (await isProxyAlive(PORT)) {
+				await attachTo(PORT);
+				return PORT;
+			}
 			spawnDaemonProcess();
 			const ready = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS);
 			if (ready) {
 				const ver = await getDaemonVersion(PORT);
 				if (ver !== null && ver !== PKG_VERSION) {
-					if (await killStaleDaemon(PORT, ver, "proxy daemon")) {
-						spawnDaemonProcess();
+				if (await killStaleDaemon(PORT, ver, "proxy daemon")) {
+					lastSpawnAt = 0; // kill-confirmed retry bypasses the spawn throttle
+					spawnDaemonProcess();
 						const retryReady = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS);
 						if (retryReady) {
 							await attachTo(PORT);
@@ -282,7 +299,8 @@ export async function ensureDaemon(): Promise<number> {
 			} else {
 				logWarn("daemon spawn did not become ready — is the port blocked?");
 			}
-			return PORT;
+			// Fall through to the in-process fallback below — never hand the caller
+			// a port we did not attach to (no lease, no heartbeat).
 		}
 
 		try {

package/src/commands.ts

@@ -68,6 +68,7 @@ function spawnWithProgress(
 	cmd: string,
 	args: string[],
 	ctx: ExtensionContext,
+	timeoutMs = 120_000,
 ): Promise<number> {
 	const { promise, resolve } = Promise.withResolvers<number>();
 	try {
@@ -76,6 +77,16 @@ function spawnWithProgress(
 			stdio: "pipe",
 			windowsHide: true,
 		});
+		const timer = setTimeout(() => {
+			try { child.kill(); } catch {}
+			ctx.ui.notify(`spawn ${cmd} timed out after ${timeoutMs}ms — killed`, "warning");
+			resolve(1);
+		}, timeoutMs);
+		try { timer.unref?.(); } catch {}
+		const done = (code: number | null): void => {
+			clearTimeout(timer);
+			resolve(code ?? 0);
+		};
 		child.stdout?.on("data", (d: Buffer) => {
 			const s = String(d).trim();
 			if (s) ctx.ui.notify(s, "info");
@@ -85,10 +96,11 @@ function spawnWithProgress(
 			if (s) ctx.ui.notify(s, "info");
 		});
 		child.on("error", (err: Error) => {
+			clearTimeout(timer);
 			ctx.ui.notify(`spawn ${cmd} failed: ${err.message}`, "warning");
 			resolve(1);
 		});
-		child.on("close", (code: number | null) => resolve(code ?? 0));
+		child.on("close", done);
 	} catch (e) {
 		ctx.ui.notify(`spawn ${cmd} failed: ${(e as Error).message}`, "warning");
 		resolve(1);
@@ -100,8 +112,15 @@ function spawnWithProgress(
  * Follow-mode log poller: tracks the count of matched lines already printed
  * and notifies only lines beyond it, so repeated ticks never re-notify the
  * same tail. One poller at a time — a re-run clears the previous interval.
+ * Stop with stopLogsFollow (session shutdown / non-follow commands).
  */
 let logsFollowTimer: NodeJS.Timeout | null = null;
+export function stopLogsFollow(): void {
+	if (logsFollowTimer) {
+		clearInterval(logsFollowTimer);
+		logsFollowTimer = null;
+	}
+}
 function startLogsFollow(
 	ctx: ExtensionContext,
 	filterLevel: LogLevel | null,
@@ -110,10 +129,7 @@ function startLogsFollow(
 	filterText: string | null,
 	baselineMatched: number,
 ): void {
-	if (logsFollowTimer) {
-		clearInterval(logsFollowTimer);
-		logsFollowTimer = null;
-	}
+	stopLogsFollow();
 	let lastPrinted = baselineMatched;
 	logsFollowTimer = setInterval(() => {
 		try {
@@ -127,7 +143,7 @@ function startLogsFollow(
 			if (newCount <= 0) return;
 			const newLines = tail.lines.slice(
 				tail.lines.length - Math.min(newCount, tail.lines.length),
-			);
+			).slice(-50);
 			if (newLines.length > 0) {
 				ctx.ui.notify(newLines.join("\n"), "info");
 			}

package/src/index.ts

@@ -17,7 +17,7 @@ import {
 	setAliveCatalog,
 } from "./catalog.ts";
 import { ensureDaemon as ensureClientDaemon, getClientPort, stopHeartbeat } from "./client.ts";
-import { createCommandSpec, updateStatusBar } from "./commands.ts";
+import { createCommandSpec, stopLogsFollow, updateStatusBar } from "./commands.ts";
 import { HOST, ONBOARDED_FLAG_FILE, PORT } from "./config.ts";
 import { logInfo, logWarn } from "./logger.ts";
 import { ALL_MODELS, KILO_MODEL_IDS, MODEL_MAP, resolveCanonicalModelId } from "./models.ts";
@@ -330,5 +330,6 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	});
 	pi.on?.("session_shutdown", () => {
 		stopHeartbeat();
+		stopLogsFollow();
 	});
 }

package/src/lease.ts

@@ -32,11 +32,13 @@ export function registerClient(clientId: string): void {
 	leases.set(clientId, Date.now());
 }
 
-/** Renew an existing client lease (unknown ids are ignored). */
-export function renewClient(clientId: string): void {
+/** Renew an existing client lease. Returns false when the id is unknown (daemon restarted). */
+export function renewClient(clientId: string): boolean {
 	if (leases.has(clientId)) {
 		leases.set(clientId, Date.now());
+		return true;
 	}
+	return false;
 }
 
 /** Remove a client lease (graceful detach on session end). */

package/src/proxy.ts

@@ -6,6 +6,7 @@
  */
 
 import { randomUUID } from "node:crypto";
+import fs from "node:fs";
 import { execSync } from "node:child_process";
 import * as http from "node:http";
 import * as https from "node:https";
@@ -177,6 +178,63 @@ export async function getDaemonVersion(port: number): Promise<string | null> {
 	return h ? h.version : null;
 }
 
+/**
+ * Linux fallback when neither lsof nor fuser exists: resolve the LISTEN
+ * socket inode for `port` via /proc/net/tcp{,6}, then find the owning pid by
+ * scanning /proc fds. Dependency-free, same-user only, never self-kills.
+ */
+function killViaProcNet(port: number): boolean {
+	if (process.platform !== "linux") return false;
+	try {
+		const hexPort = port.toString(16).toUpperCase().padStart(4, "0");
+		const inodes = new Set<string>();
+		for (const table of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+			let text = "";
+			try {
+				text = fs.readFileSync(table, "utf8");
+			} catch {
+				continue;
+			}
+			for (const line of text.split("\n").slice(1)) {
+				const cols = line.trim().split(/\s+/);
+				if (cols.length < 10) continue;
+				const addr = cols[1].split(":");
+				if (addr.length !== 2 || addr[1].toUpperCase() !== hexPort) continue;
+				if (cols[3] !== "0A") continue; // LISTEN only
+				inodes.add(cols[9]);
+			}
+		}
+		if (inodes.size === 0) return false;
+		for (const pid of fs.readdirSync("/proc")) {
+			if (!/^\d+$/.test(pid) || Number(pid) === process.pid) continue;
+			let fds: string[];
+			try {
+				fds = fs.readdirSync(`/proc/${pid}/fd`);
+			} catch {
+				continue;
+			}
+			for (const fd of fds) {
+				let link = "";
+				try {
+					link = fs.readlinkSync(`/proc/${pid}/fd/${fd}`);
+				} catch {
+					continue;
+				}
+				const sock = link.match(/^socket:\[(\d+)\]$/);
+				if (sock && inodes.has(sock[1])) {
+					try {
+						process.kill(Number(pid), "SIGKILL");
+						return true;
+					} catch {
+						return false;
+					}
+				}
+			}
+		}
+	} catch {}
+	return false;
+}
+
 export async function killPortHolder(port: number): Promise<boolean> {
 	if (!Number.isInteger(port) || port < 1 || port > 65535) return false;
 	try {
@@ -189,8 +247,10 @@ export async function killPortHolder(port: number): Promise<boolean> {
 				}) as string;
 				for (const line of out.split("\n")) {
 					if (!line.includes("LISTENING")) continue;
-					if (!line.includes(`:${port}`)) continue;
 					const parts = line.trim().split(/\s+/);
+					// Match the port on the Local Address column only — a raw
+					// substring match can hit longer ports (:2818 vs :28180).
+					if (!parts[1] || !parts[1].endsWith(`:${port}`)) continue;
 					const pid = parts[parts.length - 1];
 					if (!pid || !/^\d+$/.test(pid)) continue;
 					// Windows netstat report: 127.0.0.1:38180 ... LISTENING/PID
@@ -206,13 +266,14 @@ export async function killPortHolder(port: number): Promise<boolean> {
 				encoding: "utf8",
 				timeout: 3000,
 			}) as string;
-			const pid = out.trim().split(/\s+/)[0];
-			if (!pid || !/^\d+$/.test(pid)) return false;
-			if (Number(pid) === process.pid) return false; // never self-kill (Unix) — matches Windows guard at 161
-			execSync(`kill -9 ${pid}`, { timeout: 3000, stdio: "ignore" });
+			const pids = out.trim().split(/\s+/).filter((p) => /^\d+$/.test(p) && Number(p) !== process.pid);
+			// lsof matches both ends of a connection: our own recent probe socket
+			// (TIME_WAIT) can sort first, so skip self instead of taking [0].
+			if (pids.length === 0) return killViaProcNet(port);
+			execSync(`kill -9 ${pids[0]}`, { timeout: 3000, stdio: "ignore" });
 			return true;
 		} catch {
-			return false;
+			return killViaProcNet(port);
 		}
 	} catch {
 		return false;
@@ -271,8 +332,15 @@ export function handleControlRequest(
 			return;
 		}
 		if (reqPathname === "/_client/attach") registerClient(clientId);
-		else if (reqPathname === "/_client/heartbeat") renewClient(clientId);
-		else if (reqPathname === "/_client/detach") unregisterClient(clientId);
+		else if (reqPathname === "/_client/heartbeat") {
+			// Unknown id = daemon restarted since attach. Report ok:false so the
+			// client re-attaches instead of heartbeating lease-less.
+			if (!renewClient(clientId)) {
+				res.writeHead(200, { "content-type": "application/json" });
+				res.end(JSON.stringify({ ok: false }));
+				return;
+			}
+		} else if (reqPathname === "/_client/detach") unregisterClient(clientId);
 		else {
 			res.writeHead(404, { "content-type": "application/json" });
 			res.end(JSON.stringify({ error: "not found" }));
@@ -345,7 +413,6 @@ export function startProxy(
 			if (handleHealthRequest(req, res, realPort, getActiveRequests())) return;
 		}
 		if (req.method === "GET" && (reqPathname === "/v1/models" || reqPathname === "/v1/models/")) {
-			touchActivity();
 			const alive = getAliveCatalog();
 			const body = JSON.stringify({
 				object: "list",

package/src/relay-state.ts

@@ -117,6 +117,7 @@ function parseRelayState(raw: string): RelayState | null {
 						: s?.enabled !== false && relays.length > 0,
 			url: typeof s?.url === "string" ? s.url.trim() : (relays[0]?.url || ""),
 			relays,
+			hideWidget: s?.hideWidget === true,
 		};
 	} catch {
 		return null;
@@ -182,9 +183,10 @@ export function loadRelayState(): RelayState {
 			if (healed) {
 				return healed;
 			}
-			return { mode: "auto", enabled: true, url: "", relays: [] };
+			return { mode: "auto", enabled: true, url: "", relays: [], hideWidget: false };
 		}
-		const main = parseRelayState(fs.readFileSync(RELAY_STATE_FILE, "utf8"));
+		const raw = fs.readFileSync(RELAY_STATE_FILE, "utf8");
+		const main = parseRelayState(raw);
 		if (main) {
 			return main;
 		}
@@ -196,9 +198,15 @@ export function loadRelayState(): RelayState {
 		logWarn("relay state file unusable and no valid backup — starting fresh", {
 			path: RELAY_STATE_FILE,
 		});
-		return { mode: "auto", enabled: true, url: "", relays: [] };
+		// parse returns null on an empty pool by design (wipe-protection above);
+		// preserve an explicit hide so hide-with-zero-relays survives reload.
+		let hide = false;
+		try {
+			hide = (JSON.parse(raw) as RelayState)?.hideWidget === true;
+		} catch {}
+		return { mode: "auto", enabled: true, url: "", relays: [], hideWidget: hide };
 	} catch {
-		return { mode: "auto", enabled: true, url: "", relays: [] };
+		return { mode: "auto", enabled: true, url: "", relays: [], hideWidget: false };
 	}
 }
 
@@ -537,9 +545,6 @@ export function setActiveRelayState(s: RelayState, persist = true): void {
 // concurrent sessions cannot silently clobber each other's edits.
 
 const RELAY_STATE_LOCK_FILE = `${RELAY_STATE_FILE}.lock`;
-const LOCK_WAIT_MAX_MS = 2_000;
-const LOCK_RETRY_START_MS = 25;
-const LOCK_RETRY_MAX_MS = 200;
 /** A lock older than this is presumed abandoned (crashed holder) and taken over. */
 const LOCK_STALE_MS = 30_000;
 
@@ -571,24 +576,19 @@ function tryAcquireRelayLock(): boolean {
 
 /**
  * Apply a mutation to relay state with a compare-and-swap discipline.
- * Locks the state file (bounded retry, ~2s), loads the freshest on-disk state,
+ * Makes a single lock acquisition attempt, loads the freshest on-disk state,
  * runs the updater against it, persists atomically, and releases the lock.
- * On lock timeout the write proceeds unlocked — the atomic tmp+rename save
- * already prevents torn files; the lock only serializes write intent.
+ * When the lock is held the write proceeds unlocked — the atomic tmp+rename
+ * save already prevents torn files; the lock only serializes write intent.
+ * (Never spin here: this runs on the proxy request path and blocking the
+ * event loop stalls all in-flight streams.)
  * Returns the state that was actually persisted (also becomes the in-memory
  * active state).
  */
 export function withRelayState(updater: (s: RelayState) => RelayState): RelayState {
-	const deadline = Date.now() + LOCK_WAIT_MAX_MS;
-	let locked = tryAcquireRelayLock();
-	let delay = LOCK_RETRY_START_MS;
-	while (!locked && Date.now() < deadline) {
-		sleepSync(delay);
-		locked = tryAcquireRelayLock();
-		delay = Math.min(delay * 2, LOCK_RETRY_MAX_MS);
-	}
+	const locked = tryAcquireRelayLock();
 	if (!locked) {
-		logWarn("relay state lock held — proceeding without lock after timeout", {
+		logWarn("relay state lock held — proceeding without lock", {
 			lock: RELAY_STATE_LOCK_FILE,
 		});
 	}

package/src/update-checker.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { UPDATE_CACHE_FILE, UPDATE_CHECK_TTL_MS } from "./config.ts";
 import { logInfo } from "./logger.ts";
 import { logWarn } from "./logger.ts";
-import { getStatusUi } from "./relay-state.ts";
+import { getActiveRelayState, getStatusUi } from "./relay-state.ts";
 import type { ExtensionUIContext } from "./types.ts";
 const REGISTRY_URL = "https://registry.npmjs.org/pi-freeflow/latest";
 /** Strict semver shape: major.minor.patch with optional -prerelease or +build suffix. */
@@ -143,6 +143,10 @@ export function checkForUpdateInBackground(ui?: ExtensionUIContext | null): void
 					const local = getLocalVersion();
 					if (local && compareVersions(latest, local) > 0) {
 						logInfo(`pi-freeflow update available: ${local} -> ${latest} (run /freeflow update)`);
+						// Respect hide: log only, never re-show the widget.
+						try {
+							if (getActiveRelayState().hideWidget) return;
+						} catch {}
 						const targetUi = ui ?? null;
 						if (targetUi?.setStatus) {
 							try { targetUi.setStatus("freeflow", `update: ${local} → ${latest}`); } catch {}