pi-freeflow 1.9.1 → 1.9.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to pi-freeflow. Public, user-visible behavior only.
 
+## 1.9.2 - 2026-08-31
+
+### Fixes
+- **Closing one session no longer stops the shared local proxy.** The proxy daemon
+  is now a fully detached background process: it outlives any single OMP/Pi session
+  (previously, closing the session that owned the daemon could shut it down even
+  while other sessions were still using it). It retires by itself only when no
+  session is connected, no request is in flight, and it has been idle for a grace
+  period. The next use starts it again automatically.
+- New command: `/freeflow kill` (aliases `stop`, `shutdown`) stops the background
+  daemon on demand. The next freeflow use restarts it.
+
+### Improvements
+- The proxy tracks connected sessions and last request time; `/freeflow status`
+  and the health endpoint now report active session leases, so you can see when
+  other sessions are keeping the daemon alive.
+- Docs: the command reference now lists `kill`, and the FAQ explains the shared
+  daemon lifecycle (survives session close; self-retires when unused).
+
 ## 1.9.1 - 2026-08-30
 
 ### Fixes

package/README.md

@@ -117,6 +117,7 @@ Manage your relay pool directly from the OMP / Pi terminal:
 /freeflow refresh                 # Reload the model catalog from live upstreams
 /freeflow update                  # Check for and install a package update
 /freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
+/freeflow kill                    # Stop the shared proxy daemon now (restarts on next use)
 ```
 
 ---
@@ -286,6 +287,13 @@ with a log note instead). If a daemon cannot be replaced (e.g. port held by an u
 it falls back to reusing it with a warning. To disable replacement entirely, set the no-kill env
 to `1` before starting a session.
 
+**What happens when I close a session?**
+Nothing visible to your other sessions. The proxy daemon is a separate background
+process shared by every OMP/Pi session on the machine. Closing one session just
+unregisters it; the daemon keeps serving the rest and retires itself automatically
+once the last client disconnects and it has been idle for a short grace period.
+To stop it manually, run `/freeflow kill` — the next freeflow use starts it again.
+
 **Where's the normalizer?**
 Deleted in 1.3.0. If zai/qwen/deepseek thinking broke before, it's fixed now because host handles it.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "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

@@ -0,0 +1,313 @@
+/**
+ * Client-side daemon lifecycle for pi-freeflow.
+ *
+ * Every OMP/Pi session is a client. It attaches to the shared detached daemon
+ * at 127.0.0.1:28180 (or spawns one if none is alive), registers a lease, and
+ * renews it with a heartbeat while the session lives. When the session ends
+ * the heartbeat stops; the daemon drops the lease after its TTL and retires
+ * once no client holds a live lease and no request has been proxied recently.
+ */
+
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type * as http from "node:http";
+import {
+	DAEMON_HEARTBEAT_MS,
+	DAEMON_HEARTBEAT_MS_ENV,
+	DAEMON_READY_TIMEOUT_MS,
+	DAEMON_SPAWN_ENV,
+	HOST,
+	LEGACY_PORT,
+	NO_KILL_ENV,
+	PKG_VERSION,
+	PORT,
+} from "./config.ts";
+import { logInfo, logWarn } from "./logger.ts";
+import {
+	getDaemonHealth,
+	getDaemonVersion,
+	isProxyAlive,
+	killPortHolder,
+	startProxy,
+} from "./proxy.ts";
+import { compareVersions } from "./update-checker.ts";
+
+const CLIENT_ID = randomUUID();
+
+let attachedPort = 0;
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+let heartbeatPort = 0;
+let ensuring = false;
+let fallbackServer: http.Server | null = null;
+
+function isBunRuntime(): boolean {
+	return typeof (process.versions as unknown as Record<string, string>).bun === "string";
+}
+
+function daemonScriptPath(): string {
+	return path.join(path.dirname(fileURLToPath(import.meta.url)), "daemon.ts");
+}
+
+function getHeartbeatMs(): number {
+	const raw = process.env[DAEMON_HEARTBEAT_MS_ENV];
+	if (raw) {
+		const parsed = Number(raw);
+		if (Number.isFinite(parsed) && parsed > 0) return parsed;
+	}
+	return DAEMON_HEARTBEAT_MS;
+}
+
+function isSpawnEnabled(): boolean {
+	return process.env[DAEMON_SPAWN_ENV] !== "0";
+}
+
+type ControlResult = "ok" | "legacy" | "gone";
+
+async function controlCall(
+	port: number,
+	endpoint: string,
+	payload: Record<string, string>,
+): Promise<ControlResult> {
+	try {
+		const res = await fetch(`http://${HOST}:${port}${endpoint}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(1500),
+		});
+		return res.ok ? "ok" : "legacy";
+	} catch {
+		return "gone";
+	}
+}
+
+function startHeartbeat(port: number): void {
+	stopHeartbeatInternal();
+	heartbeatPort = port;
+	const ms = getHeartbeatMs();
+	heartbeatTimer = setInterval(() => {
+		void beatOnce(port);
+	}, ms);
+	try {
+		heartbeatTimer.unref();
+	} catch {}
+}
+
+function stopHeartbeatInternal(): void {
+	if (heartbeatTimer !== null) {
+		clearInterval(heartbeatTimer);
+		heartbeatTimer = null;
+	}
+}
+
+export function stopHeartbeat(): void {
+	const port = heartbeatPort;
+	stopHeartbeatInternal();
+	heartbeatPort = 0;
+	if (port) {
+		void controlCall(port, "/_client/detach", { id: CLIENT_ID });
+	}
+	if (fallbackServer) {
+		try {
+			fallbackServer.close();
+		} catch {}
+		fallbackServer = null;
+	}
+}
+
+async function beatOnce(port: number): Promise<void> {
+	if (ensuring) return;
+	const result = await controlCall(port, "/_client/heartbeat", { id: CLIENT_ID });
+	if (result === "gone") {
+		void ensureDaemon();
+	}
+}
+
+async function attachTo(port: number): Promise<void> {
+	attachedPort = port;
+	const result = await controlCall(port, "/_client/attach", { id: CLIENT_ID });
+	if (result === "gone") {
+		return;
+	}
+	startHeartbeat(port);
+}
+
+async function shouldReplaceDaemon(port: number, remoteVer: string): Promise<boolean> {
+	if (NO_KILL_ENV && process.env[NO_KILL_ENV] === "1") {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (replacement disabled by env)`,
+		);
+		return false;
+	}
+	if (compareVersions(remoteVer, PKG_VERSION) > 0) {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (newer daemon v${remoteVer} left running)`,
+		);
+		return false;
+	}
+	const health = await getDaemonHealth(port);
+	if (health === null || health.activeRequests === undefined) {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (cannot verify usage — leaving the running daemon untouched)`,
+		);
+		return false;
+	}
+	if (health.activeRequests > 0) {
+		logInfo(
+			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (${health.activeRequests} active request${health.activeRequests === 1 ? "" : "s"} — not interrupted)`,
+		);
+		return false;
+	}
+	return true;
+}
+
+async function killStaleDaemon(
+	port: number,
+	remoteVer: string,
+	what: string,
+): Promise<boolean> {
+	if (!(await shouldReplaceDaemon(port, remoteVer))) return false;
+	logWarn(`stale ${what} v${remoteVer} on :${port} (need v${PKG_VERSION}) — replacing`, {
+		remoteVer,
+		expected: PKG_VERSION,
+	});
+	await killPortHolder(port);
+	for (let i = 0; i < 10; i++) {
+		await new Promise<void>((r) => setTimeout(r, 200));
+		if (!(await isProxyAlive(port))) return true;
+	}
+	logInfo(
+		`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (stale kill did not free port)`,
+	);
+	return false;
+}
+
+function spawnDaemonProcess(): void {
+	const script = daemonScriptPath();
+	const args = isBunRuntime() ? [script] : ["--experimental-strip-types", script];
+	try {
+		const child = spawn(process.execPath, args, {
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		child.unref();
+		child.on("error", (err) => {
+			logWarn("daemon spawn failed", { error: String(err) });
+		});
+	} catch (e) {
+		logWarn("daemon spawn failed", { error: String(e) });
+	}
+}
+
+async function waitForReady(port: number, timeoutMs: number): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (await isProxyAlive(port)) return true;
+		await new Promise<void>((r) => setTimeout(r, 200));
+	}
+	return false;
+}
+
+async function probeAndMaybeReplace(
+	port: number,
+	label: string,
+): Promise<number | null> {
+	if (!(await isProxyAlive(port))) return null;
+	const ver = await getDaemonVersion(port);
+	if (ver !== null && ver !== PKG_VERSION) {
+		if (await killStaleDaemon(port, ver, label)) {
+			return null;
+		}
+		if (await isProxyAlive(port)) return port;
+		return null;
+	}
+	return port;
+}
+
+/**
+ * Ensure a proxy daemon is running and attach this client to it.
+ * Returns the port the caller should use for its ProviderConfig.
+ */
+export async function ensureDaemon(): Promise<number> {
+	if (ensuring) return attachedPort || PORT;
+	ensuring = true;
+	try {
+		const primary = await probeAndMaybeReplace(PORT, "proxy daemon");
+		if (primary !== null) {
+			await attachTo(primary);
+			return primary;
+		}
+
+		if (PORT !== LEGACY_PORT) {
+			const legacy = await probeAndMaybeReplace(LEGACY_PORT, "legacy proxy daemon");
+			if (legacy !== null) {
+				await attachTo(legacy);
+				return legacy;
+			}
+		}
+
+		if (isSpawnEnabled()) {
+			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();
+						const retryReady = await waitForReady(PORT, DAEMON_READY_TIMEOUT_MS);
+						if (retryReady) {
+							await attachTo(PORT);
+							return PORT;
+						}
+					} else if (await isProxyAlive(PORT)) {
+						await attachTo(PORT);
+						return PORT;
+					}
+				} else {
+					await attachTo(PORT);
+					return PORT;
+				}
+			} else {
+				logWarn("daemon spawn did not become ready — is the port blocked?");
+			}
+			return PORT;
+		}
+
+		try {
+			const r = await startProxy();
+			if (r.server) fallbackServer = r.server;
+			const port = r.port;
+			await attachTo(port);
+			return port;
+		} catch (e) {
+			logWarn("in-process fallback bind failed", { error: String(e) });
+			return PORT;
+		}
+	} finally {
+		ensuring = false;
+	}
+}
+
+export function getClientPort(): number {
+	return attachedPort || PORT;
+}
+
+export function getClientId(): string {
+	return CLIENT_ID;
+}
+
+export function _resetClientForTest(): void {
+	stopHeartbeatInternal();
+	heartbeatPort = 0;
+	attachedPort = 0;
+	ensuring = false;
+	if (fallbackServer) {
+		try {
+			fallbackServer.close();
+		} catch {}
+		fallbackServer = null;
+	}
+}

package/src/commands.ts

@@ -5,8 +5,9 @@
  */
 
 import { spawn } from "node:child_process";
+import { getClientPort } from "./client.ts";
 import { refreshCatalog, setAliveCatalog } from "./catalog.ts";
-import { DEBUG_STATE_FILE, LOG_FILE, RELAY_STATE_FILE } from "./config.ts";
+import { DEBUG_STATE_FILE, HOST, LOG_FILE, PORT, RELAY_STATE_FILE } from "./config.ts";
 import {
 	compareVersions,
 	fetchLatestVersion,
@@ -532,6 +533,21 @@ export function createCommandSpec(
 				}`;
 				const stateFileLine = `State file: ${RELAY_STATE_FILE}`;
 				ctx.ui.notify(`${modeLine} | ${poolLine}\n${stateFileLine}`, "info");
+			} else if (sub === "kill" || sub === "stop" || sub === "shutdown") {
+				const port = getClientPort() || PORT;
+				try {
+					const res = await fetch(`http://${HOST}:${port}/_shutdown`, {
+						method: "POST",
+						signal: AbortSignal.timeout(1500),
+					});
+					if (res.ok) {
+						ctx.ui.notify("Proxy daemon stopped — next freeflow use restarts it", "info");
+					} else {
+						ctx.ui.notify(`Daemon kill got HTTP ${res.status}`, "warning");
+					}
+				} catch {
+					ctx.ui.notify("Daemon not running or not reachable", "warning");
+				}
 			} else if (sub === "update") {
 				if (isLinkedInstall()) {
 					ctx.ui.notify(

package/src/config.ts

@@ -205,7 +205,34 @@ export const UPDATE_CHECK_TTL_MS = 86_400_000;
 export const ALLOW_UNSAFE_RELAY_ENV = "PI_FREEFLOW_ALLOW_UNSAFE_RELAY";
 /** Opt-out for the stale-daemon replace: when "1", a version-mismatched daemon is never killed. */
 export const NO_KILL_ENV = ALLOW_UNSAFE_RELAY_ENV.replace("_ALLOW_UNSAFE_RELAY", "_NO_KILL");
-/** Max request body the proxy buffers before responding 413. */
+/** When "0", the extension never spawns a detached proxy daemon (tests/CI). */
+export const DAEMON_SPAWN_ENV = DATA_DIR_ENV.replace("_DATA_DIR", "_DAEMON_SPAWN");
+/** Lease TTL for attached clients (ms); expired leases are dropped by the daemon GC. */
+export const DAEMON_TTL_MS_ENV = DATA_DIR_ENV.replace("_DATA_DIR", "_DAEMON_TTL_MS");
+/** Client heartbeat interval (ms) — must stay well under the lease TTL. */
+export const DAEMON_HEARTBEAT_MS_ENV = DATA_DIR_ENV.replace("_DATA_DIR", "_DAEMON_HEARTBEAT_MS");
+/** Daemon GC sweep interval (ms). */
+export const DAEMON_GC_MS_ENV = DATA_DIR_ENV.replace("_DATA_DIR", "_DAEMON_GC_MS");
+/** Idle grace after the last request before a lease-less daemon exits (ms). */
+export const DAEMON_GRACE_MS_ENV = DATA_DIR_ENV.replace("_DATA_DIR", "_DAEMON_GRACE_MS");
+/** Max time a client waits for a freshly spawned daemon to answer /_health (ms). */
+export const DAEMON_READY_TIMEOUT_MS_ENV = DATA_DIR_ENV.replace("_DATA_DIR", "_DAEMON_READY_TIMEOUT_MS");
+
+function envMs(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (raw) {
+		const parsed = Number(raw);
+		if (Number.isFinite(parsed) && parsed > 0) return parsed;
+	}
+	return fallback;
+}
+
+export const DAEMON_SPAWN_ENABLED = process.env[DAEMON_SPAWN_ENV] !== "0";
+export const DAEMON_TTL_MS = envMs(DAEMON_TTL_MS_ENV, 30_000);
+export const DAEMON_HEARTBEAT_MS = envMs(DAEMON_HEARTBEAT_MS_ENV, 10_000);
+export const DAEMON_GC_MS = envMs(DAEMON_GC_MS_ENV, 5_000);
+export const DAEMON_GRACE_MS = envMs(DAEMON_GRACE_MS_ENV, 10_000);
+export const DAEMON_READY_TIMEOUT_MS = envMs(DAEMON_READY_TIMEOUT_MS_ENV, 5_000);
 export const MAX_BODY_BYTES = 32 * 1024 * 1024;
 /** Default timeout for upstream headers while proxying a request. */
 export const UPSTREAM_HEADER_TIMEOUT_MS = 300_000;

package/src/daemon.ts

@@ -0,0 +1,140 @@
+/**
+ * Detached proxy daemon entry for pi-freeflow.
+ *
+ * Spawned as a separate OS process by src/client.ts so the local proxy survives
+ * the OMP/Pi session that started it. Owns port 28180, serves the proxy plus
+ * the client lease/control endpoints, and retires itself once no client holds
+ * a live lease and no request has been proxied recently.
+ *
+ * Run directly: `node --experimental-strip-types src/daemon.ts` (or `bun src/daemon.ts`).
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	DAEMON_GC_MS,
+	DAEMON_GRACE_MS,
+	DAEMON_TTL_MS,
+	HOST,
+	PKG_VERSION,
+	PORT,
+} from "./config.ts";
+import { setShutdownShouldExit } from "./proxy.ts";
+import {
+	getAliveCatalog,
+	readCatalogCache,
+	refreshCatalog,
+	setAliveCatalog,
+} from "./catalog.ts";
+import { log, logInfo, logWarn } from "./logger.ts";
+import {
+	startLeaseGC,
+	stopLeaseGC,
+	touchActivity,
+} from "./lease.ts";
+import { getActiveRequests, startProxy } from "./proxy.ts";
+import { loadRelayState, setActiveRelayState } from "./relay-state.ts";
+
+/** True when this module was run as the entry script (not imported by tests). */
+export function isDaemonMain(): boolean {
+	try {
+		const entry = process.argv[1];
+		if (!entry) return false;
+		return path.resolve(entry) === fileURLToPath(import.meta.url);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Load the on-disk relay state into this process's in-memory cache so routing
+ * uses the latest client edits without a daemon restart. Non-fatal on failure.
+ */
+export function syncRelayStateFromDisk(): void {
+	try {
+		setActiveRelayState(loadRelayState(), false);
+	} catch (e) {
+		log("warn", "daemon failed to load relay state from disk", { error: String(e) });
+	}
+}
+
+/**
+ * Serve the static+disk catalog and refresh it in the background, mirroring
+ * what the host session did in-process. Keeps /v1/models correct after the
+ * 24h cache TTL without requiring a daemon restart.
+ */
+export async function seedCatalog(): Promise<void> {
+	const cached = readCatalogCache();
+	if (cached && Array.isArray(cached.models) && cached.models.length > 0) {
+		setAliveCatalog(cached.models);
+	}
+	try {
+		const fresh = await refreshCatalog(false);
+		if (fresh.length > 0) {
+			setAliveCatalog(fresh);
+		}
+	} catch (e) {
+		logWarn("daemon catalog refresh failed; retaining cached catalog", {
+			error: String(e),
+		});
+	}
+	logInfo(`daemon catalog ready: ${getAliveCatalog().length} models`);
+}
+
+/**
+ * Boot the detached proxy daemon. Binds the port, seeds catalog + relay state,
+ * starts the lease GC, and installs signal handlers so the daemon exits
+ * cleanly on SIGTERM/SIGINT (e.g. /freeflow kill, taskkill, Ctrl+C).
+ */
+export async function runDaemon(): Promise<void> {
+	let server: { close(): void } | null = null;
+	const retire = (why: string): void => {
+		logInfo(`daemon retiring: ${why}`);
+		stopLeaseGC();
+		try {
+			server?.close();
+		} catch {}
+		process.exit(0);
+	};
+	process.on("SIGTERM", () => retire("SIGTERM"));
+	process.on("SIGINT", () => retire("SIGINT"));
+	setShutdownShouldExit(true);
+	try {
+		const r = await startProxy();
+		if (!r.server) {
+			// Port was taken by another (possibly newer) daemon — the parent
+			// attaches to the winner; this spawn exits quietly.
+			logInfo(`daemon found an existing proxy on http://${HOST}:${r.port} — exiting`);
+			process.exit(0);
+		}
+		server = r.server;
+	} catch (e) {
+		log("error", "daemon failed to bind proxy port", { error: String(e) });
+		process.exit(1);
+	}
+
+	// lastActivityAt is initialized AT BIND TIME: a freshly started daemon with
+	// zero leases must never be GC'd during the parent's readiness-poll window.
+	touchActivity();
+	syncRelayStateFromDisk();
+	void seedCatalog();
+
+	startLeaseGC({
+		ttlMs: DAEMON_TTL_MS,
+		gcMs: DAEMON_GC_MS,
+		graceMs: DAEMON_GRACE_MS,
+		getActiveRequests,
+		onIdle: () => retire("no clients and idle"),
+	});
+
+	logInfo(`pi-freeflow daemon v${PKG_VERSION} listening on http://${HOST}:${PORT}`);
+}
+
+// Entry guard: run only when executed as the entry script. When imported by
+// tests, isDaemonMain() is false and no port is bound.
+if (isDaemonMain()) {
+	runDaemon().catch((e) => {
+		log("error", "daemon crashed", { error: String(e) });
+		process.exit(1);
+	});
+}

package/src/health.ts

@@ -6,6 +6,7 @@
 import type * as http from "node:http";
 import { ALL_MODELS } from "./models.ts";
 import { getActiveRelayState, getRelayHealth, isRelayHealthy } from "./relay-state.ts";
+import { getLastActivityAt, getLeaseCount, getLeaseSnapshot } from "./lease.ts";
 import { PKG_VERSION, PORT } from "./config.ts";
 
 export interface HealthRelayInfo {
@@ -26,7 +27,14 @@ export interface HealthData {
 	version: string;
 	/** In-flight proxied requests right now (stale-daemon replacement guard). */
 	activeRequests: number;
+	/** Clients holding a live lease (detached-daemon GC). */
+	clients: number;
+	/** clientId -> lastSeenAt for every live lease. */
+	leases: Record<string, number>;
+	/** Last time any request was proxied (request-touch for legacy clients). */
+	lastActivityAt: number;
 }
+
 /**
  * Collect current health snapshot.
  * @param portOverride - actual listening port (defaults to config PORT)
@@ -54,10 +62,16 @@ export function getHealthData(portOverride?: number, activeRequests = 0): Health
 		catalog: ALL_MODELS.length,
 		version: PKG_VERSION,
 		activeRequests,
+		clients: getLeaseCount(),
+		leases: getLeaseSnapshot(),
+		lastActivityAt: getLastActivityAt(),
 	};
 }
 
-function isLoopbackIP(ip: string): boolean {
+/**
+ * Check whether an IP address is a loopback address (127.0.0.1, ::1, localhost).
+ */
+export function isLoopbackIP(ip: string): boolean {
 	if (!ip) return false;
 	const withoutZone = ip.split("%")[0];
 	const clean = withoutZone.startsWith("::ffff:") ? withoutZone.slice(7) : withoutZone;
@@ -75,38 +89,31 @@ export function handleHealthRequest(
 	portOverride?: number,
 	activeRequests = 0,
 ): boolean {
-	let pathname: string | null = null;
+	if (req.method !== "GET") return false;
+
+	let reqPathname: string | null = null;
 	try {
-		pathname = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+		reqPathname = new URL(req.url ?? "/", `http://127.0.0.1`).pathname;
 	} catch {
 		return false;
 	}
+	if (reqPathname === null) return false;
+	if (reqPathname !== "/_health" && reqPathname !== "/health") return false;
 
-	const isHealthPath = pathname === "/_health" || pathname === "/health";
-	if (req.method !== "GET" || !isHealthPath) {
-		return false;
-	}
-
-	const sock: unknown = req.socket;
-	let rawIp = "";
-	if (sock && typeof sock === "object" && "remoteAddress" in sock) {
-		const v = sock.remoteAddress;
-		if (typeof v === "string") rawIp = v;
-	}
-	const clientIP = rawIp.startsWith("::ffff:") ? rawIp.slice(7) : rawIp;
+	const clientIP = req.socket.remoteAddress ?? "";
 	if (!isLoopbackIP(clientIP)) {
-		const body = JSON.stringify({ error: "forbidden" });
-		res.writeHead(403, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });
-		res.end(body);
+		res.writeHead(403, { "content-type": "application/json" });
+		res.end(JSON.stringify({ error: "loopback only" }));
 		return true;
 	}
 
 	const data = getHealthData(portOverride, activeRequests);
-	const body = JSON.stringify(data);
+	const body = JSON.stringify(data, null, 2);
 	res.writeHead(200, {
 		"content-type": "application/json",
 		"content-length": Buffer.byteLength(body),
+		"cache-control": "no-store",
 	});
 	res.end(body);
 	return true;
-}
+}

package/src/index.ts

@@ -9,7 +9,6 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import type * as http from "node:http";
 import {
 	getAliveCatalog,
 	mergeCatalog,
@@ -17,13 +16,12 @@ import {
 	refreshCatalog,
 	setAliveCatalog,
 } from "./catalog.ts";
+import { ensureDaemon as ensureClientDaemon, getClientPort, stopHeartbeat } from "./client.ts";
 import { createCommandSpec, updateStatusBar } from "./commands.ts";
-import { HOST, LEGACY_PORT, NO_KILL_ENV, ONBOARDED_FLAG_FILE, PKG_VERSION, PORT } from "./config.ts";
-import { log, logInfo, logWarn } from "./logger.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";
-import { getDaemonHealth, getDaemonVersion, isProxyAlive, killPortHolder, startProxy } from "./proxy.ts";
-import { resetRateLimits } from "./rate-limiter.ts";
-import { checkForUpdateInBackground, compareVersions } from "./update-checker.ts";
+import { checkForUpdateInBackground } from "./update-checker.ts";
 import {
 	ensureRelay,
 	getActiveRelayState,
@@ -160,150 +158,18 @@ export function buildProviderConfig(
 		}),
 	};
 }
-
-/**
- * Stale-daemon replacement guard.
- * Never interrupt a working shared daemon: a newer-version daemon is left
- * running (downgrade case), an in-flight daemon is left running (busy case —
- * its streams would die mid-flight), a pre-1.9 daemon that cannot report
- * usage is left running (cannot verify), and NO_KILL_ENV disables replacement
- * entirely. Only older, VERIFIED-idle daemons are replaced.
- */
-async function shouldReplaceDaemon(port: number, remoteVer: string): Promise<boolean> {
-	if (NO_KILL_ENV && process.env[NO_KILL_ENV] === "1") {
-		logInfo(
-			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (replacement disabled by env)`,
-		);
-		return false;
-	}
-	if (compareVersions(remoteVer, PKG_VERSION) > 0) {
-		logInfo(
-			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (newer daemon v${remoteVer} left running)`,
-		);
-		return false;
-	}
-	const health = await getDaemonHealth(port);
-	if (health === null || health.activeRequests === undefined) {
-		// Pre-1.9 daemons do not report in-flight requests: usage cannot be
-		// verified, so the running daemon is left untouched. Interrupting a
-		// possibly-busy session is worse than keeping an older daemon alive.
-		logInfo(
-			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (cannot verify usage — leaving the running daemon untouched)`,
-		);
-		return false;
-	}
-	if (health.activeRequests > 0) {
-		logInfo(
-			`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (${health.activeRequests} active request${health.activeRequests === 1 ? "" : "s"} — not interrupted)`,
-		);
-		return false;
-	}
-	return true;
-}
-
-/**
- * Guarded kill ritual for a stale daemon: decide (older-only, verified-idle,
- * NO_KILL) → log → kill → wait for the port to free. Returns true when the
- * port stopped answering (caller re-binds or re-attaches below); false when
- * the daemon is left running — every skip reason is logged here.
- */
-async function killStaleDaemon(
-	port: number,
-	remoteVer: string,
-	what: string,
-): Promise<boolean> {
-	if (!(await shouldReplaceDaemon(port, remoteVer))) return false;
-	logWarn(`stale ${what} v${remoteVer} on :${port} (need v${PKG_VERSION}) — replacing`, {
-		remoteVer,
-		expected: PKG_VERSION,
-	});
-	await killPortHolder(port);
-	for (let i = 0; i < 10; i++) {
-		await new Promise<void>((r) => setTimeout(r, 200));
-		if (!(await isProxyAlive(port))) return true;
-	}
-	logInfo(
-		`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${port} (stale kill did not free port)`,
-	);
-	return false;
-}
 /**
  * Main extension entrypoint
  */
 export default async function (pi: ExtensionAPI): Promise<void> {
 	logInfo("pi-freeflow extension initializing...");
 
-
-	let server: http.Server | null = null;
-	let actualPort = PORT;
-
-	// 2. Single-Port Shared Pattern: Check if daemon is already running (e.g. parent session)
-	// Dual-probe: probe current PORT first; if missing, check LEGACY_PORT so existing v1.4.9
-	// sessions on 18080 are seamlessly reused without split-brain or duplicate daemons.
-	// Stale-daemon heal: if the alive daemon reports a different version (e.g. 1.7.1 vs 1.8.0
-	// after an upgrade), the auth fix never loads for the new session. Detect via /_health
-	// and best-effort replace the stale holder so old users are auto-healed.
-	let alreadyRunning = await isProxyAlive(PORT);
-	if (alreadyRunning) {
-		const remoteVer = await getDaemonVersion(PORT);
-		if (remoteVer !== null && remoteVer !== PKG_VERSION) {
-			if (await killStaleDaemon(PORT, remoteVer, "proxy daemon")) {
-				try {
-					const r = await startProxy();
-					server = r.server;
-					actualPort = r.port;
-					alreadyRunning = false;
-				} catch (e) {
-					log("error", "stale daemon replaced but fresh bind failed — reusing stale as fallback", {
-						error: String(e),
-					});
-					actualPort = PORT;
-				}
-			} else {
-				actualPort = PORT;
-			}
-		} else {
-			logInfo(`Reusing existing pi-freeflow proxy daemon on http://${HOST}:${PORT}`);
-			actualPort = PORT;
-		}
-	} else if (PORT !== LEGACY_PORT && (await isProxyAlive(LEGACY_PORT))) {
-		const remoteVer = await getDaemonVersion(LEGACY_PORT);
-		if (remoteVer !== null && remoteVer !== PKG_VERSION) {
-			if (await killStaleDaemon(LEGACY_PORT, remoteVer, "legacy proxy daemon")) {
-				try {
-					const r = await startProxy();
-					server = r.server;
-					actualPort = r.port;
-					alreadyRunning = false;
-				} catch (e) {
-					log("error", "stale legacy daemon replaced but fresh bind failed — reusing as fallback", {
-						error: String(e),
-					});
-					alreadyRunning = true;
-					actualPort = LEGACY_PORT;
-				}
-			} else {
-				alreadyRunning = true;
-				actualPort = LEGACY_PORT;
-			}
-		} else {
-			logInfo(`Reusing existing legacy pi-freeflow proxy daemon on http://${HOST}:${LEGACY_PORT}`);
-			alreadyRunning = true;
-			actualPort = LEGACY_PORT;
-		}
-	} else {
-		try {
-			const r = await startProxy();
-			server = r.server;
-			actualPort = r.port;
-		} catch (e) {
-			log(
-				"error",
-				"extension inactive — could not bind proxy port. resolve the port conflict and restart pi.",
-				{ error: String(e) },
-			);
-			return;
-		}
+	let actualPort: number;
+	try {
+		actualPort = await ensureClientDaemon();
+	} catch (e) {
+		logWarn("daemon ensure failed — using configured port", { error: String(e) });
+		actualPort = getClientPort();
 	}
 	// Register static models immediately on boot so Pi/OMP picker is populated with zero latency!
 	const registeredCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
@@ -318,63 +184,16 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			buildProviderConfig(models, actualPort),
 		);
 	};
-	let ensuringDaemon = false;
 	const ensureDaemon = async (): Promise<void> => {
-		if (ensuringDaemon) return;
-		ensuringDaemon = true;
 		try {
-			if (await isProxyAlive(actualPort)) {
-				const v = await getDaemonVersion(actualPort);
-				if (v === null || v === PKG_VERSION) return;
-				if (!(await killStaleDaemon(actualPort, v, "proxy daemon"))) return;
-			}
-			if (await isProxyAlive(PORT)) {
-				const v = await getDaemonVersion(PORT);
-				if (v === null || v === PKG_VERSION) {
-					actualPort = PORT;
-					registerCatalog(getAliveCatalog());
-					logInfo(`Re-attached to proxy daemon on http://${HOST}:${PORT}`);
-					return;
-				}
-				if (await killStaleDaemon(PORT, v, "proxy daemon")) {
-					// Port freed — fall through to legacy probe / re-bind below.
-				} else if (await isProxyAlive(PORT)) {
-					actualPort = PORT;
-					registerCatalog(getAliveCatalog());
-					logInfo(`Re-attached to proxy daemon on http://${HOST}:${PORT} (stale kill did not free port)`);
-					return;
-				} else {
-					return; // daemon replaced; re-bind happens below
-				}
+			const port = await ensureClientDaemon();
+			if (port !== actualPort) {
+				actualPort = port;
+				registerCatalog(getAliveCatalog());
+				logInfo(`Re-attached to proxy daemon on http://${HOST}:${port}`);
 			}
-			if (PORT !== LEGACY_PORT && (await isProxyAlive(LEGACY_PORT))) {
-				const v = await getDaemonVersion(LEGACY_PORT);
-				if (v === null || v === PKG_VERSION) {
-					actualPort = LEGACY_PORT;
-					registerCatalog(getAliveCatalog());
-					logInfo(`Re-attached to legacy proxy daemon on http://${HOST}:${LEGACY_PORT}`);
-					return;
-				}
-				if (await killStaleDaemon(LEGACY_PORT, v, "legacy proxy daemon")) {
-					// Port freed — fall through to the re-bind below.
-				} else if (await isProxyAlive(LEGACY_PORT)) {
-					actualPort = LEGACY_PORT;
-					registerCatalog(getAliveCatalog());
-					logInfo(`Re-attached to legacy proxy daemon on http://${HOST}:${LEGACY_PORT} (stale kill did not free port)`);
-					return;
-				} else {
-					return; // daemon replaced; re-bind happens below
-				}
-			}
-			const r = await startProxy();
-			if (r.server) server = r.server;
-			if (r.port) actualPort = r.port;
-			registerCatalog(getAliveCatalog());
-			logWarn("proxy daemon was lost — re-bound locally", { port: actualPort });
 		} catch (e) {
-			logWarn("proxy daemon lost and re-bind failed", { error: String(e) });
-		} finally {
-			ensuringDaemon = false;
+			logWarn("proxy daemon re-attach failed", { error: String(e) });
 		}
 	};
 
@@ -510,16 +329,6 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		}
 	});
 	pi.on?.("session_shutdown", () => {
-		if (server) {
-			logInfo("shutting down proxy daemon...");
-			const closing = server;
-			server = null;
-			closing.close();
-			// Node 18.2+: closeIdleConnections exists at runtime even if lib types lag
-			const closable = closing as unknown as { closeIdleConnections?: () => void };
-			closable.closeIdleConnections?.();
-			resetRateLimits();
-			logInfo("shutdown complete");
-		}
+		stopHeartbeat();
 	});
 }

package/src/lease.ts

@@ -0,0 +1,106 @@
+/**
+ * Client lease registry for the detached pi-freeflow proxy daemon.
+ *
+ * Each OMP/Pi session is a client that registers a lease and renews it with a
+ * heartbeat while alive. The daemon drops expired leases and, once NO client
+ * holds a live lease AND no request has been proxied recently, retires itself.
+ *
+ * The request-touch (`lastActivityAt`) is the fallback for legacy clients that
+ * never heartbeated: any proxied request counts as a live user, so the daemon
+ * is never idle-killed while a session is actually using it.
+ */
+
+export interface LeaseOptions {
+	/** Lease lifetime (ms); a client that misses ~3 beats is dropped. */
+	ttlMs: number;
+	/** GC sweep interval (ms). */
+	gcMs: number;
+	/** Idle grace after the last proxied request before a lease-less daemon exits (ms). */
+	graceMs: number;
+	/** Current in-flight proxied requests — daemon never exits mid-stream. */
+	getActiveRequests: () => number;
+	/** Called once when the daemon should retire (close server + exit). */
+	onIdle: () => void;
+}
+
+const leases = new Map<string, number>();
+let lastActivityAt = Date.now();
+let gcTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Register or refresh a client lease. */
+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 {
+	if (leases.has(clientId)) {
+		leases.set(clientId, Date.now());
+	}
+}
+
+/** Remove a client lease (graceful detach on session end). */
+export function unregisterClient(clientId: string): void {
+	leases.delete(clientId);
+}
+
+/** Number of clients holding a live lease. */
+export function getLeaseCount(): number {
+	return leases.size;
+}
+
+/** Snapshot of live client leases (id -> lastSeenAt) for health/debugging. */
+export function getLeaseSnapshot(): Record<string, number> {
+	return Object.fromEntries(leases);
+}
+
+/** Record proxy activity — any proxied request counts as a live user. */
+export function touchActivity(): void {
+	lastActivityAt = Date.now();
+}
+
+/** Timestamp of the last proxied request (0 = never; daemon inits at bind). */
+export function getLastActivityAt(): number {
+	return lastActivityAt;
+}
+
+/**
+ * Start the lease GC sweep. Prunes expired leases and, when no client holds a
+ * lease, nothing is in flight, and no request has been proxied within the
+ * grace window, invokes `onIdle` (the daemon retires). Idempotent — a second
+ * call is a no-op.
+ */
+export function startLeaseGC(opts: LeaseOptions): void {
+	if (gcTimer !== null) return;
+	gcTimer = setInterval(() => {
+		const now = Date.now();
+		for (const [id, seenAt] of leases) {
+			if (now - seenAt > opts.ttlMs) {
+				leases.delete(id);
+			}
+		}
+		if (
+			leases.size === 0 &&
+			opts.getActiveRequests() === 0 &&
+			now - lastActivityAt > opts.graceMs
+		) {
+			stopLeaseGC();
+			opts.onIdle();
+		}
+	}, opts.gcMs);
+}
+
+/** Stop the GC sweep (test teardown / daemon shutdown). */
+export function stopLeaseGC(): void {
+	if (gcTimer !== null) {
+		clearInterval(gcTimer);
+		gcTimer = null;
+	}
+}
+
+/** Test-only: reset all lease state. */
+export function _resetLeaseStateForTest(): void {
+	leases.clear();
+	lastActivityAt = Date.now();
+	stopLeaseGC();
+}

package/src/proxy.ts

@@ -9,9 +9,11 @@ import { randomUUID } from "node:crypto";
 import { execSync } from "node:child_process";
 import * as http from "node:http";
 import * as https from "node:https";
-import { handleHealthRequest } from "./health.ts";
+import { handleHealthRequest, isLoopbackIP } from "./health.ts";
+import { registerClient, renewClient, touchActivity, unregisterClient } from "./lease.ts";
 import { Readable } from "node:stream";
 import type { ReadableStream as WebReadableStream } from "node:stream/web";
+
 import { getAliveCatalog } from "./catalog.ts";
 import {
 	ALLOWED_METHODS,
@@ -25,6 +27,7 @@ import {
 	UPSTREAM_OPENCODE,
 	opencodeHeaders,
 } from "./config.ts";
+
 import { isDebugEnabled, log } from "./logger.ts";
 import { KILO_MODEL_IDS, resolveCanonicalModelId } from "./models.ts";
 // normalize removed — host pi-ai already normalizes thinking/reasoning before proxy
@@ -34,6 +37,12 @@ import { getActiveRelayState } from "./relay-state.ts";
 import { pipeUpstreamStream } from "./stream-pipe.ts";
 import type { Upstream } from "./types.ts";
 
+
+let shutdownShouldExit = false;
+export function setShutdownShouldExit(v: boolean): void {
+	shutdownShouldExit = v;
+}
+
 /**
  * Direct-mode 429 hint throttle: the guidance hint is emitted at most once per
  * 10 minutes per process so repeated rate-limit responses don't spam clients.
@@ -206,6 +215,71 @@ export async function killPortHolder(port: number): Promise<boolean> {
 	}
 }
 
+/**
+ * Loopback-only client lease + control endpoints used by the detached-daemon
+ * protocol (src/client.ts). Returns false when the request is not a control
+ * endpoint (caller continues). Control writes are async (chunked JSON).
+ */
+export function handleControlRequest(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+	reqPathname: string | null,
+	closeServer: () => void,
+): boolean {
+	if (reqPathname === null) return false;
+	const isShutdown = reqPathname === "/_shutdown";
+	const isClientRoute = reqPathname.startsWith("/_client/");
+	if (!isShutdown && !isClientRoute) return false;
+	const clientIP = req.socket.remoteAddress ?? "";
+	if (!isLoopbackIP(clientIP)) {
+		res.writeHead(403, { "content-type": "application/json" });
+		res.end(JSON.stringify({ error: "loopback only" }));
+		return true;
+	}
+	if (isShutdown) {
+		res.writeHead(200, { "content-type": "application/json" });
+		res.end(JSON.stringify({ ok: true }));
+		setTimeout(() => {
+			try { closeServer(); } catch {}
+			if (shutdownShouldExit) process.exit(0);
+		}, 50);
+		return true;
+	}
+	const chunks: Buffer[] = [];
+	let total = 0;
+	req.on("data", (c: Buffer) => {
+		total += c.length;
+		if (total > 4096) { req.destroy(); return; }
+		chunks.push(c);
+	});
+	req.on("end", () => {
+		let clientId = "";
+		try {
+			const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+			if (parsed && typeof parsed === "object" && "id" in parsed) {
+				const candidate = parsed.id;
+				if (typeof candidate === "string" && candidate) clientId = candidate;
+			}
+		} catch {}
+		if (!clientId) {
+			res.writeHead(400, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "missing client id" }));
+			return;
+		}
+		if (reqPathname === "/_client/attach") registerClient(clientId);
+		else if (reqPathname === "/_client/heartbeat") renewClient(clientId);
+		else if (reqPathname === "/_client/detach") unregisterClient(clientId);
+		else {
+			res.writeHead(404, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "not found" }));
+			return;
+		}
+		res.writeHead(200, { "content-type": "application/json" });
+		res.end(JSON.stringify({ ok: true }));
+	});
+	return true;
+}
+
 /**
  * Tagged abort reason for the proxy-internal header-wait timeout.
  * relayFetch rethrows AbortErrors untouched, and stream-pipe recognizes
@@ -213,9 +287,7 @@ export async function killPortHolder(port: number): Promise<boolean> {
  * rolls nor penalizes a healthy relay when the request merely ran slow.
  */
 function upstreamTimeoutError(): Error & { code: string } {
-	const err = new Error(
-		`upstream header timeout (${UPSTREAM_HEADER_TIMEOUT_MS}ms)`,
-	) as Error & { code: string };
+	const err = new Error(`upstream header timeout (${UPSTREAM_HEADER_TIMEOUT_MS}ms)`) as Error & { code: string };
 	err.name = "AbortError";
 	err.code = "FF_INTERNAL_ABORT";
 	return err;
@@ -261,6 +333,7 @@ export function startProxy(
 		try {
 			reqPathname = new URL(req.url ?? "/", `http://${HOST}`).pathname;
 		} catch {}
+		if (handleControlRequest(req, res, reqPathname, () => server.close())) return;
 		// Loopback-only health endpoint — always accessible even when widget hidden
 		if (req.method === "GET" && reqPathname !== null && (reqPathname === "/_health" || reqPathname === "/health")) {
 			const addr = server.address();
@@ -268,6 +341,7 @@ 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",
@@ -298,6 +372,7 @@ export function startProxy(
 			}
 			return;
 		}
+		touchActivity();
 		// Buffer request body to inspect model ID for upstream routing
 		const bodyChunks: Buffer[] = [];
 		activeRequests += 1;