@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/observability/contract.ts

@@ -18,25 +18,24 @@ export interface TokenThroughputSnapshot {
 }
 
 /**
- * One bounded, product-facing observability event. Notices are a redacted,
- * append-only stream: a runtime eviction, a blocked tool, a hook crash, a
- * pruned context window, and so on. They never carry raw worker output or tool
- * arguments; `message` is a short rendered line and `ref` links back to the
- * subject (a run, a target, an evidence bundle) without embedding its contents.
+ * One bounded, product-facing observability event: an evidence build that
+ * failed for a run, read by the Dispatch Board to explain why a run has no
+ * evidence bundle. This used to also carry runtime/middleware/safety/loop/
+ * tool-budget/context/budget notices classified off the same bus channels the
+ * interactive layer's own notice pipeline (bus-notices.ts and
+ * interactive-event-projection.ts) classifies independently for the toast
+ * surface a session actually shows; those seven kinds had no reader of their
+ * own here and were removed rather than kept as an unread second opinion.
+ * `message` is a short rendered line and `ref` links back to the run.
  */
 export interface ObservabilityNotice {
 	id: string;
 	at: number;
-	kind: "runtime" | "middleware" | "safety" | "loop" | "tool-budget" | "context" | "budget" | "provider" | "evidence";
+	kind: "evidence";
 	level: "info" | "warning" | "error";
 	message: string;
 	ref?: {
 		runId?: string;
-		agentId?: string;
-		targetId?: string;
-		modelId?: string;
-		evidenceId?: string;
-		tool?: string;
 	};
 }
 

package/src/domains/observability/extension.ts

@@ -1,7 +1,8 @@
 /**
  * Observability domain wire-up. Listens to dispatch + safety bus channels and
- * folds payloads into telemetry/cost trackers. Emits nothing; other domains
- * read the snapshot through the contract.
+ * folds payloads into telemetry/cost trackers. Other domains read the snapshot
+ * through the contract; the one thing it emits is
+ * `accountability.evidenceReady`, once per run whose evidence bundle landed.
  */
 
 import { BusChannels, type DispatchCompletedPayload } from "../../core/bus-events.js";
@@ -96,7 +97,7 @@ async function buildAndIndexEvidence(
 		});
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		process.stderr.write(`[clio:evidence] auto-build failed for run ${runId}: ${message}\n`);
+		process.stderr.write(`[clio-coder:evidence] auto-build failed for run ${runId}: ${message}\n`);
 		hooks.onFailed(runId, message);
 	}
 }
@@ -171,7 +172,14 @@ export function createObservabilityBundle(
 	const trackBuild = (runId: string, succeeded: boolean, attempt: number | undefined): void => {
 		projection.evidenceBuildStarted(runId);
 		const build = buildAndIndexEvidence(runId, succeeded, attempt, {
-			onReady: (id, evidence) => projection.evidenceBuildSucceeded(id, evidence),
+			onReady: (id, evidence) => {
+				projection.evidenceBuildSucceeded(id, evidence);
+				// The same fact, once, for listeners outside this closure (the ACP
+				// server forwards it as the opt-in `accountability.evidenceReady`
+				// kind). The payload spreads the evidence object the projection just
+				// received rather than rebuilding it, so the two cannot drift.
+				context.bus.emit(BusChannels.AccountabilityEvidenceReady, { runId: id, ...evidence });
+			},
 			onFailed: (id, message) => projection.evidenceBuildFailed(id, message),
 		});
 		pendingBuilds.add(build);

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

@@ -130,7 +130,7 @@ export function appendOutOfTurnUsageRow(stateDir: string, row: OutOfTurnUsageRow
 			closeSync(fd);
 		}
 	} catch (error) {
-		process.stderr.write(`[clio:usage] out-of-turn usage row not written: ${messageOf(error)}\n`);
+		process.stderr.write(`[clio-coder:usage] out-of-turn usage row not written: ${messageOf(error)}\n`);
 		return;
 	}
 	appendsSinceBoundCheck += 1;
@@ -139,7 +139,7 @@ export function appendOutOfTurnUsageRow(stateDir: string, row: OutOfTurnUsageRow
 	try {
 		boundOutOfTurnUsageFile(path);
 	} catch (error) {
-		process.stderr.write(`[clio:usage] out-of-turn usage ring not bounded: ${messageOf(error)}\n`);
+		process.stderr.write(`[clio-coder:usage] out-of-turn usage ring not bounded: ${messageOf(error)}\n`);
 	}
 }
 

package/src/domains/observability/projection.ts

@@ -17,8 +17,10 @@
  */
 
 import { BusChannels } from "../../core/bus-events.js";
+import { resolveDispatchFailureStatus } from "../../core/dispatch-outcome.js";
 import type { SafeEventBus } from "../../core/event-bus.js";
 import type { TargetStatus } from "../providers/contract.js";
+import { resolveCostProvenance } from "../providers/types/cost-provenance.js";
 import type { AccountabilitySummary } from "./accountability.js";
 import type {
 	ObservabilityNotice,
@@ -94,17 +96,6 @@ function resolveHeartbeat(status: unknown): ObservabilityRunSummary["status"] |
 	return null;
 }
 
-/** Map a DispatchFailed outcome/reason to a summary status, mirroring the board. */
-function resolveFailedStatus(reason: unknown): ObservabilityRunSummary["status"] {
-	if (reason === "dead" || reason === "stalled") return "dead";
-	if (reason === "interrupted" || reason === "canceled") return "aborted";
-	return "failed";
-}
-
-function normalizeLevel(value: unknown): ObservabilityNotice["level"] {
-	return value === "error" || value === "warning" || value === "info" ? value : "info";
-}
-
 /** Build a notice ref from candidate parts, dropping anything non-string/empty. */
 function makeRef(parts: Record<string, unknown>): ObservabilityNotice["ref"] | undefined {
 	const ref: Record<string, string> = {};
@@ -167,7 +158,7 @@ export function createObservabilityProjection(bus: SafeEventBus, deps: Projectio
 				listener(snapshot);
 			} catch (error) {
 				const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
-				console.error(`[clio:observability] projection listener crashed: ${message}`);
+				console.error(`[clio-coder:observability] projection listener crashed: ${message}`);
 			}
 		}
 	}
@@ -216,22 +207,20 @@ export function createObservabilityProjection(bus: SafeEventBus, deps: Projectio
 		if (typeof id.runtimeKind === "string" && id.runtimeKind.length > 0) summary.runtimeKind = id.runtimeKind;
 	}
 
+	// num()'s Number.isFinite check matters here specifically: a NaN or
+	// Infinity costUsd/tokenCount from a payload used to pass the bare
+	// `typeof === "number"` check this function had instead, so the projection
+	// could corrupt a run's running total on a malformed terminal payload while
+	// the dispatch board's parseFiniteNumber (an identical check) rejected it.
 	function applyTerminalTokens(summary: ObservabilityRunSummary, payload: Record<string, unknown>): void {
-		if (typeof payload.tokenCount === "number") summary.tokens.total = payload.tokenCount;
+		summary.tokens.total = num(payload.tokenCount, summary.tokens.total);
 		if (typeof payload.inputTokenCount === "number") {
-			summary.tokens.input = payload.inputTokenCount + num(payload.cacheReadTokenCount, 0);
-		}
-		if (typeof payload.outputTokenCount === "number") summary.tokens.output = payload.outputTokenCount;
-		if (typeof payload.reasoningTokenCount === "number") summary.tokens.reasoning = payload.reasoningTokenCount;
-		if (typeof payload.costUsd === "number") summary.costUsd = payload.costUsd;
-		if (
-			payload.costProvenance === "known" ||
-			payload.costProvenance === "known_free" ||
-			payload.costProvenance === "estimated" ||
-			payload.costProvenance === "unknown"
-		) {
-			summary.costProvenance = payload.costProvenance;
+			summary.tokens.input = num(payload.inputTokenCount, summary.tokens.input) + num(payload.cacheReadTokenCount, 0);
 		}
+		summary.tokens.output = num(payload.outputTokenCount, summary.tokens.output);
+		summary.tokens.reasoning = num(payload.reasoningTokenCount, summary.tokens.reasoning);
+		summary.costUsd = num(payload.costUsd, summary.costUsd);
+		summary.costProvenance = resolveCostProvenance(payload.costProvenance, summary.costProvenance);
 	}
 
 	function pushNotice(
@@ -337,7 +326,7 @@ export function createObservabilityProjection(bus: SafeEventBus, deps: Projectio
 			const now = Date.now();
 			const summary = runs.get(runId) ?? emptyRun(runId, now);
 			applyIdentity(summary, payload);
-			summary.status = resolveFailedStatus(payload.reason);
+			summary.status = resolveDispatchFailureStatus(payload.reason);
 			summary.updatedAtMs = now;
 			summary.finishedAtMs = now;
 			summary.durationMs = num(payload.durationMs, Math.max(0, now - summary.startedAtMs));
@@ -355,71 +344,6 @@ export function createObservabilityProjection(bus: SafeEventBus, deps: Projectio
 			providerHealth.set(payload.id, payload.status as TargetStatus);
 			markChanged();
 		}),
-		bus.on(BusChannels.RuntimeNotice, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			pushNotice(
-				"runtime",
-				normalizeLevel(payload.level),
-				str(payload.message, "runtime notice"),
-				makeRef({ targetId: payload.targetId, modelId: payload.model }),
-			);
-		}),
-		bus.on(BusChannels.MiddlewareHookFailed, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			const kind = payload.kind;
-			// Mirror the interactive notice policy: every crashed hook surfaces, but
-			// a budget overrun only surfaces once it is steady-state slowness.
-			if (kind === "budget_exceeded" && payload.steadyStateWarn !== true) return;
-			const hook = str(payload.hook, "hook");
-			const message =
-				typeof payload.message === "string" && payload.message.length > 0
-					? payload.message
-					: kind === "budget_exceeded"
-						? `middleware hook ${hook} exceeded ${num(payload.budgetMs, 0)}ms budget`
-						: `middleware hook ${hook} failed`;
-			pushNotice("middleware", kind === "budget_exceeded" ? "warning" : "error", message);
-		}),
-		bus.on(BusChannels.SafetyBlocked, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			const tool = str(payload.tool, "tool");
-			const rejection = (payload.rejection ?? {}) as { short?: unknown };
-			const short = str(rejection.short, `${str(payload.actionClass, "action")} blocked`);
-			pushNotice("safety", "warning", `${tool}: ${short}`, makeRef({ tool: payload.tool }));
-		}),
-		bus.on(BusChannels.LoopBlocked, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			const tool = str(payload.tool, "tool");
-			pushNotice(
-				"loop",
-				payload.interrupted === true ? "error" : "warning",
-				`loop guard blocked repeated ${tool} (${num(payload.repeatCount, 0)}x)`,
-				makeRef({ tool: payload.tool }),
-			);
-		}),
-		bus.on(BusChannels.ToolBudgetExceeded, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			const tool = str(payload.tool, "tool");
-			pushNotice(
-				"tool-budget",
-				payload.interrupted === true ? "error" : "warning",
-				`tool-call budget reached on ${tool} (${num(payload.callsThisTurn, 0)} calls)`,
-				makeRef({ tool: payload.tool }),
-			);
-		}),
-		bus.on(BusChannels.ContextPruned, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			const reclaimed = Math.max(0, num(payload.tokensBefore, 0) - num(payload.tokensAfter, 0));
-			pushNotice("context", "info", `context pruned ${reclaimed} tokens (${str(payload.stage, "prune")})`);
-		}),
-		bus.on(BusChannels.BudgetAlert, (raw: unknown) => {
-			const payload = (raw ?? {}) as Record<string, unknown>;
-			const over = payload.level === "over";
-			pushNotice(
-				"budget",
-				over ? "error" : "warning",
-				`session cost $${num(payload.currentUsd, 0).toFixed(2)} ${over ? "over" : "at"} $${num(payload.ceilingUsd, 0).toFixed(2)} ceiling`,
-			);
-		}),
 	];
 
 	return {

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

@@ -19,6 +19,7 @@ import type {
 	DispatchProgressPayload,
 	DispatchStartedPayload,
 } from "../../core/bus-events.js";
+import { normalizeClioCoderEventType } from "../../core/naming-events.js";
 import { processAlive, processBirthToken } from "../../core/process-identity.js";
 import { createRedactionTally, redactSecretsText } from "../evidence/redact.js";
 
@@ -110,7 +111,7 @@ function requireSqlite(): DatabaseSyncConstructor {
  * Exported for the contract test, which drives it with a load that emits both
  * warnings; production has exactly one caller.
  */
-export function loadWithSqliteWarningSuppressed<T>(load: () => T): T {
+function loadWithSqliteWarningSuppressed<T>(load: () => T): T {
 	if (warningTracingRequested()) return load();
 	const emitWarning = process.emitWarning;
 	const forward = emitWarning.bind(process) as (...args: unknown[]) => void;
@@ -340,6 +341,8 @@ export interface TraceRunRow {
 	ended_at: string | null;
 	total_tokens: number | null;
 	total_cost_usd: number | null;
+	/** 'dispatch' for a worker run, 'session' for an interactive chat-loop turn. */
+	source: "dispatch" | "session";
 }
 
 export interface TracePhaseRow {
@@ -422,7 +425,8 @@ CREATE TABLE runs (
   started_at TEXT NOT NULL,
   ended_at TEXT,
   total_tokens INTEGER,
-  total_cost_usd REAL
+  total_cost_usd REAL,
+  source TEXT NOT NULL DEFAULT 'dispatch' CHECK(source IN ('dispatch','session'))
 );
 
 CREATE TABLE phases (
@@ -523,6 +527,23 @@ function ensureProcessOwnerColumns(db: DatabaseSync): void {
 	db.exec("ALTER TABLE processes ADD COLUMN host TEXT; ALTER TABLE processes ADD COLUMN birth_token TEXT;");
 }
 
+/**
+ * Additive discriminator between a dispatched run and an interactive session
+ * turn; older version-1 databases gain it in place. `runs`/`phases` held both
+ * kinds under one undocumented schema before this column existed, distinguishable
+ * only by the sentinel `assignment_id = SESSION_TRACE_ASSIGNMENT_ID` a session
+ * turn's row carries (recordSessionTurn's startSessionTurn) versus a real
+ * dispatch assignment id (upsertRun). The backfill reads that existing
+ * sentinel once; every row written after this migration sets `source`
+ * directly instead of relying on it.
+ */
+function ensureRunSourceColumn(db: DatabaseSync): void {
+	const columns = db.prepare("PRAGMA table_info(runs)").all() as { name: string }[];
+	if (columns.some((column) => column.name === "source")) return;
+	db.exec("ALTER TABLE runs ADD COLUMN source TEXT NOT NULL DEFAULT 'dispatch';");
+	db.prepare("UPDATE runs SET source = 'session' WHERE assignment_id = ?").run(SESSION_TRACE_ASSIGNMENT_ID);
+}
+
 /**
  * Finalize `running` rows whose recorded owner is on this host and provably
  * dead (pid gone, or alive under a different birth token, i.e. reused). Rows
@@ -569,6 +590,7 @@ export class TraceStore {
 		else if (version !== TRACE_SCHEMA_VERSION) throw new TraceSchemaVersionError(version);
 		this.transaction(() => {
 			ensureProcessOwnerColumns(this.db);
+			ensureRunSourceColumn(this.db);
 			reconcileAbandonedRuns(this.db);
 		});
 	}
@@ -672,8 +694,8 @@ export class TraceStore {
 		this.transaction(() => {
 			this.db
 				.prepare(`INSERT INTO runs
-          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at)
-          VALUES (?, ?, ?, 'queued', ?, ?, ?, ?, ?, ?)
+          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at, source)
+          VALUES (?, ?, ?, 'queued', ?, ?, ?, ?, ?, ?, 'dispatch')
           ON CONFLICT(run_id) DO UPDATE SET request=excluded.request, agent=excluded.agent,
             target=excluded.target, model=excluded.model, runtime=excluded.runtime, node=excluded.node`)
 				.run(
@@ -1045,8 +1067,8 @@ export class TraceStore {
 		this.transaction(() => {
 			this.db
 				.prepare(`INSERT INTO runs
-          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at)
-          VALUES (?, ?, ?, 'running', ?, ?, ?, ?, NULL, ?)
+          (run_id, assignment_id, request, status, agent, target, model, runtime, node, started_at, source)
+          VALUES (?, ?, ?, 'running', ?, ?, ?, ?, NULL, ?, 'session')
           ON CONFLICT(run_id) DO NOTHING`)
 				.run(
 					input.runId,
@@ -1166,6 +1188,15 @@ function traceDatabaseFootprintBytes(path: string): number {
 
 export class TraceReader {
 	readonly db: DatabaseSync;
+	/**
+	 * `runs.source` is an additive column (see ensureRunSourceColumn) a
+	 * TraceStore writer backfills in place. A read-only reader can open a
+	 * database no writer has touched since before the column existed — the
+	 * trace viewer opening a dormant install's trace.sqlite fresh is the
+	 * realistic case — and cannot ALTER TABLE to fix that itself, so it
+	 * derives the same value the migration would have written instead.
+	 */
+	private readonly runsSourceExpr: string;
 
 	constructor(readonly path: string) {
 		this.db = new (databaseSyncConstructor())(path, { readOnly: true });
@@ -1176,6 +1207,10 @@ export class TraceReader {
 		const mode = this.db.prepare("PRAGMA journal_mode").get() as { journal_mode: string };
 		if (mode.journal_mode.toLowerCase() !== "wal")
 			throw new Error(`trace database journal mode is ${mode.journal_mode}, expected WAL`);
+		const runColumns = this.db.prepare("PRAGMA table_info(runs)").all() as { name: string }[];
+		this.runsSourceExpr = runColumns.some((column) => column.name === "source")
+			? "*"
+			: `*, CASE WHEN assignment_id = '${SESSION_TRACE_ASSIGNMENT_ID}' THEN 'session' ELSE 'dispatch' END AS source`;
 	}
 
 	close(): void {
@@ -1184,13 +1219,15 @@ export class TraceReader {
 
 	runs(limit = 50): TraceRunRow[] {
 		return this.db
-			.prepare("SELECT * FROM runs ORDER BY started_at DESC LIMIT ?")
+			.prepare(`SELECT ${this.runsSourceExpr} FROM runs ORDER BY started_at DESC LIMIT ?`)
 			.all(clampInt(limit, 1, 500)) as unknown as TraceRunRow[];
 	}
 
 	run(runId: string): TraceRunRow | null {
 		return (
-			(this.db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId) as unknown as TraceRunRow | undefined) ?? null
+			(this.db.prepare(`SELECT ${this.runsSourceExpr} FROM runs WHERE run_id=?`).get(runId) as unknown as
+				| TraceRunRow
+				| undefined) ?? null
 		);
 	}
 
@@ -1201,7 +1238,7 @@ export class TraceReader {
 	}
 
 	events(runId: string, afterRowid = 0, limit = TRACE_EVENT_POLL_LIMIT): TraceEventRow[] {
-		return this.db
+		const rows = this.db
 			.prepare(`SELECT rowid, event_id, run_id, phase_id, parent_id, type, name, payload_json,
         tokens, started_at, ended_at FROM events
         WHERE run_id = ? AND rowid > ? ORDER BY rowid LIMIT ?`)
@@ -1210,6 +1247,7 @@ export class TraceReader {
 				Math.max(0, Math.trunc(afterRowid)),
 				clampInt(limit, 1, TRACE_EVENT_POLL_LIMIT),
 			) as unknown as TraceEventRow[];
+		return rows.map((row) => ({ ...row, type: normalizeClioCoderEventType(row.type) }));
 	}
 
 	/**
@@ -1221,9 +1259,17 @@ export class TraceReader {
 	 * on the way to counting them.
 	 */
 	eventKindCounts(runId: string): Array<{ type: string; count: number }> {
-		return this.db
+		const rows = 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 }>;
+		const counts = new Map<string, number>();
+		for (const row of rows) {
+			const type = normalizeClioCoderEventType(row.type);
+			counts.set(type, (counts.get(type) ?? 0) + row.count);
+		}
+		return [...counts]
+			.map(([type, count]) => ({ type, count }))
+			.sort((left, right) => right.count - left.count || left.type.localeCompare(right.type));
 	}
 
 	/** Total events and the wall span they cover, without reading one of them. */
@@ -1273,7 +1319,7 @@ export class TraceReader {
 	}
 
 	select(sql: string): Record<string, SQLInputValue>[] {
-		assertSelectOnly(sql);
+		assertTraceSelectOnly(sql);
 		return this.db.prepare(sql).all() as Record<string, SQLInputValue>[];
 	}
 }
@@ -1301,7 +1347,7 @@ export function createDispatchTraceMirror(
 	path: string,
 	options: { warn?: (message: string) => void; now?: () => string } = {},
 ): DispatchTraceMirror {
-	const warn = options.warn ?? ((message: string) => process.stderr.write(`[clio:trace] ${message}\n`));
+	const warn = options.warn ?? ((message: string) => process.stderr.write(`[clio-coder:trace] ${message}\n`));
 	const now = options.now ?? (() => new Date().toISOString());
 	let store: TraceStore | null = null;
 	let chain: Promise<void> = Promise.resolve();
@@ -1408,7 +1454,7 @@ function recordProgress(
 ): void {
 	if (!isRecord(payload.event)) return;
 	const event = payload.event;
-	const type = typeof event.type === "string" ? event.type : "progress";
+	const type = typeof event.type === "string" ? normalizeClioCoderEventType(event.type) : "progress";
 	const toolCallId = stringValue(event.toolCallId) ?? stringValue(event.tool_call_id);
 	if (
 		type === "message_end" &&
@@ -1442,7 +1488,7 @@ function recordProgress(
 			});
 		}
 	}
-	if ((type === "tool_execution_start" || type === "clio_tool_start") && toolCallId !== null) {
+	if ((type === "tool_execution_start" || type === "clio_coder_tool_start") && toolCallId !== null) {
 		starts.set(`${payload.runId}:${toolCallId}`, {
 			toolCallId,
 			tool: stringValue(event.toolName) ?? stringValue(event.tool) ?? "tool",
@@ -1451,7 +1497,7 @@ function recordProgress(
 		});
 		return;
 	}
-	if ((type === "tool_execution_end" || type === "clio_tool_finish") && toolCallId !== null) {
+	if ((type === "tool_execution_end" || type === "clio_coder_tool_finish") && toolCallId !== null) {
 		const key = `${payload.runId}:${toolCallId}`;
 		const start = starts.get(key);
 		// One clock frame per row. The worker measures `durationMs` on its own
@@ -1537,12 +1583,12 @@ function recordFailure(store: TraceStore, input: DispatchFailedPayload, at: stri
 function isCriticalTraceEvent(channel: string, raw: unknown): boolean {
 	if (channel !== "dispatch.progress") return true;
 	if (!isRecord(raw) || !isRecord(raw.event)) return false;
-	const type = raw.event.type;
+	const type = typeof raw.event.type === "string" ? normalizeClioCoderEventType(raw.event.type) : raw.event.type;
 	return (
 		type === "tool_execution_start" ||
 		type === "tool_execution_end" ||
-		type === "clio_tool_start" ||
-		type === "clio_tool_finish" ||
+		type === "clio_coder_tool_start" ||
+		type === "clio_coder_tool_finish" ||
 		type === "message_end" ||
 		type === "attempt_start"
 	);
@@ -1659,7 +1705,7 @@ function sha256(value: string): string {
 	return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-function assertSelectOnly(sql: string): void {
+export function assertTraceSelectOnly(sql: string): void {
 	const trimmed = sql.trim();
 	if (!/^(SELECT|WITH)\b/i.test(trimmed)) throw new Error("trace sql accepts SELECT or read-only WITH queries only");
 	if (trimmed.includes(";")) throw new Error("trace sql accepts exactly one statement");