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

package/dist/client/styles.css

@@ -1,10 +1,11 @@
-/*! tailwindcss v4.3.2 | MIT License | https://tailwindcss.com */
+/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
 @layer properties;
 @layer theme, base, components, utilities;
 @layer theme {
   :root, :host {
-    --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
-      "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+    --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
+      "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+      "Segoe UI Symbol", "Noto Color Emoji";
     --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
       "Courier New", monospace;
     --spacing: 0.25rem;
@@ -40,7 +41,7 @@
     line-height: 1.5;
     -webkit-text-size-adjust: 100%;
     tab-size: 4;
-    font-family: var(--default-font-family, ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");
+    font-family: var(--default-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");
     font-feature-settings: var(--default-font-feature-settings, normal);
     font-variation-settings: var(--default-font-variation-settings, normal);
     -webkit-tap-highlight-color: transparent;
@@ -92,7 +93,7 @@
     border-color: inherit;
     border-collapse: collapse;
   }
-  :-moz-focusring {
+  :-moz-focusring:where(:not(iframe)) {
     outline: auto;
   }
   progress {
@@ -251,7 +252,7 @@
     max-width: 440px;
   }
   .min-w-0 {
-    min-width: 0;
+    min-width: 0px;
   }
   .flex-1 {
     flex: 1;
@@ -298,40 +299,30 @@
   .gap-6 {
     gap: calc(var(--spacing) * 6);
   }
-  .space-y-0\.5 {
-    :where(& > :not(:last-child)) {
-      --tw-space-y-reverse: 0;
-      margin-block-start: calc(calc(var(--spacing) * 0.5) * var(--tw-space-y-reverse));
-      margin-block-end: calc(calc(var(--spacing) * 0.5) * calc(1 - var(--tw-space-y-reverse)));
-    }
+  :where(.space-y-0\.5 > :not(:last-child)) {
+    --tw-space-y-reverse: 0;
+    margin-block-start: calc(calc(var(--spacing) * 0.5) * var(--tw-space-y-reverse));
+    margin-block-end: calc(calc(var(--spacing) * 0.5) * calc(1 - var(--tw-space-y-reverse)));
   }
-  .space-y-1 {
-    :where(& > :not(:last-child)) {
-      --tw-space-y-reverse: 0;
-      margin-block-start: calc(var(--spacing) * var(--tw-space-y-reverse));
-      margin-block-end: calc(var(--spacing) * calc(1 - var(--tw-space-y-reverse)));
-    }
+  :where(.space-y-1 > :not(:last-child)) {
+    --tw-space-y-reverse: 0;
+    margin-block-start: calc(var(--spacing) * var(--tw-space-y-reverse));
+    margin-block-end: calc(var(--spacing) * calc(1 - var(--tw-space-y-reverse)));
   }
-  .space-y-2 {
-    :where(& > :not(:last-child)) {
-      --tw-space-y-reverse: 0;
-      margin-block-start: calc(calc(var(--spacing) * 2) * var(--tw-space-y-reverse));
-      margin-block-end: calc(calc(var(--spacing) * 2) * calc(1 - var(--tw-space-y-reverse)));
-    }
+  :where(.space-y-2 > :not(:last-child)) {
+    --tw-space-y-reverse: 0;
+    margin-block-start: calc(calc(var(--spacing) * 2) * var(--tw-space-y-reverse));
+    margin-block-end: calc(calc(var(--spacing) * 2) * calc(1 - var(--tw-space-y-reverse)));
   }
-  .space-y-4 {
-    :where(& > :not(:last-child)) {
-      --tw-space-y-reverse: 0;
-      margin-block-start: calc(calc(var(--spacing) * 4) * var(--tw-space-y-reverse));
-      margin-block-end: calc(calc(var(--spacing) * 4) * calc(1 - var(--tw-space-y-reverse)));
-    }
+  :where(.space-y-4 > :not(:last-child)) {
+    --tw-space-y-reverse: 0;
+    margin-block-start: calc(calc(var(--spacing) * 4) * var(--tw-space-y-reverse));
+    margin-block-end: calc(calc(var(--spacing) * 4) * calc(1 - var(--tw-space-y-reverse)));
   }
-  .space-y-6 {
-    :where(& > :not(:last-child)) {
-      --tw-space-y-reverse: 0;
-      margin-block-start: calc(calc(var(--spacing) * 6) * var(--tw-space-y-reverse));
-      margin-block-end: calc(calc(var(--spacing) * 6) * calc(1 - var(--tw-space-y-reverse)));
-    }
+  :where(.space-y-6 > :not(:last-child)) {
+    --tw-space-y-reverse: 0;
+    margin-block-start: calc(calc(var(--spacing) * 6) * var(--tw-space-y-reverse));
+    margin-block-end: calc(calc(var(--spacing) * 6) * calc(1 - var(--tw-space-y-reverse)));
   }
   .truncate {
     overflow: hidden;
@@ -466,30 +457,24 @@
     transition-timing-function: var(--tw-ease, var(--default-transition-timing-function));
     transition-duration: var(--tw-duration, var(--default-transition-duration));
   }
-  .hover\:bg-\[var\(--bg-hover\)\] {
-    &:hover {
-      @media (hover: hover) {
-        background-color: var(--bg-hover);
-      }
+  @media (hover: hover) {
+    .hover\:bg-\[var\(--bg-hover\)\]:hover {
+      background-color: var(--bg-hover);
     }
   }
-  .md\:grid-cols-3 {
-    @media (width >= 48rem) {
+  @media (width >= 48rem) {
+    .md\:grid-cols-3 {
       grid-template-columns: repeat(3, minmax(0, 1fr));
     }
-  }
-  .md\:grid-cols-6 {
-    @media (width >= 48rem) {
+    .md\:grid-cols-6 {
       grid-template-columns: repeat(6, minmax(0, 1fr));
     }
   }
-  .lg\:col-span-2 {
-    @media (width >= 64rem) {
+  @media (width >= 64rem) {
+    .lg\:col-span-2 {
       grid-column: span 2 / span 2;
     }
-  }
-  .lg\:grid-cols-3 {
-    @media (width >= 64rem) {
+    .lg\:grid-cols-3 {
       grid-template-columns: repeat(3, minmax(0, 1fr));
     }
   }
@@ -974,15 +959,15 @@
 }
 .stats-metric-secondary-grid {
   display: grid;
-  grid-template-columns: repeat(6, 1fr);
+  grid-template-columns: repeat(8, 1fr);
   gap: 12px;
 }
-@media (max-width: 1023px) {
+@media (max-width: 1279px) {
   .stats-metric-secondary-grid {
-    grid-template-columns: repeat(3, 1fr);
+    grid-template-columns: repeat(4, 1fr);
   }
 }
-@media (max-width: 600px) {
+@media (max-width: 767px) {
   .stats-metric-secondary-grid {
     grid-template-columns: repeat(2, 1fr);
   }

package/dist/types/client/data/view-models.d.ts

@@ -1,4 +1,12 @@
 import type { AgentType, AgentTypeStats, BehaviorOverallStats, BehaviorTimeSeriesPoint, CostTimeSeriesPoint, FolderStats, ModelPerformancePoint, TimeRange, ToolUsageStats } from "../types.js";
+export interface ConversationTokenStats {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheWriteTokens: number;
+}
+/** Sum every conversation-token bucket shown by the overview. */
+export declare function sumConversationTokens(stats: ConversationTokenStats): number;
 export interface AgentTokenSegment {
     agentType: AgentType;
     /** input + output + cache read + cache write — the displayed denominator. */
@@ -16,9 +24,8 @@ export interface AgentTokenShareView {
 /**
  * Build the "token usage by agent" breakdown: one segment per agent type that
  * appears in the data, ordered main -> subagents -> advisor, each carrying its
- * token total and share of the grand total. Token counts sum the same four
- * columns the overview renders (input + output + cache read + cache write) so a
- * segment's share never disagrees with the count beside it.
+ * token total and share of the grand total. Token counts use the same four
+ * conversation-token buckets as the overview total so the two views reconcile.
  */
 export declare function buildAgentTokenShare(stats: AgentTypeStats[]): AgentTokenShareView;
 export interface CostSummaryView {

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.6",
 	"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.6",
+		"@oh-my-pi/pi-catalog": "17.0.6",
+		"@oh-my-pi/pi-utils": "17.0.6",
 		"@tailwindcss/node": "^4.3.2",
 		"chart.js": "^4.5.1",
 		"date-fns": "^4.4.0",

package/src/client/data/view-models.ts

@@ -14,6 +14,18 @@ import type {
 /** Fixed display order for the agent-token-share breakdown. */
 const AGENT_TYPE_ORDER: AgentType[] = ["main", "subagent", "advisor"];
 
+export interface ConversationTokenStats {
+	totalInputTokens: number;
+	totalOutputTokens: number;
+	totalCacheReadTokens: number;
+	totalCacheWriteTokens: number;
+}
+
+/** Sum every conversation-token bucket shown by the overview. */
+export function sumConversationTokens(stats: ConversationTokenStats): number {
+	return stats.totalInputTokens + stats.totalOutputTokens + stats.totalCacheReadTokens + stats.totalCacheWriteTokens;
+}
+
 export interface AgentTokenSegment {
 	agentType: AgentType;
 	/** input + output + cache read + cache write — the displayed denominator. */
@@ -33,25 +45,21 @@ export interface AgentTokenShareView {
 /**
  * Build the "token usage by agent" breakdown: one segment per agent type that
  * appears in the data, ordered main -> subagents -> advisor, each carrying its
- * token total and share of the grand total. Token counts sum the same four
- * columns the overview renders (input + output + cache read + cache write) so a
- * segment's share never disagrees with the count beside it.
+ * token total and share of the grand total. Token counts use the same four
+ * conversation-token buckets as the overview total so the two views reconcile.
  */
 export function buildAgentTokenShare(stats: AgentTypeStats[]): AgentTokenShareView {
 	const byType = new Map<AgentType, AgentTypeStats>();
 	for (const stat of stats) byType.set(stat.agentType, stat);
 
-	const tokensOf = (stat: AgentTypeStats) =>
-		stat.totalInputTokens + stat.totalOutputTokens + stat.totalCacheReadTokens + stat.totalCacheWriteTokens;
-
 	const present = AGENT_TYPE_ORDER.map(type => byType.get(type)).filter(
 		(stat): stat is AgentTypeStats => stat !== undefined,
 	);
-	const totalTokens = present.reduce((sum, stat) => sum + tokensOf(stat), 0);
+	const totalTokens = present.reduce((sum, stat) => sum + sumConversationTokens(stat), 0);
 	const totalCost = present.reduce((sum, stat) => sum + stat.totalCost, 0);
 
 	const segments = present.map(stat => {
-		const tokens = tokensOf(stat);
+		const tokens = sumConversationTokens(stat);
 		return {
 			agentType: stat.agentType,
 			tokens,

package/src/client/routes/OverviewRoute.tsx

@@ -226,8 +226,8 @@ export function OverviewRoute({ active, range, refreshTrigger, onRequestClick }:
 			</AsyncBoundary>
 
 			<Panel
-				title="Token Usage by Agent"
-				subtitle="Share of tokens across the main agent, task subagents, and the advisor"
+				title="Conversation Tokens by Agent"
+				subtitle="Uncached input + cache reads + cache writes + output, grouped by agent type"
 			>
 				<AsyncBoundary loading={overviewLoading} error={overviewError} data={overview}>
 					{overview && <AgentTokenShare stats={overview.byAgentType} />}

package/src/client/styles.css

@@ -581,17 +581,17 @@
 
 .stats-metric-secondary-grid {
   display: grid;
-  grid-template-columns: repeat(6, 1fr);
+  grid-template-columns: repeat(8, 1fr);
   gap: 12px;
 }
 
-@media (max-width: 1023px) {
+@media (max-width: 1279px) {
   .stats-metric-secondary-grid {
-    grid-template-columns: repeat(3, 1fr);
+    grid-template-columns: repeat(4, 1fr);
   }
 }
 
-@media (max-width: 600px) {
+@media (max-width: 767px) {
   .stats-metric-secondary-grid {
     grid-template-columns: repeat(2, 1fr);
   }

package/src/client/ui/MetricCluster.tsx

@@ -6,6 +6,7 @@ import {
 	formatPercent,
 	formatTokensPerSecond,
 } from "../data/formatters";
+import { sumConversationTokens } from "../data/view-models";
 import type { AggregatedStats } from "../types";
 
 export interface MetricClusterProps {
@@ -13,6 +14,8 @@ export interface MetricClusterProps {
 }
 
 export function MetricCluster({ stats }: MetricClusterProps) {
+	const conversationTokens = sumConversationTokens(stats);
+
 	return (
 		<div className="stats-metric-cluster">
 			<div className="stats-metric-primary-grid">
@@ -37,14 +40,22 @@ export function MetricCluster({ stats }: MetricClusterProps) {
 			</div>
 
 			<div className="stats-metric-secondary-grid">
-				<div className="stats-metric-card secondary">
-					<div className="stats-metric-label">Input Tokens</div>
+				<div className="stats-metric-card secondary" title="Conversation input not served from cache">
+					<div className="stats-metric-label">Uncached Input</div>
 					<div className="stats-metric-value">{formatCompact(stats.totalInputTokens)}</div>
 				</div>
+				<div className="stats-metric-card secondary" title="Conversation input read from the prompt cache">
+					<div className="stats-metric-label">Cache Read</div>
+					<div className="stats-metric-value">{formatCompact(stats.totalCacheReadTokens)}</div>
+				</div>
 				<div className="stats-metric-card secondary">
 					<div className="stats-metric-label">Output Tokens</div>
 					<div className="stats-metric-value">{formatCompact(stats.totalOutputTokens)}</div>
 				</div>
+				<div className="stats-metric-card secondary" title="Uncached input + cache reads + cache writes + output">
+					<div className="stats-metric-label">Conversation Total</div>
+					<div className="stats-metric-value">{formatCompact(conversationTokens)}</div>
+				</div>
 				<div className="stats-metric-card secondary">
 					<div className="stats-metric-label">Premium Requests</div>
 					<div className="stats-metric-value">{formatInteger(stats.totalPremiumRequests)}</div>

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";
+}