@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/mux/yazi/theme.ts

@@ -0,0 +1,30 @@
+import { tokenHex } from "../../../core/theme-token-hex.js";
+
+/** Render the deliberately small Clio overlay on Yazi's pinned preset theme. */
+export function renderYaziTheme(): string {
+	return `# Generated by Clio Coder. Changes are replaced when the managed profile regenerates.
+
+[mgr]
+cwd = { fg = "${tokenHex("accent")}" }
+find_keyword = { fg = "${tokenHex("warning")}" }
+marker_selected = { fg = "${tokenHex("success")}", bg = "${tokenHex("success")}" }
+marker_copied = { fg = "${tokenHex("accent")}", bg = "${tokenHex("accent")}" }
+marker_cut = { fg = "${tokenHex("error")}", bg = "${tokenHex("error")}" }
+border_style = { fg = "${tokenHex("frame")}" }
+
+[mode]
+normal_main = { bg = "${tokenHex("accent")}" }
+normal_alt = { fg = "${tokenHex("accent")}" }
+select_main = { bg = "${tokenHex("action")}" }
+select_alt = { fg = "${tokenHex("action")}" }
+unset_main = { bg = "${tokenHex("error")}" }
+unset_alt = { fg = "${tokenHex("error")}" }
+
+[tabs]
+active = { bg = "${tokenHex("accent")}" }
+inactive = { fg = "${tokenHex("accent")}" }
+
+[status]
+perm_sep = { fg = "${tokenHex("dim")}" }
+`;
+}

package/src/domains/observability/background-memory-usage.ts

@@ -0,0 +1,140 @@
+/**
+ * Accounting for one proactive-memory step.
+ *
+ * A background memory step is a priced model call that never enters the
+ * session: it appends nothing to the session JSONL, exactly as a `/btw` side
+ * question does not. Until this existed the spend was recorded nowhere at all.
+ * The operator's own telemetry ledger held 60 model steps, 137,205 tokens, and
+ * 1,666 seconds of model time across 14 days while `/cost` showed no row for
+ * any of it and `clio-coder usage report` could not see it either (#229).
+ *
+ * The two writes are the same pair the side-question path makes: the
+ * in-process cost tracker under the `background-memory` label, which is what
+ * `/cost` folds, and one durable row in the out-of-turn usage store, which is
+ * what an archive reader folds after the process is gone.
+ */
+
+import { uncachedPrefillTokens } from "../../core/cache-telemetry.js";
+import type { CostProvenance } from "../providers/index.js";
+import type { CostEntryLabel, UsageBreakdown } from "./cost.js";
+import { appendOutOfTurnUsageRow, type OutOfTurnUsageRow } from "./out-of-turn-usage.js";
+
+/** Provider-reported spend for one memory step, as the calling client observed it. */
+export interface BackgroundMemoryStepUsage {
+	targetId: string;
+	attributedModelId: string;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoning: number;
+	totalTokens: number;
+	costUsd: number;
+	costProvenance: CostProvenance;
+	durationMs: number;
+	backend: {
+		promptTokens: number;
+		cachedTokens: number | null;
+		promptMs: number;
+		source: string;
+	} | null;
+}
+
+/** The subset of the observability contract this accounting needs. */
+export interface BackgroundMemoryUsageSink {
+	recordTokens(
+		providerId: string,
+		attributedModelId: string,
+		tokens: number,
+		costUsd?: number,
+		breakdown?: Partial<UsageBreakdown>,
+		costProvenance?: CostProvenance,
+		modelIdFacts?: unknown,
+		label?: CostEntryLabel,
+	): void;
+}
+
+export interface RecordBackgroundMemoryStepInput {
+	usage: BackgroundMemoryStepUsage;
+	stateDir: string;
+	sessionId: string | null;
+	/** The cwd hash the session ledger is filed under, so `usage report --repo` selects it. */
+	repoIdentity: string | null;
+	observability?: BackgroundMemoryUsageSink | undefined;
+	now?: Date;
+	/** Test seam; production appends to the out-of-turn store under the state dir. */
+	appendRow?: (stateDir: string, row: OutOfTurnUsageRow) => void;
+}
+
+/** Build the durable row for one memory step without writing it. */
+export function backgroundMemoryUsageRow(
+	usage: BackgroundMemoryStepUsage,
+	options: { sessionId: string | null; repoIdentity: string | null; now?: Date },
+): OutOfTurnUsageRow {
+	return {
+		label: "background-memory",
+		sessionId: options.sessionId,
+		repoIdentity: options.repoIdentity,
+		timestamp: (options.now ?? new Date()).toISOString(),
+		target: usage.targetId,
+		attributedModelId: usage.attributedModelId,
+		usage: {
+			input: usage.input,
+			output: usage.output,
+			cacheRead: usage.cacheRead,
+			cacheWrite: usage.cacheWrite,
+			reasoning: usage.reasoning,
+			totalTokens: usage.totalTokens,
+			costUsd: usage.costUsd,
+			costProvenance: usage.costProvenance,
+		},
+		timing: { durationMs: usage.durationMs },
+		...(usage.backend === null
+			? {}
+			: {
+					promptCache: {
+						promptTokens: usage.backend.promptTokens,
+						cachedTokens: usage.backend.cachedTokens,
+						uncachedPrefillTokens: uncachedPrefillTokens({
+							promptTokens: usage.backend.promptTokens,
+							cachedTokens: usage.backend.cachedTokens,
+							predictedTokens: 0,
+							promptMs: usage.backend.promptMs,
+							predictedMs: 0,
+							source: "llamacpp-timings",
+						}),
+						promptMs: usage.backend.promptMs,
+						source: usage.backend.source,
+					},
+				}),
+	};
+}
+
+/** Record one memory step in the session's cost totals and in the durable store. */
+export function recordBackgroundMemoryStep(input: RecordBackgroundMemoryStepInput): OutOfTurnUsageRow {
+	input.observability?.recordTokens(
+		input.usage.targetId,
+		input.usage.attributedModelId,
+		input.usage.totalTokens,
+		input.usage.costUsd,
+		{
+			input: input.usage.input,
+			output: input.usage.output,
+			cacheRead: input.usage.cacheRead,
+			cacheWrite: input.usage.cacheWrite,
+			reasoningTokens: input.usage.reasoning,
+			totalTokens: input.usage.totalTokens,
+			apiCalls: 1,
+		},
+		input.usage.costProvenance,
+		undefined,
+		"background-memory",
+	);
+	const row = backgroundMemoryUsageRow(input.usage, {
+		sessionId: input.sessionId,
+		repoIdentity: input.repoIdentity,
+		...(input.now === undefined ? {} : { now: input.now }),
+	});
+	(input.appendRow ?? appendOutOfTurnUsageRow)(input.stateDir, row);
+	return row;
+}

package/src/domains/observability/cost.ts

@@ -101,6 +101,27 @@ export function costAggregateForAmount(usd: number, provenance: CostProvenance |
 	return aggregateCostAmounts([{ usd, provenance: normalizeCostProvenance(provenance) }]);
 }
 
+/**
+ * What a fixed-width surface renders for an already-folded aggregate: the cost
+ * claim when one exists, {@link COST_NOT_MEASURED} when none does. Named here
+ * because the fallback is part of the derivation, not a caller's choice, and a
+ * surface that spells the `?? COST_NOT_MEASURED` out by hand is one edit away
+ * from spelling `$0.00` instead.
+ */
+export function renderCostAggregate(cost: CostAggregate | null | undefined): string {
+	return formatCostAggregate(cost) ?? COST_NOT_MEASURED;
+}
+
+/**
+ * The same render for a single sealed amount, which is the shape a receipt or a
+ * ledger row hands over. A caller that reaches for `usd.toFixed(4)` here drops
+ * the provenance on the floor and turns unpriced work into a measured `$0.0000`,
+ * which is a claim nobody made.
+ */
+export function renderCostAmount(usd: number, provenance: CostProvenance | undefined): string {
+	return renderCostAggregate(costAggregateForAmount(usd, provenance));
+}
+
 export interface UsageBreakdown {
 	input: number;
 	output: number;
@@ -116,7 +137,7 @@ export interface UsageBreakdown {
  * the usage surfaces separate these out so an operator can see that money was
  * spent beside the session rather than inside it.
  */
-export type CostEntryLabel = "side-question" | "handoff";
+export type CostEntryLabel = "side-question" | "handoff" | "prewarm" | "background-memory";
 
 export interface CostEntry {
 	providerId: string;

package/src/domains/observability/index.ts

@@ -16,6 +16,13 @@ export function createObservabilityDomainModule(options: ObservabilityBundleOpti
 
 export type { AccountabilitySummary } from "./accountability.js";
 export { readAccountabilitySummary, summarizeEvidenceIndex } from "./accountability.js";
+export {
+	type BackgroundMemoryStepUsage,
+	type BackgroundMemoryUsageSink,
+	backgroundMemoryUsageRow,
+	type RecordBackgroundMemoryStepInput,
+	recordBackgroundMemoryStep,
+} from "./background-memory-usage.js";
 export type {
 	ObservabilityContract,
 	ObservabilityNotice,
@@ -35,6 +42,8 @@ export {
 	costWasMeasured,
 	emptyCostAggregate,
 	formatCostAggregate,
+	renderCostAggregate,
+	renderCostAmount,
 	type UsageBreakdown,
 } from "./cost.js";
 export type { EvidenceIndexRow } from "./evidence-index.js";

package/src/domains/observability/out-of-turn-usage.ts

@@ -1,6 +1,7 @@
 /**
  * Durable record of the model calls that were billed beside a session rather
- * than inside it: `/btw` side questions and `/handoff` extraction rounds.
+ * than inside it: `/btw` side questions, `/handoff` extraction rounds, and the
+ * session pre-warm.
  *
  * These rounds deliberately append nothing to the session JSONL. A fleet run
  * briefs its workers from the transcript, so a question the operator asked to
@@ -50,6 +51,27 @@ export const MAX_OUT_OF_TURN_USAGE_ROWS = 1000;
  */
 const BOUND_CHECK_INTERVAL = 64;
 
+/** Wall-clock facts about one out-of-turn call. */
+export interface OutOfTurnTiming {
+	/** Duration of the model call itself, as the caller measured it. */
+	durationMs: number;
+}
+
+/**
+ * Backend prefill facts for one out-of-turn call, in the shape brief #247
+ * established for assistant entries. A background memory step re-sends a whole
+ * trajectory to a server that has just been serving the chat prefix, so whether
+ * that prefill was cached is the difference between a cheap step and a step
+ * that re-prefills thousands of tokens on the operator's own machine.
+ */
+export interface OutOfTurnPromptCache {
+	promptTokens: number;
+	cachedTokens: number | null;
+	uncachedPrefillTokens: number | null;
+	promptMs: number;
+	source: string;
+}
+
 /** Provider-reported usage for one out-of-turn call. */
 export interface OutOfTurnUsage {
 	input: number;
@@ -75,6 +97,10 @@ export interface OutOfTurnUsageRow {
 	target: string;
 	attributedModelId: string;
 	usage: OutOfTurnUsage;
+	/** Present when the caller measured the call. */
+	timing?: OutOfTurnTiming;
+	/** Present when the serving backend reported prefill facts. */
+	promptCache?: OutOfTurnPromptCache;
 }
 
 export interface OutOfTurnUsageReadResult {
@@ -179,10 +205,13 @@ export function readOutOfTurnUsageRows(stateDir: string): OutOfTurnUsageReadResu
 function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 	if (!isRecord(value)) return null;
 	const label = value.label;
-	if (label !== "side-question" && label !== "handoff") return null;
+	if (label !== "side-question" && label !== "handoff" && label !== "prewarm" && label !== "background-memory")
+		return null;
 	if (typeof value.timestamp !== "string" || value.timestamp.length === 0) return null;
 	if (!isRecord(value.usage)) return null;
 	const usage = value.usage;
+	const timing = asTiming(value.timing);
+	const promptCache = asPromptCache(value.promptCache);
 	return {
 		label,
 		sessionId: typeof value.sessionId === "string" ? value.sessionId : null,
@@ -203,6 +232,26 @@ function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 			costUsd: numberOr0(usage.costUsd),
 			costProvenance: asCostProvenance(usage.costProvenance),
 		},
+		...(timing === null ? {} : { timing }),
+		...(promptCache === null ? {} : { promptCache }),
+	};
+}
+
+function asTiming(value: unknown): OutOfTurnTiming | null {
+	if (!isRecord(value)) return null;
+	const durationMs = numberOr0(value.durationMs);
+	return durationMs === 0 ? null : { durationMs };
+}
+
+function asPromptCache(value: unknown): OutOfTurnPromptCache | null {
+	if (!isRecord(value)) return null;
+	if (typeof value.source !== "string" || value.source.length === 0) return null;
+	return {
+		promptTokens: numberOr0(value.promptTokens),
+		cachedTokens: typeof value.cachedTokens === "number" ? value.cachedTokens : null,
+		uncachedPrefillTokens: typeof value.uncachedPrefillTokens === "number" ? value.uncachedPrefillTokens : null,
+		promptMs: numberOr0(value.promptMs),
+		source: value.source,
 	};
 }
 

package/src/domains/observability/trace-store.ts

@@ -7,7 +7,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { hostname } from "node:os";
 import { dirname, join } from "node:path";
@@ -27,6 +27,32 @@ export const TRACE_DATABASE_FILE = "trace.sqlite";
 export const TRACE_EVENT_POLL_LIMIT = 500;
 export const TRACE_PAYLOAD_LIMIT_BYTES = 16 * 1024;
 export const TRACE_WRITE_QUEUE_LIMIT = 2048;
+export const TRACE_RETENTION_DAYS_ENV = "CLIO_CODER_TRACE_RETENTION_DAYS";
+export const TRACE_MAX_BYTES_ENV = "CLIO_CODER_TRACE_MAX_BYTES";
+
+export interface TraceRetentionPolicy {
+	maxAgeDays: number;
+	maxBytes: number;
+}
+
+export interface TracePruneResult {
+	runsRemoved: number;
+	rowsRemoved: number;
+	bytesBefore: number;
+	bytesAfter: number;
+	bytesRemoved: number;
+	vacuumed: boolean;
+	protectedRuns: number;
+}
+
+/** Thirty days or 128 MiB, whichever limit the mirror reaches first. */
+export const DEFAULT_TRACE_RETENTION_POLICY: Readonly<TraceRetentionPolicy> = Object.freeze({
+	maxAgeDays: 30,
+	maxBytes: 128 * 1024 * 1024,
+});
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+const VACUUM_RECLAIMABLE_FRACTION = 0.2;
 
 type DatabaseSyncConstructor = typeof import("node:sqlite").DatabaseSync;
 let sqliteConstructor: DatabaseSyncConstructor | null = null;
@@ -110,6 +136,40 @@ export function traceDatabasePath(stateDir: string): string {
 	return join(stateDir, TRACE_DATABASE_FILE);
 }
 
+/** Resolve the two operator-configurable retention bounds. */
+export function resolveTraceRetentionPolicy(
+	overrides: Partial<TraceRetentionPolicy> = {},
+	environment: NodeJS.ProcessEnv = process.env,
+): TraceRetentionPolicy {
+	const maxAgeDays =
+		overrides.maxAgeDays ??
+		parsePositiveRetentionNumber(environment[TRACE_RETENTION_DAYS_ENV], TRACE_RETENTION_DAYS_ENV, 1);
+	const maxBytes =
+		overrides.maxBytes ??
+		parsePositiveRetentionNumber(environment[TRACE_MAX_BYTES_ENV], TRACE_MAX_BYTES_ENV, 1024 * 1024);
+	return {
+		maxAgeDays: requirePositiveRetentionNumber(maxAgeDays, TRACE_RETENTION_DAYS_ENV, 1),
+		maxBytes: requirePositiveRetentionNumber(maxBytes, TRACE_MAX_BYTES_ENV, 1024 * 1024),
+	};
+}
+
+function parsePositiveRetentionNumber(raw: string | undefined, name: string, fallback: number): number {
+	if (raw === undefined || raw.trim().length === 0) {
+		return name === TRACE_RETENTION_DAYS_ENV
+			? DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays
+			: DEFAULT_TRACE_RETENTION_POLICY.maxBytes;
+	}
+	const value = Number(raw);
+	return requirePositiveRetentionNumber(value, name, fallback);
+}
+
+function requirePositiveRetentionNumber(value: number, name: string, minimum: number): number {
+	if (!Number.isSafeInteger(value) || value < minimum) {
+		throw new Error(`${name} must be an integer of at least ${minimum}`);
+	}
+	return value;
+}
+
 export class TraceSchemaVersionError extends Error {
 	constructor(readonly found: number | null) {
 		super(
@@ -494,8 +554,13 @@ function reconcileAbandonedRuns(db: DatabaseSync): void {
 
 export class TraceStore {
 	readonly db: DatabaseSync;
+	private readonly retention: TraceRetentionPolicy;
 
-	constructor(readonly path: string) {
+	constructor(
+		readonly path: string,
+		options: { retention?: Partial<TraceRetentionPolicy> } = {},
+	) {
+		this.retention = resolveTraceRetentionPolicy(options.retention);
 		mkdirSync(dirname(path), { recursive: true });
 		this.db = new (databaseSyncConstructor())(path);
 		applyConnectionPragmas(this.db);
@@ -523,6 +588,86 @@ export class TraceStore {
 		}
 	}
 
+	/**
+	 * Remove whole terminal runs, including all of their dependent rows.
+	 *
+	 * Age pruning runs first. If the allocated database is still above the byte
+	 * limit, the oldest remaining terminal runs are removed until the live page
+	 * set fits or only queued/running runs remain. A live run is never a candidate.
+	 */
+	prune(policy: Partial<TraceRetentionPolicy> = this.retention, now = new Date().toISOString()): TracePruneResult {
+		const resolved = resolveTraceRetentionPolicy(policy);
+		const nowMs = Date.parse(now);
+		if (!Number.isFinite(nowMs)) throw new Error(`trace prune time is invalid: ${now}`);
+		const bytesBefore = traceDatabaseFootprintBytes(this.path);
+		let rowsRemoved = 0;
+		let runsRemoved = 0;
+		const removed = new Set<string>();
+		const cutoff = new Date(Math.max(0, nowMs - resolved.maxAgeDays * MILLISECONDS_PER_DAY)).toISOString();
+
+		const ageCandidates = this.db
+			.prepare(
+				"SELECT run_id FROM runs WHERE status IN ('success','fail') AND ended_at IS NOT NULL AND ended_at < ? ORDER BY ended_at, started_at, run_id",
+			)
+			.all(cutoff) as { run_id: string }[];
+		if (ageCandidates.length > 0) {
+			this.transaction(() => {
+				for (const candidate of ageCandidates) {
+					rowsRemoved += deleteTraceRun(this.db, candidate.run_id);
+					runsRemoved += 1;
+					removed.add(candidate.run_id);
+				}
+			});
+		}
+
+		let pages = tracePageStats(this.db);
+		if (pages.usedBytes > resolved.maxBytes) {
+			const sizeCandidates = this.db
+				.prepare(
+					"SELECT run_id FROM runs WHERE status IN ('success','fail') AND ended_at IS NOT NULL ORDER BY ended_at, started_at, run_id",
+				)
+				.all() as { run_id: string }[];
+			this.transaction(() => {
+				for (const candidate of sizeCandidates) {
+					if (pages.usedBytes <= resolved.maxBytes) break;
+					if (removed.has(candidate.run_id)) continue;
+					rowsRemoved += deleteTraceRun(this.db, candidate.run_id);
+					runsRemoved += 1;
+					removed.add(candidate.run_id);
+					pages = tracePageStats(this.db);
+				}
+			});
+		}
+
+		pages = tracePageStats(this.db);
+		const reclaimableFraction = pages.pageCount === 0 ? 0 : pages.freePages / pages.pageCount;
+		const sizeNeedsReclaim = pages.allocatedBytes > resolved.maxBytes && pages.freePages > 0;
+		const vacuumed =
+			rowsRemoved > 0 && pages.freePages > 0 && (reclaimableFraction >= VACUUM_RECLAIMABLE_FRACTION || sizeNeedsReclaim);
+		if (vacuumed) {
+			this.db.exec("VACUUM");
+			this.db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+		}
+
+		const protectedRuns = Number(
+			(
+				this.db.prepare("SELECT COUNT(*) AS count FROM runs WHERE status IN ('queued','running')").get() as {
+					count: number | bigint;
+				}
+			).count,
+		);
+		const bytesAfter = traceDatabaseFootprintBytes(this.path);
+		return {
+			runsRemoved,
+			rowsRemoved,
+			bytesBefore,
+			bytesAfter,
+			bytesRemoved: Math.max(0, bytesBefore - bytesAfter),
+			vacuumed,
+			protectedRuns,
+		};
+	}
+
 	upsertRun(input: DispatchEnqueuedPayload, at = new Date().toISOString()): void {
 		this.transaction(() => {
 			this.db
@@ -859,6 +1004,7 @@ export class TraceStore {
 				startedAt: at,
 			});
 		});
+		this.prune(this.retention, at);
 	}
 
 	/**
@@ -971,9 +1117,53 @@ export class TraceStore {
 				startedAt: input.at,
 			});
 		});
+		this.prune(this.retention, input.at);
 	}
 }
 
+interface TracePageStats {
+	pageCount: number;
+	freePages: number;
+	allocatedBytes: number;
+	usedBytes: number;
+}
+
+function tracePageStats(db: DatabaseSync): TracePageStats {
+	const pageSize = Number((db.prepare("PRAGMA page_size").get() as { page_size: number | bigint }).page_size);
+	const pageCount = Number((db.prepare("PRAGMA page_count").get() as { page_count: number | bigint }).page_count);
+	const freePages = Number(
+		(db.prepare("PRAGMA freelist_count").get() as { freelist_count: number | bigint }).freelist_count,
+	);
+	return {
+		pageCount,
+		freePages,
+		allocatedBytes: pageCount * pageSize,
+		usedBytes: Math.max(0, pageCount - freePages) * pageSize,
+	};
+}
+
+function deleteTraceRun(db: DatabaseSync, runId: string): number {
+	let rows = 0;
+	for (const table of ["events", "envelopes", "gate_results", "agent_sessions", "processes", "phases", "runs"]) {
+		const result = db.prepare(`DELETE FROM ${table} WHERE run_id=?`).run(runId);
+		rows += Number(result.changes);
+	}
+	return rows;
+}
+
+function traceDatabaseFootprintBytes(path: string): number {
+	let total = 0;
+	for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+		try {
+			total += statSync(candidate).size;
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+			if (code !== "ENOENT") throw error;
+		}
+	}
+	return total;
+}
+
 export class TraceReader {
 	readonly db: DatabaseSync;
 
@@ -1022,6 +1212,48 @@ export class TraceReader {
 			) as unknown as TraceEventRow[];
 	}
 
+	/**
+	 * Per-kind event tallies for one run.
+	 *
+	 * Aggregated in SQL rather than by reading rows, so `payload_json` and the
+	 * free-form event name are never loaded at all. That is the point: a caller
+	 * that only ever wants shapes should not be holding the payloads in memory
+	 * on the way to counting them.
+	 */
+	eventKindCounts(runId: string): Array<{ type: string; count: number }> {
+		return this.db
+			.prepare("SELECT type, COUNT(*) AS count FROM events WHERE run_id=? GROUP BY type ORDER BY count DESC, type")
+			.all(runId) as unknown as Array<{ type: string; count: number }>;
+	}
+
+	/** Total events and the wall span they cover, without reading one of them. */
+	eventSpan(runId: string): { total: number; firstAt: string | null; lastAt: string | null } {
+		const row = this.db
+			.prepare(
+				`SELECT COUNT(*) AS total, MIN(started_at) AS firstAt,
+					MAX(COALESCE(ended_at, started_at)) AS lastAt FROM events WHERE run_id=?`,
+			)
+			.get(runId) as unknown as { total: number; firstAt: string | null; lastAt: string | null } | undefined;
+		return row ?? { total: 0, firstAt: null, lastAt: null };
+	}
+
+	/**
+	 * Per-kind process tallies for one run.
+	 *
+	 * Same reason as {@link eventKindCounts}, and more sharply: a process row
+	 * carries the command line, the pid, and the host, none of which a shape
+	 * count needs.
+	 */
+	processKindCounts(runId: string): Array<{ kind: string; total: number; running: number }> {
+		return this.db
+			.prepare(
+				`SELECT kind, COUNT(*) AS total,
+					SUM(CASE WHEN ended_at IS NULL THEN 1 ELSE 0 END) AS running
+				 FROM processes WHERE run_id=? GROUP BY kind ORDER BY total DESC, kind`,
+			)
+			.all(runId) as unknown as Array<{ kind: string; total: number; running: number }>;
+	}
+
 	processes(runId: string): TraceProcessRow[] {
 		return this.db
 			.prepare("SELECT * FROM processes WHERE run_id=? ORDER BY ended_at IS NOT NULL, id")