@oh-my-pi/omp-stats 18.13.2 → 18.14.0

package/src/db.ts

@@ -11,6 +11,7 @@ import {
 } from "@oh-my-pi/pi-catalog/models";
 import type { ModelCost } from "@oh-my-pi/pi-catalog/types";
 import { getConfigRootDir, getStatsDbPath, VERSION } from "@oh-my-pi/pi-utils";
+import { ChunkedInsert } from "./chunked-insert";
 import { classifyAgentType, type ParseSessionResult, type SessionParserState } from "./parser";
 import { ensureRollupSchema, getDailyActivityFromRollup } from "./rollup";
 import type {
@@ -135,6 +136,17 @@ export async function initDb(): Promise<Database> {
 	// https://github.com/can1357/oh-my-pi/issues/2421.
 	db.run("PRAGMA busy_timeout = 5000");
 	db.run("PRAGMA journal_mode = WAL");
+	// The database is a derived cache of the transcripts, so WAL's NORMAL sync
+	// (fsync only at checkpoints) is safe: a crash can drop the newest batches,
+	// which the next sync re-ingests from their unchanged cursors. Rarer, larger
+	// checkpoints cut the F_FULLFSYNC stalls macOS pays per checkpoint. The
+	// statement journal and temp b-tree every trigger-carrying insert opens stay
+	// in memory instead of a temp file, and a 64 MiB page cache (default 8 MiB)
+	// keeps more index pages of a multi-GB database resident between batches.
+	db.run("PRAGMA synchronous = NORMAL");
+	db.run("PRAGMA temp_store = MEMORY");
+	db.run("PRAGMA cache_size = -65536");
+	db.run("PRAGMA wal_autocheckpoint = 16384");
 
 	// Whether `messages` predates this init — drives the one-time agent_type
 	// backfill below, so it must be sampled before CREATE TABLE adds the table.
@@ -174,11 +186,17 @@ export async function initDb(): Promise<Database> {
 			UNIQUE(session_file, entry_id)
 		);
 
-		CREATE INDEX IF NOT EXISTS idx_messages_timestamp ON messages(timestamp);
-		CREATE INDEX IF NOT EXISTS idx_messages_entry_timestamp ON messages(entry_id, timestamp);
+		-- Fork-guard identity lookups key on (entry_id, timestamp). Time-first
+		-- keeps one transcript's rows in a few neighbouring leaves; entry-first
+		-- scattered every insert, delete and lookup across the whole index. The
+		-- composite also serves every timestamp range scan.
+		DROP INDEX IF EXISTS idx_messages_timestamp;
+		DROP INDEX IF EXISTS idx_messages_entry_timestamp;
+		CREATE INDEX IF NOT EXISTS idx_messages_timestamp_entry ON messages(timestamp, entry_id);
 		CREATE INDEX IF NOT EXISTS idx_messages_model ON messages(model);
 		CREATE INDEX IF NOT EXISTS idx_messages_folder ON messages(folder);
-		CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_file);
+		-- UNIQUE(session_file, entry_id) already indexes session_file lookups.
+		DROP INDEX IF EXISTS idx_messages_session;
 		CREATE INDEX IF NOT EXISTS idx_messages_timestamp_model_provider ON messages(timestamp, model, provider);
 		CREATE INDEX IF NOT EXISTS idx_messages_timestamp_folder ON messages(timestamp, folder);
 		CREATE INDEX IF NOT EXISTS idx_messages_stop_reason_timestamp ON messages(stop_reason, timestamp);
@@ -211,8 +229,9 @@ export async function initDb(): Promise<Database> {
 			UNIQUE(session_file, entry_id)
 		);
 
-		CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp ON user_messages(timestamp);
-		CREATE INDEX IF NOT EXISTS idx_user_messages_entry_timestamp ON user_messages(entry_id, timestamp);
+		DROP INDEX IF EXISTS idx_user_messages_timestamp;
+		DROP INDEX IF EXISTS idx_user_messages_entry_timestamp;
+		CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp_entry ON user_messages(timestamp, entry_id);
 		CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp_model ON user_messages(timestamp, model, provider);
 
 		-- Judge verdicts keyed by prose hash: identical messages share one verdict,
@@ -244,8 +263,9 @@ export async function initDb(): Promise<Database> {
 			UNIQUE(session_file, tool_call_id)
 		);
 
-		CREATE INDEX IF NOT EXISTS idx_tool_calls_timestamp ON tool_calls(timestamp);
-		CREATE INDEX IF NOT EXISTS idx_tool_calls_entry_timestamp ON tool_calls(entry_id, timestamp);
+		DROP INDEX IF EXISTS idx_tool_calls_timestamp;
+		DROP INDEX IF EXISTS idx_tool_calls_entry_timestamp;
+		CREATE INDEX IF NOT EXISTS idx_tool_calls_timestamp_entry ON tool_calls(timestamp, entry_id);
 		CREATE INDEX IF NOT EXISTS idx_tool_calls_tool_timestamp ON tool_calls(tool_name, timestamp);
 
 		CREATE TABLE IF NOT EXISTS meta (
@@ -348,7 +368,7 @@ export async function initDb(): Promise<Database> {
 				prose_hash TEXT NOT NULL DEFAULT '',
 				UNIQUE(session_file, entry_id)
 			);
-			CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp ON user_messages(timestamp);
+			CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp_entry ON user_messages(timestamp, entry_id);
 			CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp_model ON user_messages(timestamp, model, provider);
 		`);
 	} else if (!userMessageColumns.some(column => column.name === "prose")) {
@@ -674,6 +694,17 @@ export function setFileOffset(
 	stmt.run(sessionFile, offset, lastModified, parserState ? JSON.stringify(parserState) : null);
 }
 
+/**
+ * Run `fn` atomically: inline when the caller already holds a transaction,
+ * otherwise in a fresh one. Nesting `db.transaction` would open a savepoint,
+ * which copies every page the batch touches into the statement journal; each
+ * statement end then rewinds that ever-growing journal, so a long batch
+ * degrades quadratically.
+ */
+function atomically<T>(database: Database, fn: () => T): T {
+	return database.inTransaction ? fn() : database.transaction(fn)();
+}
+
 /** Parsed transcript queued by the sync loop for an atomic database batch. */
 export interface ParsedSession {
 	sessionFile: string;
@@ -873,7 +904,7 @@ export function completeSessionSync(reconcile: boolean): void {
  * `provider`, token counts, and `responseId`. The `UNIQUE(session_file,
  * entry_id)` constraint alone keys each row by file, so without the guard
  * below the same provider request would land twice and inflate every
- * aggregate. The `WHERE NOT EXISTS` clause skips inserts whose
+ * aggregate. The {@link ChunkedInsert} fork guard skips inserts whose
  * `(entry_id, timestamp)` already exists under a different `session_file` —
  * first-write-wins across the lineage. Same-file re-syncs still hit the
  * `ON CONFLICT(session_file, entry_id)` upsert below, which re-derives the
@@ -882,21 +913,39 @@ export function completeSessionSync(reconcile: boolean): void {
  */
 export function insertMessageStats(stats: Iterable<MessageStatsInput>): number {
 	if (!db) return 0;
-
-	const stmt = db.query(`
-		INSERT INTO messages (
-			session_file, entry_id, folder, model, provider, api, timestamp,
-			duration, ttft, stop_reason, error_message,
-			input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, total_tokens, premium_requests,
-			cost_input, cost_output, cost_cache_read, cost_cache_write, cost_total, cost_no_cache_input,
-			cost_unpriced, agent_type, service_tier
-		)
-		SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
-		WHERE NOT EXISTS (
-			SELECT 1 FROM messages
-			WHERE entry_id = ? AND timestamp = ? AND session_file <> ?
-		)
-		ON CONFLICT(session_file, entry_id) DO UPDATE SET
+	const writer = new ChunkedInsert(db, {
+		verb: "INSERT",
+		table: "messages",
+		columns: [
+			"session_file",
+			"entry_id",
+			"folder",
+			"model",
+			"provider",
+			"api",
+			"timestamp",
+			"duration",
+			"ttft",
+			"stop_reason",
+			"error_message",
+			"input_tokens",
+			"output_tokens",
+			"cache_read_tokens",
+			"cache_write_tokens",
+			"total_tokens",
+			"premium_requests",
+			"cost_input",
+			"cost_output",
+			"cost_cache_read",
+			"cost_cache_write",
+			"cost_total",
+			"cost_no_cache_input",
+			"cost_unpriced",
+			"agent_type",
+			"service_tier",
+		],
+		identity: ["entry_id", "timestamp"],
+		upsert: `ON CONFLICT(session_file, entry_id) DO UPDATE SET
 			premium_requests = MAX(messages.premium_requests, excluded.premium_requests),
 			cost_input = excluded.cost_input,
 			cost_output = excluded.cost_output,
@@ -905,53 +954,47 @@ export function insertMessageStats(stats: Iterable<MessageStatsInput>): number {
 			cost_total = excluded.cost_total,
 			cost_no_cache_input = excluded.cost_no_cache_input,
 			cost_unpriced = excluded.cost_unpriced,
-			service_tier = excluded.service_tier
-	`);
-
-	let inserted = 0;
-	const insert = db.transaction(() => {
+			service_tier = excluded.service_tier`,
+	});
+	return atomically(db, () => {
 		for (const s of stats) {
 			const { cost, unpriced } = resolveStoredCost(s);
 			const noCacheInputCost = calculateNoCacheInputCost(s.provider, s.model, s.usage, s.timestamp) ?? 0;
-			const result = stmt.run(
-				s.sessionFile,
-				s.entryId,
-				s.folder,
-				s.model,
-				s.provider,
-				s.api,
-				s.timestamp,
-				s.duration,
-				s.ttft,
-				s.stopReason,
-				s.errorMessage,
-				s.usage.input,
-				s.usage.output,
-				s.usage.cacheRead,
-				s.usage.cacheWrite,
-				s.usage.totalTokens,
-				s.usage.premiumRequests ?? 0,
-				cost.input,
-				cost.output,
-				cost.cacheRead,
-				cost.cacheWrite,
-				cost.total,
-				noCacheInputCost,
-				unpriced ? 1 : 0,
-				s.agentType,
-				s.serviceTier ?? null,
-				// `WHERE NOT EXISTS` binds: skip when a different session_file
-				// already holds this (entry_id, timestamp).
-				s.entryId,
-				s.timestamp,
+			writer.add(
 				s.sessionFile,
+				[s.entryId, s.timestamp],
+				[
+					s.sessionFile,
+					s.entryId,
+					s.folder,
+					s.model,
+					s.provider,
+					s.api,
+					s.timestamp,
+					s.duration,
+					s.ttft,
+					s.stopReason,
+					s.errorMessage,
+					s.usage.input,
+					s.usage.output,
+					s.usage.cacheRead,
+					s.usage.cacheWrite,
+					s.usage.totalTokens,
+					s.usage.premiumRequests ?? 0,
+					cost.input,
+					cost.output,
+					cost.cacheRead,
+					cost.cacheWrite,
+					cost.total,
+					noCacheInputCost,
+					unpriced ? 1 : 0,
+					s.agentType,
+					s.serviceTier ?? null,
+				],
 			);
-			if (result.changes > 0) inserted++;
 		}
+		return writer.finish();
 	});
-
-	insert();
-	return inserted;
 }
 
 /**
@@ -1333,57 +1376,62 @@ export function markSessionBackfillsComplete(): void {
 
 /**
  * Insert user-message stats. Idempotent via UNIQUE(session_file, entry_id).
- * The `WHERE NOT EXISTS` clause matches {@link insertMessageStats}: forks
- * copy user entries verbatim into the child JSONL, so the same
- * `(entry_id, timestamp)` must not land twice across different session files.
+ * The fork guard matches {@link insertMessageStats}: forks copy user entries
+ * verbatim into the child JSONL, so the same `(entry_id, timestamp)` must not
+ * land twice across different session files.
  */
 export function insertUserMessageStats(stats: Iterable<UserMessageStats>): number {
 	if (!db) return 0;
-
-	const stmt = db.query(`
-		INSERT OR IGNORE INTO user_messages (
-			session_file, entry_id, folder, timestamp, model, provider,
-			chars, words, yelling, profanity, anguish,
-			negation, repetition, blame, prose, prose_hash
-		)
-		SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
-		WHERE NOT EXISTS (
-			SELECT 1 FROM user_messages
-			WHERE entry_id = ? AND timestamp = ? AND session_file <> ?
-		)
-	`);
-
-	let inserted = 0;
-	const insert = db.transaction(() => {
+	const writer = new ChunkedInsert(db, {
+		verb: "INSERT OR IGNORE",
+		table: "user_messages",
+		columns: [
+			"session_file",
+			"entry_id",
+			"folder",
+			"timestamp",
+			"model",
+			"provider",
+			"chars",
+			"words",
+			"yelling",
+			"profanity",
+			"anguish",
+			"negation",
+			"repetition",
+			"blame",
+			"prose",
+			"prose_hash",
+		],
+		identity: ["entry_id", "timestamp"],
+	});
+	return atomically(db, () => {
 		for (const s of stats) {
-			const result = stmt.run(
-				s.sessionFile,
-				s.entryId,
-				s.folder,
-				s.timestamp,
-				s.model,
-				s.provider,
-				s.chars,
-				s.words,
-				s.yelling,
-				s.profanity,
-				s.anguish,
-				s.negation,
-				s.repetition,
-				s.blame,
-				s.prose,
-				s.proseHash,
-				// `WHERE NOT EXISTS` binds: skip when a different session_file
-				// already holds this (entry_id, timestamp).
-				s.entryId,
-				s.timestamp,
+			writer.add(
 				s.sessionFile,
+				[s.entryId, s.timestamp],
+				[
+					s.sessionFile,
+					s.entryId,
+					s.folder,
+					s.timestamp,
+					s.model,
+					s.provider,
+					s.chars,
+					s.words,
+					s.yelling,
+					s.profanity,
+					s.anguish,
+					s.negation,
+					s.repetition,
+					s.blame,
+					s.prose,
+					s.proseHash,
+				],
 			);
-			if (result.changes > 0) inserted++;
 		}
+		return writer.finish();
 	});
-	insert();
-	return inserted;
 }
 
 /**
@@ -1404,13 +1452,12 @@ export function updateUserMessageLinks(links: Iterable<UserMessageLink>): number
 	`);
 
 	let updated = 0;
-	const apply = db.transaction(() => {
+	atomically(db, () => {
 		for (const link of links) {
 			const result = stmt.run(link.model, link.provider, link.sessionFile, link.entryId);
 			if (result.changes > 0) updated++;
 		}
 	});
-	apply();
 	return updated;
 }
 
@@ -1574,7 +1621,7 @@ export function upsertFrustrationVerdicts(verdicts: readonly FrustrationVerdict[
 
 /**
  * Insert tool-call rows. Idempotent via UNIQUE(session_file, tool_call_id);
- * the `WHERE NOT EXISTS` guard mirrors {@link insertMessageStats}: forked
+ * the fork guard mirrors {@link insertMessageStats}: forked
  * sessions deep-copy assistant entries (same `entry_id`, `timestamp`, and
  * tool-call ids under a new file), so first-write-wins across the lineage
  * keeps aggregates from double counting. Keyed on the assistant entry
@@ -1583,46 +1630,50 @@ export function upsertFrustrationVerdicts(verdicts: readonly FrustrationVerdict[
  */
 export function insertToolCalls(calls: Iterable<ToolCallStats>): number {
 	if (!db) return 0;
-
-	const stmt = db.query(`
-		INSERT OR IGNORE INTO tool_calls (
-			session_file, entry_id, tool_call_id, folder, tool_name,
-			model, provider, timestamp, agent_type, calls_in_turn, args_chars
-		)
-		SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
-		WHERE NOT EXISTS (
-			SELECT 1 FROM tool_calls
-			WHERE entry_id = ? AND timestamp = ? AND tool_call_id = ? AND session_file <> ?
-		)
-	`);
-
-	let inserted = 0;
-	const insert = db.transaction(() => {
+	const writer = new ChunkedInsert(db, {
+		verb: "INSERT OR IGNORE",
+		table: "tool_calls",
+		columns: [
+			"session_file",
+			"entry_id",
+			"tool_call_id",
+			"folder",
+			"tool_name",
+			"model",
+			"provider",
+			"timestamp",
+			"agent_type",
+			"calls_in_turn",
+			"args_chars",
+			"result_chars",
+			"is_error",
+		],
+		identity: ["entry_id", "timestamp", "tool_call_id"],
+	});
+	return atomically(db, () => {
 		for (const c of calls) {
-			const result = stmt.run(
-				c.sessionFile,
-				c.entryId,
-				c.toolCallId,
-				c.folder,
-				c.toolName,
-				c.model,
-				c.provider,
-				c.timestamp,
-				c.agentType,
-				c.callsInTurn,
-				c.argsChars,
-				// `WHERE NOT EXISTS` binds: skip when a different session_file
-				// already holds this (entry_id, timestamp, tool_call_id).
-				c.entryId,
-				c.timestamp,
-				c.toolCallId,
+			writer.add(
 				c.sessionFile,
+				[c.entryId, c.timestamp, c.toolCallId],
+				[
+					c.sessionFile,
+					c.entryId,
+					c.toolCallId,
+					c.folder,
+					c.toolName,
+					c.model,
+					c.provider,
+					c.timestamp,
+					c.agentType,
+					c.callsInTurn,
+					c.argsChars,
+					c.resultChars ?? null,
+					c.isError === undefined ? null : c.isError ? 1 : 0,
+				],
 			);
-			if (result.changes > 0) inserted++;
 		}
+		return writer.finish();
 	});
-	insert();
-	return inserted;
 }
 
 /**
@@ -1642,12 +1693,11 @@ export function updateToolResults(links: Iterable<ToolResultLink>): number {
 	`);
 
 	let updated = 0;
-	const apply = db.transaction(() => {
+	atomically(db, () => {
 		for (const link of links) {
 			const result = stmt.run(link.resultChars, link.isError ? 1 : 0, link.sessionFile, link.toolCallId);
 			updated += result.changes;
 		}
 	});
-	apply();
 	return updated;
 }

package/src/parser.ts

@@ -553,6 +553,8 @@ export async function parseSessionFile(
 	const userLinks: UserMessageLink[] = [];
 	const toolCalls: ToolCallStats[] = [];
 	const toolResults: ToolResultLink[] = [];
+	// First call per id: the row `INSERT OR IGNORE` keeps, so it can be written with its result.
+	const callsById = new Map<string, ToolCallStats>();
 
 	// Reduce each entry immediately so full replays do not retain tool-output/message bodies.
 	const visit = (entry: SessionEntry): void => {
@@ -567,7 +569,13 @@ export async function parseSessionFile(
 		}
 		if (isToolResultMessage(entry)) {
 			const link = extractToolResultLink(sessionPath, entry);
-			if (link) toolResults.push(link);
+			if (!link) return;
+			toolResults.push(link);
+			const call = callsById.get(link.toolCallId);
+			if (call && call.resultChars === undefined) {
+				call.resultChars = link.resultChars;
+				call.isError = link.isError;
+			}
 			return;
 		}
 		if (isModelUsage(entry)) {
@@ -578,7 +586,10 @@ export async function parseSessionFile(
 		if (isAssistantMessage(entry)) {
 			const msgStats = extractStats(sessionPath, folder, entry, currentServiceTier, agentType);
 			if (msgStats) stats.push(msgStats);
-			toolCalls.push(...extractToolCalls(sessionPath, folder, entry, agentType));
+			for (const call of extractToolCalls(sessionPath, folder, entry, agentType)) {
+				toolCalls.push(call);
+				if (!callsById.has(call.toolCallId)) callsById.set(call.toolCallId, call);
+			}
 			// Persist links even when the user entry was ingested in an earlier tail read.
 			const parentId = entry.parentId;
 			const msg = entry.message;

package/src/port-conflict.ts

@@ -1,10 +1,15 @@
 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 { $which, logger } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 
-const STATS_PROBE_TIMEOUT_MS = 500;
+/**
+ * Upper bound on the identity probe. A live dashboard ingests on its main thread
+ * (serially on macOS), which stalls its responses for over a second on large
+ * histories; giving up sooner mistakes a busy dashboard for a hung listener.
+ */
+const STATS_PROBE_TIMEOUT_MS = 3_000;
 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 };
@@ -26,15 +31,29 @@ export const STATS_DASHBOARD_SECURITY_VERSION = "3";
 /** IPv4 loopback address shared by the dashboard server and reuse probe. */
 export const STATS_DASHBOARD_HOSTNAME = "127.0.0.1";
 
-type StatsDashboardProbe = "reusable" | "replaceable" | "occupied" | "unreachable";
+/**
+ * What answers on the dashboard port:
+ * - `reusable`: a current dashboard bound to the requested host.
+ * - `replaceable`: an older dashboard this version may upgrade.
+ * - `occupied`: any other HTTP answer.
+ * - `unresponsive`: accepted the connection but did not answer in time (busy or hung).
+ * - `unreachable`: the connection failed, typically because nothing listens there.
+ */
+type StatsDashboardProbe = "reusable" | "replaceable" | "occupied" | "unresponsive" | "unreachable";
+
+/**
+ * How {@link startServer} proceeds with the requested port: bind it, reuse the
+ * dashboard already serving it, or fall back to an ephemeral port because the
+ * holder is neither reusable nor safe to stop.
+ */
+export type StatsPortClaim = "bind" | "reuse" | "fallback";
 
 async function probeStatsDashboard(port: number, hostname: string): Promise<StatsDashboardProbe> {
 	const probeHostname = hostname === "0.0.0.0" ? STATS_DASHBOARD_HOSTNAME : hostname === "::" ? "::1" : hostname;
 	const urlHostname = probeHostname.includes(":") ? `[${probeHostname}]` : probeHostname;
+	const signal = AbortSignal.timeout(STATS_PROBE_TIMEOUT_MS);
 	try {
-		const response = await fetch(`http://${urlHostname}:${port}/api/stats/models`, {
-			signal: AbortSignal.timeout(STATS_PROBE_TIMEOUT_MS),
-		});
+		const response = await fetch(`http://${urlHostname}:${port}/api/stats/models`, { signal });
 		const dashboardVersionHeader = response.headers.get(STATS_DASHBOARD_HEADER);
 		const dashboardVersion = dashboardVersionHeader === null ? Number.NaN : Number(dashboardVersionHeader);
 		// Never replace a newer dashboard: an older CLI must not downgrade it.
@@ -52,7 +71,7 @@ async function probeStatsDashboard(port: number, hostname: string): Promise<Stat
 		if (reusable) return "reusable";
 		return replaceable ? "replaceable" : "occupied";
 	} catch {
-		return "unreachable";
+		return signal.aborted ? "unresponsive" : "unreachable";
 	}
 }
 
@@ -227,13 +246,16 @@ async function terminatePortHolder(holder: PortHolder): Promise<void> {
 	await Bun.sleep(PROCESS_EXIT_POLL_MS);
 }
 
-async function reclaimStatsPort(port: number, hasDashboardIdentity = false): Promise<"retry"> {
+/**
+ * Stop the stats dashboard answering `probe` on `port` so it can be rebound.
+ * Holders that cannot be positively identified as an omp stats dashboard, or
+ * that refuse to stop, are left running and yield `"fallback"`.
+ */
+async function reclaimStatsPort(port: number, probe: "replaceable" | "occupied"): Promise<StatsPortClaim> {
 	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}).`);
+	if (!holder || holder.pid === process.pid) {
+		logger.debug("Stats dashboard port holder not reclaimable", { port, holder });
+		return "fallback";
 	}
 
 	const normalizedImage = holder.image
@@ -247,33 +269,48 @@ async function reclaimStatsPort(port: number, hasDashboardIdentity = false): Pro
 		/\/packages\/stats\/src\/index\.ts(?:["'\s]|$)/.test(normalizedCommand) ||
 		(normalizedImage === "omp" && /(?:^|\s)stats(?:\s|$)/.test(normalizedCommand)) ||
 		/(?:^|\/)omp(?:\.exe)?["'\s]+stats(?:["'\s]|$)/.test(normalizedCommand);
+	const hasDashboardIdentity = probe === "replaceable";
 	if (!STATS_RUNTIME_IMAGES[normalizedImage] || (!hasStatsIdentity && !hasDashboardIdentity)) {
-		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.`,
-		);
+		logger.debug("Stats dashboard port held by an unidentified process", { port, holder });
+		return "fallback";
 	}
 
-	await terminatePortHolder(holder);
-	return "retry";
+	try {
+		await terminatePortHolder(holder);
+	} catch (error) {
+		logger.warn("Failed to stop stale stats dashboard", { port, pid: holder.pid, error: String(error) });
+		return "fallback";
+	}
+	return "bind";
+}
+
+async function claimStatsPort(port: number, hostname: string, ifUnreachable: StatsPortClaim): Promise<StatsPortClaim> {
+	const probe = await probeStatsDashboard(port, hostname);
+	switch (probe) {
+		case "reusable":
+			return "reuse";
+		case "replaceable":
+		case "occupied":
+			return reclaimStatsPort(port, probe);
+		case "unresponsive":
+			// Busy or hung: a dashboard stalled mid-ingest must never be stopped.
+			return "fallback";
+		case "unreachable":
+			return ifUnreachable;
+	}
 }
 
 /**
- * Reuse a secure dashboard or reclaim an insecure HTTP dashboard before binding.
+ * Reuse a current dashboard, or upgrade an older one, before binding.
  * The preflight is needed on platforms that permit wildcard and loopback-specific
  * listeners to coexist on one port.
  */
-export async function prepareStatsPort(port: number, hostname = STATS_DASHBOARD_HOSTNAME): Promise<"retry" | "reuse"> {
-	if (port === 0) return "retry";
-	const probe = await probeStatsDashboard(port, hostname);
-	if (probe === "reusable") return "reuse";
-	if (probe === "replaceable") return reclaimStatsPort(port, true);
-	if (probe === "occupied") return reclaimStatsPort(port);
-	return "retry";
+export async function prepareStatsPort(port: number, hostname = STATS_DASHBOARD_HOSTNAME): Promise<StatsPortClaim> {
+	if (port === 0) return "bind";
+	return claimStatsPort(port, hostname, "bind");
 }
 
 /** Reuse or reclaim a listener found after the server bind reports EADDRINUSE. */
-export async function recoverStatsPort(port: number, hostname = STATS_DASHBOARD_HOSTNAME): Promise<"retry" | "reuse"> {
-	const probe = await probeStatsDashboard(port, hostname);
-	if (probe === "reusable") return "reuse";
-	return reclaimStatsPort(port, probe === "replaceable");
+export async function recoverStatsPort(port: number, hostname = STATS_DASHBOARD_HOSTNAME): Promise<StatsPortClaim> {
+	return claimStatsPort(port, hostname, "fallback");
 }