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

package/src/server.ts

@@ -474,19 +474,18 @@ function liveEventStream(headers: Record<string, string>, signal: AbortSignal):
 	});
 }
 
-/**
- * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
- */
+/** A dashboard this process started or found; `port` is where it listens, which may differ from the one requested. */
 export interface StatsServerHandle {
 	hostname: string;
 	port: number;
 	stop: () => void;
 }
 
-// Dashboards this process already bound, keyed by requested `hostname:port`.
-// A second in-process start (e.g. `/trace` twice in one session) must return
-// the live handle: probing our own port can time out under load and would
-// then dead-end in the reclaim path's self-PID guard.
+// Dashboards this process already bound, keyed by requested and bound
+// `hostname:port`. A second in-process start (e.g. `/trace` twice in one
+// session, or a caller passing back a fallback port) must return the live
+// handle: probing our own port can time out under load and would then start
+// yet another dashboard on a fallback port.
 const activeServers = new Map<string, StatsServerHandle>();
 /** Dashboards bound by this process (any port); background ingest stops when the last one does. */
 let liveServers = 0;
@@ -496,30 +495,34 @@ export interface StartServerOptions {
 	judge?: StatsJudgeProvider;
 }
 
+/**
+ * Start the dashboard on `port`, or reuse the current dashboard already serving it.
+ * An older dashboard there is stopped and replaced; any other holder (a foreign
+ * program, or a dashboard too busy to answer the identity probe) is left running
+ * and the dashboard binds an ephemeral port instead.
+ */
 export async function startServer(
 	port = 3847,
 	hostname = STATS_DASHBOARD_HOSTNAME,
 	options: StartServerOptions = {},
 ): Promise<StatsServerHandle> {
 	if (options.judge) setStatsJudgeProvider(options.judge);
-	const activeKey = `${hostname}:${port}`;
+	const requestedKey = `${hostname}:${port}`;
 	if (port !== 0) {
-		const active = activeServers.get(activeKey);
+		const active = activeServers.get(requestedKey);
 		if (active) return active;
 	}
 	await ensureClientBuild();
-	const preparation = await prepareStatsPort(port, hostname);
-	if (preparation === "reuse") {
-		return { hostname, port, stop: () => {} };
-	}
 	const register = (server: Server<undefined>): StatsServerHandle => {
 		liveServers++;
 		let stopped = false;
+		const boundPort = server.port ?? port;
+		const keys = port === 0 ? [`${hostname}:${boundPort}`] : [requestedKey, `${hostname}:${boundPort}`];
 		const handle: StatsServerHandle = {
 			hostname,
-			port: server.port ?? port,
+			port: boundPort,
 			stop: () => {
-				activeServers.delete(activeKey);
+				for (const key of keys) activeServers.delete(key);
 				server.stop(true);
 				if (stopped) return;
 				stopped = true;
@@ -527,26 +530,31 @@ export async function startServer(
 				if (--liveServers === 0) statsLive().stop();
 			},
 		};
-		if (port !== 0) activeServers.set(activeKey, handle);
+		for (const key of keys) activeServers.set(key, handle);
 		return handle;
 	};
 
+	let claim = await prepareStatsPort(port, hostname);
+	if (claim === "bind") {
+		const server = bindDashboardServer(port, hostname);
+		if (server) return register(server);
+		claim = await recoverStatsPort(port, hostname);
+	}
+	if (claim === "reuse") return { hostname, port, stop: () => {} };
+	if (claim === "bind") {
+		const server = bindDashboardServer(port, hostname);
+		if (server) return register(server);
+	}
+	logger.warn("Stats dashboard port is held by another process; serving on an ephemeral port", { hostname, port });
+	return register(createDashboardServer(0, hostname));
+}
+
+/** {@link createDashboardServer}, or null when the port is already in use. */
+function bindDashboardServer(port: number, hostname: string): Server<undefined> | null {
 	try {
-		return register(createDashboardServer(port, hostname));
+		return createDashboardServer(port, hostname);
 	} catch (error) {
-		if (!(error instanceof Error && "code" in error && error.code === "EADDRINUSE")) throw error;
-
-		const recovery = await recoverStatsPort(port, hostname);
-		if (recovery === "reuse") {
-			return { hostname, port, stop: () => {} };
-		}
-
-		try {
-			return register(createDashboardServer(port, hostname));
-		} catch (retryError) {
-			throw new Error(`Failed to start stats dashboard on ${hostname}:${port} after reclaiming it.`, {
-				cause: retryError,
-			});
-		}
+		if (error instanceof Error && "code" in error && error.code === "EADDRINUSE") return null;
+		throw error;
 	}
 }

package/src/shared-types.ts

@@ -604,7 +604,7 @@ export interface TraceTrack {
 	agent: string | null;
 	/** session_init.resolvedModel ?? first assistant model. */
 	model: string | null;
-	/** Absolute transcript path (for entry fetch). */
+	/** Absolute transcript path for live entry fetch, or the embedded snapshot key. */
 	file: string;
 	/** Sorted by start. */
 	spans: TraceSpan[];
@@ -648,12 +648,13 @@ export interface SessionTrace {
 	cwd: string | null;
 	startedAt: number;
 	endedAt: number;
-	/** Root transcript mtime; doubles as the ETag. */
+	/** Root transcript mtime, or recorded root activity/header time for offline snapshots. */
 	mtimeMs: number;
 	/**
 	 * Conditional-request fingerprint `"<rootMs>:<childHighMs>"` (see
 	 * traceFingerprintForEtag): the server ETag is built from this, so a
 	 * subagent-only append changes the ETag even when the root is untouched.
+	 * Offline snapshots use "snapshot" and do not support HTTP revalidation.
 	 */
 	etag: string;
 	/** DFS order, main first. */

package/src/trace.ts

@@ -35,7 +35,7 @@ export class TracePathError extends Error {}
  * span assembly changes so browsers don't revalidate stale cached bodies
  * against an unchanged transcript mtime.
  */
-export const TRACE_ETAG_VERSION = 3;
+export const TRACE_ETAG_VERSION = 4;
 
 const MAX_TRACK_DEPTH = 6;
 const LABEL_MAX = 80;
@@ -230,7 +230,7 @@ function unionLength(intervals: Array<[number, number]>): number {
 // Single-transcript scan
 
 /** Keep only the active branch: the parentId chain walked back from the last entry. */
-function activeChain(views: EntryView[]): EntryView[] {
+function activeChain(views: readonly EntryView[]): EntryView[] {
 	const byId = new Map<string, EntryView>();
 	let last: EntryView | undefined;
 	for (const entry of views) {
@@ -278,13 +278,14 @@ function argsPreview(args: unknown): string | undefined {
  * markers, and the cross-track facts (task results, request counts).
  */
 function scanTranscript(
-	entries: SessionEntry[],
+	entries: readonly SessionEntry[],
 	trackId: string,
 	parentTrackId: string | null,
 	file: string,
+	header?: TraceSnapshotHeader | null,
 ): TrackScan {
 	// Boundary cast: persisted JSONL entries are re-validated field-by-field below.
-	const views = entries as EntryView[];
+	const views = entries as readonly EntryView[];
 	const chain = activeChain(views);
 	const spans: TraceSpan[] = [];
 	const markers: TraceMarker[] = [];
@@ -297,9 +298,9 @@ function scanTranscript(
 	const taskResults: TaskResultFact[] = [];
 
 	let sessionExit: { recordedAt: number; pendingIds: Set<string> } | undefined;
-	let cwd: string | null = null;
-	let headerTitle: string | null = null;
-	let headerTs: number | undefined;
+	let cwd = typeof header?.cwd === "string" ? header.cwd : null;
+	let headerTitle = typeof header?.title === "string" ? header.title : null;
+	let headerTs = toMs(header?.timestamp);
 	let slotTitle: string | null = null;
 	let initAgent: string | null = null;
 	let initModel: string | null = null;
@@ -689,7 +690,7 @@ async function buildTrackTree(
 			const childTrackId = trackId === "main" ? stem : `${trackId}/${stem}`;
 			const childScan = await buildTrackTree(childFile, childTrackId, trackId, depth + 1, visited, out, scans);
 			if (!childScan) continue;
-			const isAdvisor = name === "__advisor.jsonl" || (name.startsWith("__advisor.") && name.endsWith(".jsonl"));
+			const isAdvisor = stem === "__advisor" || stem.startsWith("__advisor.");
 			childScan.track.label = isAdvisor
 				? "Advisor"
 				: headText(`${childScan.track.agent ?? "agent"} ${stem}`, LABEL_MAX);
@@ -697,6 +698,13 @@ async function buildTrackTree(
 		}
 	}
 
+	linkChildTracks(scan, childrenById);
+	return scan;
+}
+
+/** Place child activity and structured task-result spans on their parent track. */
+function linkChildTracks(scan: TrackScan, childrenById: ReadonlyMap<string, TrackScan>): void {
+	const trackId = scan.track.id;
 	// Subagent spans on this track, one per task SingleResult.
 	const linkedChildren = new Set<string>();
 	for (const result of scan.taskResults) {
@@ -746,8 +754,6 @@ async function buildTrackTree(
 		scan.track.spans.push(span);
 	}
 	scan.track.spans.sort((a, b) => a.start - b.start || a.end - b.end);
-
-	return scan;
 }
 
 // ---------------------------------------------------------------------------
@@ -863,6 +869,106 @@ export async function buildSessionTrace(fileParam: string, fingerprint?: TraceFi
 	if (!rootScan) {
 		throw Object.assign(new Error(`ENOENT: session not found: ${resolved}`), { code: "ENOENT" });
 	}
+	// Re-collect the fingerprint AFTER the parse: a child append landing
+	// between the pre-build check and now would otherwise be baked into
+	// neither the trace nor the key.
+	const childFingerprint = await childTranscriptsFingerprint(resolved);
+	// Root rewritten mid-build: same no-cache rule as the child race below.
+	const rootChanged = (await fs.stat(resolved).catch(() => null))?.mtimeMs !== rootMtimeMs;
+	const raced = childFingerprint !== preChildFingerprint;
+	// Raced builds keep the PRE-build fingerprint as their ETag: the parsed
+	// bytes predate the racy write, so claiming the post-write state would
+	// 304 stale forever when that write was the child's last. The pre-build
+	// key guarantees the next conditional poll misses (filesystem moved on)
+	// and rebuilds — at most one stale response per race, never an
+	// indefinitely cached one. Unraced builds use the post-build key, which
+	// equals the pre-build key by construction.
+	const etagFingerprint = raced || rootChanged ? preChildFingerprint : childFingerprint;
+	const trace = assembleSessionTrace(rootScan, tracks, scans, rootMtimeMs, `${rootMtimeMs}:${etagFingerprint}`);
+	if (!raced && !rootChanged) {
+		traceMemo = {
+			file: resolved,
+			entry: { mtimeMs: rootMtimeMs, childFingerprint, trace },
+		};
+	}
+	return trace;
+}
+
+/** Header metadata used by snapshot traces, including journals without a schema version. */
+export interface TraceSnapshotHeader {
+	timestamp?: string;
+	cwd?: string;
+	title?: string;
+}
+
+/** The journal data for one embedded transcript; its header may be stored separately. */
+export interface SessionTraceSnapshot {
+	header?: TraceSnapshotHeader | null;
+	entries: readonly SessionEntry[];
+}
+
+/** A collected child transcript, keyed by its slash-joined path from the root. */
+export interface SubSessionTraceSnapshot extends SessionTraceSnapshot {
+	parent: string | null;
+}
+
+/**
+ * Assemble an offline trace using the same timing joins and rollups as the live
+ * filesystem builder. Only supplied snapshots participate: no filesystem, DB,
+ * network, or wall-clock reads. Track files are snapshot keys, never disk paths.
+ *
+ * Missing parent transcripts attach their readable descendants to main. Unlike
+ * filesystem discovery, already-collected snapshots need no depth limit.
+ * `mtimeMs` is the root's last activity (or header time, then 0); the constant
+ * `etag` identifies a snapshot, not a conditional HTTP response.
+ */
+export function buildSessionTraceFromSnapshots(
+	root: SessionTraceSnapshot,
+	subSessions?: Readonly<Record<string, SubSessionTraceSnapshot>>,
+): SessionTrace {
+	const children = new Map<string | null, Array<[string, SubSessionTraceSnapshot]>>();
+	if (subSessions) {
+		for (const key of Object.keys(subSessions).sort()) {
+			const snapshot = subSessions[key];
+			const parent =
+				snapshot.parent !== null && Object.hasOwn(subSessions, snapshot.parent) ? snapshot.parent : null;
+			const siblings = children.get(parent);
+			if (siblings) siblings.push([key, snapshot]);
+			else children.set(parent, [[key, snapshot]]);
+		}
+	}
+
+	const tracks: TraceTrack[] = [];
+	const scans: TrackScan[] = [];
+	const visit = (snapshot: SessionTraceSnapshot, key: string, parentId: string | null): TrackScan => {
+		const scan = scanTranscript(snapshot.entries, key, parentId, key, snapshot.header);
+		tracks.push(scan.track);
+		scans.push(scan);
+		const childrenById = new Map<string, TrackScan>();
+		for (const [childKey, childSnapshot] of children.get(parentId === null ? null : key) ?? []) {
+			const child = visit(childSnapshot, childKey, key);
+			const stem = childKey.slice(childKey.lastIndexOf("/") + 1);
+			child.track.label =
+				stem === "__advisor" || stem.startsWith("__advisor.")
+					? "Advisor"
+					: headText(`${child.track.agent ?? "agent"} ${stem}`, LABEL_MAX);
+			childrenById.set(stem, child);
+		}
+		linkChildTracks(scan, childrenById);
+		return scan;
+	};
+	const rootScan = visit(root, "main", null);
+	return assembleSessionTrace(rootScan, tracks, scans, rootScan.lastActivity ?? rootScan.headerTs ?? 0, "snapshot");
+}
+
+/** Shared aggregation after either filesystem discovery or snapshot traversal. */
+function assembleSessionTrace(
+	rootScan: TrackScan,
+	tracks: TraceTrack[],
+	scans: TrackScan[],
+	rootMtimeMs: number,
+	etag: string,
+): SessionTrace {
 	rootScan.track.label = "Main";
 
 	let startedAt: number | undefined;
@@ -935,39 +1041,17 @@ export async function buildSessionTrace(fileParam: string, fingerprint?: TraceFi
 		toolStats: [...toolStats.values()].sort((a, b) => b.totalMs - a.totalMs),
 	};
 
-	// Re-collect the fingerprint AFTER the parse: a child append landing
-	// between the pre-build check and now would otherwise be baked into
-	// neither the trace nor the key.
-	const childFingerprint = await childTranscriptsFingerprint(resolved);
-	// Root rewritten mid-build: same no-cache rule as the child race below.
-	const rootChanged = (await fs.stat(resolved).catch(() => null))?.mtimeMs !== rootMtimeMs;
-	const raced = childFingerprint !== preChildFingerprint;
-	// Raced builds keep the PRE-build fingerprint as their ETag: the parsed
-	// bytes predate the racy write, so claiming the post-write state would
-	// 304 stale forever when that write was the child's last. The pre-build
-	// key guarantees the next conditional poll misses (filesystem moved on)
-	// and rebuilds — at most one stale response per race, never an
-	// indefinitely cached one. Unraced builds use the post-build key, which
-	// equals the pre-build key by construction.
-	const etagFingerprint = raced || rootChanged ? preChildFingerprint : childFingerprint;
-	const trace: SessionTrace = {
-		file: resolved,
+	return {
+		file: rootScan.track.file,
 		title: rootScan.title,
 		cwd: rootScan.cwd,
 		startedAt: start,
 		endedAt: end,
 		mtimeMs: rootMtimeMs,
-		etag: `${rootMtimeMs}:${etagFingerprint}`,
+		etag,
 		tracks,
 		summary,
 	};
-	if (!raced && !rootChanged) {
-		traceMemo = {
-			file: resolved,
-			entry: { mtimeMs: rootMtimeMs, childFingerprint, trace },
-		};
-	}
-	return trace;
 }
 
 /** Fetch one full journal entry by id from a transcript, for the span drawer. */

package/src/types.ts

@@ -231,12 +231,17 @@ export interface ToolCallStats {
 	callsInTurn: number;
 	/** Serialized argument characters */
 	argsChars: number;
+	/** Result text characters, when the same parse also read the call's `toolResult` */
+	resultChars?: number;
+	/** Result error flag, set together with `resultChars` */
+	isError?: boolean;
 }
 
 /**
  * Result linkage emitted when the parser sees a `toolResult` message entry.
  * Applied as an UPDATE on the persisted tool-call row — results can land in a
- * later incremental sync pass than the call that produced them.
+ * later incremental sync pass than the call that produced them (calls parsed
+ * in the same pass already carry the result, so their UPDATE is a no-op).
  */
 export interface ToolResultLink {
 	sessionFile: string;