@oh-my-pi/omp-stats 17.0.4 → 17.0.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [17.0.5] - 2026-07-18
+
+### Fixed
+
+- Fixed an EADDRINUSE error by properly reusing the live stats dashboard on the requested port and reclaiming stale listeners (#5970).
+
 ## [17.0.2] - 2026-07-17
 
 ### Fixed

package/dist/types/port-conflict.d.ts

@@ -0,0 +1,4 @@
+/** Header stamped on every dashboard response so reuse probes can identify us. */
+export declare const STATS_DASHBOARD_HEADER = "x-omp-stats-dashboard";
+/** Reuse a live stats dashboard or reclaim the port from a stale omp runtime. */
+export declare function recoverStatsPort(port: number): Promise<"retry" | "reuse">;

package/dist/types/server.d.ts

@@ -3,7 +3,7 @@
  */
 export declare function handleApi(req: Request): Promise<Response>;
 /**
- * Start the HTTP server.
+ * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
  */
 export declare function startServer(port?: number): Promise<{
     port: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "17.0.4",
+	"version": "17.0.5",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -39,9 +39,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.0.4",
-		"@oh-my-pi/pi-catalog": "17.0.4",
-		"@oh-my-pi/pi-utils": "17.0.4",
+		"@oh-my-pi/pi-ai": "17.0.5",
+		"@oh-my-pi/pi-catalog": "17.0.5",
+		"@oh-my-pi/pi-utils": "17.0.5",
 		"@tailwindcss/node": "^4.3.2",
 		"chart.js": "^4.5.1",
 		"date-fns": "^4.4.0",

package/src/port-conflict.ts

@@ -0,0 +1,250 @@
+import type { Dirent } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { $which } from "@oh-my-pi/pi-utils";
+import { $ } from "bun";
+
+const STATS_PROBE_TIMEOUT_MS = 500;
+const PROCESS_EXIT_POLL_MS = 50;
+const PROCESS_EXIT_POLLS = 10;
+const STATS_RUNTIME_IMAGES: Record<string, true> = { bun: true, node: true, omp: true, "omp-stats": true };
+
+interface PortHolder {
+	pid: number;
+	image: string;
+	commandLine: string;
+}
+
+/** Header stamped on every dashboard response so reuse probes can identify us. */
+export const STATS_DASHBOARD_HEADER = "x-omp-stats-dashboard";
+
+async function probeStatsDashboard(port: number): Promise<boolean> {
+	try {
+		const response = await fetch(`http://localhost:${port}/api/stats/models`, {
+			signal: AbortSignal.timeout(STATS_PROBE_TIMEOUT_MS),
+		});
+		if (response.status !== 200) {
+			await response.body?.cancel();
+			return false;
+		}
+		// A live omp-stats dashboard stamps this header on every response.
+		if (response.headers.get(STATS_DASHBOARD_HEADER)) {
+			await response.body?.cancel();
+			return true;
+		}
+		// Older dashboards predate the header; fall back to the response shape
+		// (`/api/stats/models` returns a JSON array) so we never reuse — or later
+		// kill — a foreign 200 responder such as an SPA dev server catch-all.
+		if (!(response.headers.get("content-type") ?? "").includes("application/json")) {
+			await response.body?.cancel();
+			return false;
+		}
+		return Array.isArray(await response.json());
+	} catch {
+		return false;
+	}
+}
+
+async function findLinuxPortHolder(port: number): Promise<PortHolder | null> {
+	const socketInodes = new Set<string>();
+	for (const tablePath of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+		let table: string;
+		try {
+			table = await Bun.file(tablePath).text();
+		} catch {
+			continue;
+		}
+
+		for (const line of table.split("\n").slice(1)) {
+			const fields = line.trim().split(/\s+/);
+			const localAddress = fields[1];
+			const state = fields[3];
+			const inode = fields[9];
+			if (!localAddress || state !== "0A" || !inode) continue;
+			const encodedPort = localAddress.slice(localAddress.lastIndexOf(":") + 1);
+			if (Number.parseInt(encodedPort, 16) === port) socketInodes.add(inode);
+		}
+	}
+	if (socketInodes.size === 0) return null;
+
+	let processes: Dirent[];
+	try {
+		processes = await fs.readdir("/proc", { withFileTypes: true });
+	} catch {
+		return null;
+	}
+
+	for (const entry of processes) {
+		if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue;
+		const pid = Number.parseInt(entry.name, 10);
+		let descriptors: string[];
+		try {
+			descriptors = await fs.readdir(`/proc/${pid}/fd`);
+		} catch {
+			continue;
+		}
+
+		let ownsSocket = false;
+		for (const descriptor of descriptors) {
+			try {
+				const target = await fs.readlink(`/proc/${pid}/fd/${descriptor}`);
+				const match = /^socket:\[(\d+)]$/.exec(target);
+				if (match?.[1] && socketInodes.has(match[1])) {
+					ownsSocket = true;
+					break;
+				}
+			} catch {}
+		}
+		if (!ownsSocket) continue;
+
+		let commandLine = "";
+		try {
+			const rawCommandLine = await Bun.file(`/proc/${pid}/cmdline`).text();
+			commandLine = rawCommandLine.split("\0").filter(Boolean).join(" ");
+		} catch {}
+
+		try {
+			const executable = await fs.readlink(`/proc/${pid}/exe`);
+			return { pid, image: path.basename(executable), commandLine };
+		} catch {
+			const executable = commandLine.split(" ", 1)[0];
+			return { pid, image: executable ? path.basename(executable) : "unknown", commandLine };
+		}
+	}
+	return null;
+}
+
+async function findMacPortHolder(port: number): Promise<PortHolder | null> {
+	const lsof = $which("lsof") ?? ((await Bun.file("/usr/sbin/lsof").exists()) ? "/usr/sbin/lsof" : null);
+	if (!lsof) return null;
+
+	const selector = `-iTCP:${port}`;
+	const result = await $`${lsof} -nP ${selector} -sTCP:LISTEN -Fpc`.quiet().nothrow();
+	if (result.exitCode !== 0) return null;
+
+	let pid: number | null = null;
+	let image = "unknown";
+	for (const line of result.text().split("\n")) {
+		if (line.startsWith("p")) {
+			const parsed = Number.parseInt(line.slice(1), 10);
+			pid = Number.isSafeInteger(parsed) ? parsed : null;
+		} else if (line.startsWith("c") && pid !== null) {
+			image = line.slice(1) || "unknown";
+			break;
+		}
+	}
+	if (pid === null) return null;
+
+	const ps = $which("ps");
+	if (!ps) return { pid, image, commandLine: "" };
+	const processInfo = await $`${ps} -ww -p ${pid} -o command=`.quiet().nothrow();
+	return { pid, image, commandLine: processInfo.exitCode === 0 ? processInfo.text().trim() : "" };
+}
+
+async function findWindowsPortHolder(port: number): Promise<PortHolder | null> {
+	const netstat = $which("netstat");
+	if (!netstat) return null;
+
+	const result = await $`${netstat} -ano -p TCP`.quiet().nothrow();
+	if (result.exitCode !== 0) return null;
+
+	let pid: number | null = null;
+	for (const line of result.text().split("\n")) {
+		const fields = line.trim().split(/\s+/);
+		if (fields[0]?.toUpperCase() !== "TCP" || fields[3]?.toUpperCase() !== "LISTENING") continue;
+		const localAddress = fields[1];
+		if (!localAddress || Number.parseInt(localAddress.slice(localAddress.lastIndexOf(":") + 1), 10) !== port) {
+			continue;
+		}
+		const parsed = Number.parseInt(fields[4] ?? "", 10);
+		if (Number.isSafeInteger(parsed)) {
+			pid = parsed;
+			break;
+		}
+	}
+	if (pid === null) return null;
+
+	let image = "unknown";
+	const tasklist = $which("tasklist");
+	if (tasklist) {
+		const filter = `PID eq ${pid}`;
+		const task = await $`${tasklist} /FI ${filter} /FO CSV /NH`.quiet().nothrow();
+		if (task.exitCode === 0) {
+			const imageMatch = /^"((?:[^"]|"")*)"/.exec(task.text().trim());
+			image = imageMatch?.[1]?.replaceAll('""', '"') || "unknown";
+		}
+	}
+
+	const powershell = $which("powershell") ?? $which("pwsh");
+	if (!powershell) return { pid, image, commandLine: "" };
+	const command = `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`;
+	const processInfo = await $`${powershell} -NoProfile -NonInteractive -Command ${command}`.quiet().nothrow();
+	return { pid, image, commandLine: processInfo.exitCode === 0 ? processInfo.text().trim() : "" };
+}
+
+async function findPortHolder(port: number): Promise<PortHolder | null> {
+	if (process.platform === "linux") return findLinuxPortHolder(port);
+	if (process.platform === "darwin") return findMacPortHolder(port);
+	if (process.platform === "win32") return findWindowsPortHolder(port);
+	return null;
+}
+
+async function terminatePortHolder(holder: PortHolder): Promise<void> {
+	try {
+		process.kill(holder.pid, "SIGTERM");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ESRCH") return;
+		throw new Error(`Failed to stop ${holder.image} (PID ${holder.pid})`, { cause: error });
+	}
+
+	for (let attempt = 0; attempt < PROCESS_EXIT_POLLS; attempt++) {
+		await Bun.sleep(PROCESS_EXIT_POLL_MS);
+		try {
+			process.kill(holder.pid, 0);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ESRCH") return;
+			throw new Error(`Failed to inspect ${holder.image} (PID ${holder.pid})`, { cause: error });
+		}
+	}
+
+	try {
+		process.kill(holder.pid, "SIGKILL");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ESRCH") return;
+		throw new Error(`Failed to kill ${holder.image} (PID ${holder.pid})`, { cause: error });
+	}
+	await Bun.sleep(PROCESS_EXIT_POLL_MS);
+}
+
+/** Reuse a live stats dashboard or reclaim the port from a stale omp runtime. */
+export async function recoverStatsPort(port: number): Promise<"retry" | "reuse"> {
+	if (await probeStatsDashboard(port)) return "reuse";
+
+	const holder = await findPortHolder(port);
+	if (!holder) {
+		throw new Error(`Port ${port} is in use, but the listening process could not be identified.`);
+	}
+	if (holder.pid === process.pid) {
+		throw new Error(`Port ${port} is held by the current process (${holder.image}, PID ${holder.pid}).`);
+	}
+
+	const normalizedImage = holder.image
+		.toLowerCase()
+		.replace(/\.exe$/, "")
+		.replace(/ \(deleted\)$/, "");
+	const normalizedCommand = holder.commandLine.toLowerCase().replaceAll("\\", "/");
+	const hasStatsIdentity =
+		normalizedImage === "omp-stats" ||
+		/(?:^|[/"'\s])omp-stats(?:\.exe)?(?:["'\s]|$)/.test(normalizedCommand) ||
+		/\/packages\/stats\/src\/index\.ts(?:["'\s]|$)/.test(normalizedCommand) ||
+		(normalizedImage === "omp" && /(?:^|\s)stats(?:\s|$)/.test(normalizedCommand)) ||
+		/(?:^|\/)omp(?:\.exe)?["'\s]+stats(?:["'\s]|$)/.test(normalizedCommand);
+	if (!STATS_RUNTIME_IMAGES[normalizedImage] || !hasStatsIdentity) {
+		throw new Error(
+			`Port ${port} is in use by ${holder.image} (PID ${holder.pid}), which is not identifiable as an omp stats dashboard; refusing to stop it.`,
+		);
+	}
+
+	await terminatePortHolder(holder);
+	return "retry";
+}

package/src/server.ts

@@ -20,6 +20,7 @@ import {
 import { decodeEmbeddedClientArchive } from "./embedded-client";
 import embeddedClientArchiveTxt from "./embedded-client.generated.txt";
 import { getGainDashboardStats } from "./gain-aggregator";
+import { recoverStatsPort, STATS_DASHBOARD_HEADER } from "./port-conflict";
 
 const EMBEDDED_CLIENT_ARCHIVE = decodeEmbeddedClientArchive(embeddedClientArchiveTxt);
 
@@ -293,23 +294,20 @@ async function handleStatic(requestPath: string): Promise<Response> {
 	return new Response("Not Found", { status: 404 });
 }
 
-/**
- * Start the HTTP server.
- */
-export async function startServer(port = 3847): Promise<{ port: number; stop: () => void }> {
-	await ensureClientBuild();
-
+function createDashboardServer(port: number) {
 	const server = Bun.serve({
 		port,
 		async fetch(req) {
 			const url = new URL(req.url);
 			const path = url.pathname;
 
-			// CORS headers for local development
-			const corsHeaders = {
+			// CORS headers for local development; the identity header lets another
+			// omp session's reuse probe positively recognize this dashboard.
+			const corsHeaders: Record<string, string> = {
 				"Access-Control-Allow-Origin": "*",
 				"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
 				"Access-Control-Allow-Headers": "Content-Type",
+				[STATS_DASHBOARD_HEADER]: "1",
 			};
 
 			if (req.method === "OPTIONS") {
@@ -327,8 +325,8 @@ export async function startServer(port = 3847): Promise<{ port: number; stop: ()
 
 				// Add CORS headers to all responses
 				const headers = new Headers(response.headers);
-				for (const [key, value] of Object.entries(corsHeaders)) {
-					headers.set(key, value);
+				for (const key in corsHeaders) {
+					headers.set(key, corsHeaders[key]);
 				}
 
 				return new Response(response.body, {
@@ -344,9 +342,39 @@ export async function startServer(port = 3847): Promise<{ port: number; stop: ()
 			}
 		},
 	});
+	return server;
+}
+
+/**
+ * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
+ */
+export async function startServer(port = 3847): Promise<{ port: number; stop: () => void }> {
+	await ensureClientBuild();
+
+	try {
+		const server = createDashboardServer(port);
+		return {
+			port: server.port ?? port,
+			stop: () => server.stop(),
+		};
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "EADDRINUSE")) throw error;
+
+		const recovery = await recoverStatsPort(port);
+		if (recovery === "reuse") {
+			return { port, stop: () => {} };
+		}
 
-	return {
-		port: server.port ?? port,
-		stop: () => server.stop(),
-	};
+		try {
+			const server = createDashboardServer(port);
+			return {
+				port: server.port ?? port,
+				stop: () => server.stop(),
+			};
+		} catch (retryError) {
+			throw new Error(`Failed to start stats dashboard on port ${port} after reclaiming it.`, {
+				cause: retryError,
+			});
+		}
+	}
 }