@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/observability/compaction-usage.ts

@@ -0,0 +1,118 @@
+/** Preserve spending from summary streams that did not produce a checkpoint. */
+
+import type { CompactionCallObservation } from "../session/compaction/compact.js";
+import { extractReasoningTokens } from "../session/context-accounting.js";
+import type { BackgroundMemoryUsageSink } from "./background-memory-usage.js";
+import { appendOutOfTurnUsageRow, type OutOfTurnUsage, type OutOfTurnUsageRow } from "./out-of-turn-usage.js";
+
+export interface CompactionUsageOrigin {
+	stateDir: string;
+	sessionId: string;
+	repoIdentity: string;
+	target: string;
+	model: string;
+}
+
+/** Failed adapter zeros cannot distinguish absent usage from a reported zero. */
+function observedUsage(call: CompactionCallObservation): OutOfTurnUsage {
+	const raw = isRecord(call.usage) ? call.usage : {};
+	const reading = (value: unknown): number | null =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 && (call.outcome === "success" || value > 0)
+			? value
+			: null;
+	const cost = isRecord(raw.cost) ? reading(raw.cost.total) : null;
+	// Adapter cost is a price estimate, not independent provider billing evidence.
+	const costUsd = cost !== null && cost > 0 ? cost : null;
+	const reasoning = extractReasoningTokens({ ...raw, reasoningTokens: undefined });
+	return {
+		input: reading(raw.input),
+		output: reading(raw.output),
+		cacheRead: reading(raw.cacheRead),
+		cacheWrite: reading(raw.cacheWrite),
+		reasoning: reasoning !== null && reasoning > 0 ? reasoning : null,
+		totalTokens: reading(raw.totalTokens),
+		costUsd,
+		costProvenance: costUsd === null ? "unknown" : "estimated",
+	};
+}
+
+/**
+ * The checkpoint is the sole accounting source on success. Call this only when
+ * no checkpoint exists; each row is one actual stream invocation, not a retry.
+ * Missing amounts remain null on disk. Numeric live counters are known subtotals.
+ */
+export function recordFailedCompactionCalls(
+	origin: CompactionUsageOrigin,
+	calls: ReadonlyArray<CompactionCallObservation>,
+	observability?: BackgroundMemoryUsageSink,
+): void {
+	for (const call of calls) {
+		const usage = observedUsage(call);
+		const row: OutOfTurnUsageRow = {
+			label: "failed-compaction",
+			callOutcome: call.outcome,
+			sessionId: origin.sessionId,
+			repoIdentity: origin.repoIdentity,
+			timestamp: call.timestamp,
+			target: origin.target,
+			attributedModelId: origin.model,
+			usage,
+			timing: { durationMs: call.durationMs },
+		};
+		appendOutOfTurnUsageRow(origin.stateDir, row, { required: true });
+		// Do not create a measured-zero live entry for a wholly unobserved call.
+		if (!Object.values(usage).some((value) => typeof value === "number" && value > 0)) continue;
+		observability?.recordTokens(
+			origin.target,
+			origin.model,
+			usage.totalTokens ?? 0,
+			usage.costUsd ?? 0,
+			{
+				input: usage.input ?? 0,
+				output: usage.output ?? 0,
+				cacheRead: usage.cacheRead ?? 0,
+				cacheWrite: usage.cacheWrite ?? 0,
+				reasoningTokens: usage.reasoning ?? 0,
+				totalTokens: usage.totalTokens ?? 0,
+				apiCalls: 1,
+			},
+			usage.costProvenance,
+			undefined,
+			"failed-compaction",
+		);
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const USAGE_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "reasoning", "totalTokens", "costUsd"] as const;
+type UsageField = (typeof USAGE_FIELDS)[number];
+
+/** Known subtotals and missing-field coverage; zero missing values are never inferred. */
+export function summarizeFailedCompactionUsage(rows: ReadonlyArray<OutOfTurnUsageRow>) {
+	const calls = rows.filter((row) => row.label === "failed-compaction");
+	const knownUsage = Object.fromEntries(USAGE_FIELDS.map((field) => [field, null])) as Record<UsageField, number | null>;
+	const erroredKnownUsage = { ...knownUsage };
+	const unobservedUsageCalls = Object.fromEntries(USAGE_FIELDS.map((field) => [field, 0])) as Record<UsageField, number>;
+	for (const row of calls) {
+		for (const field of USAGE_FIELDS) {
+			const value = row.usage[field];
+			if (value === null) unobservedUsageCalls[field] += 1;
+			else {
+				knownUsage[field] = (knownUsage[field] ?? 0) + value;
+				if (row.callOutcome === "error") erroredKnownUsage[field] = (erroredKnownUsage[field] ?? 0) + value;
+			}
+		}
+	}
+	return {
+		calls: calls.length,
+		successfulCalls: calls.filter((row) => row.callOutcome === "success").length,
+		erroredCalls: calls.filter((row) => row.callOutcome === "error").length,
+		abortedCalls: calls.filter((row) => row.callOutcome === "aborted").length,
+		knownUsage,
+		erroredKnownUsage,
+		unobservedUsageCalls,
+	};
+}

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/cost.ts

@@ -137,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" | "prewarm" | "background-memory";
+export type CostEntryLabel = "side-question" | "handoff" | "prewarm" | "background-memory" | "failed-compaction";
 
 export interface CostEntry {
 	providerId: 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";
@@ -36,6 +37,11 @@ type DispatchTerminalLike = {
 	[K in keyof DispatchCompletedPayload]?: DispatchCompletedPayload[K] | undefined;
 };
 
+/** Pre-admission failures have an announced run id but never create a run ledger. */
+export function dispatchHasEvidenceLedger(payload: DispatchTerminalLike): boolean {
+	return payload.lineage !== undefined;
+}
+
 function recordDispatchCost(
 	telemetry: ReturnType<typeof createTelemetry>,
 	cost: ReturnType<typeof createCostTracker>,
@@ -171,7 +177,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);
@@ -214,7 +227,7 @@ export function createObservabilityBundle(
 					recordDispatchCost(telemetry, cost, payload);
 					// A failed run is never a first-pass success; still build the
 					// bundle so its failure-cause tags exist for the index.
-					if (typeof payload.runId === "string" && payload.runId.length > 0) {
+					if (typeof payload.runId === "string" && payload.runId.length > 0 && dispatchHasEvidenceLedger(payload)) {
 						trackBuild(payload.runId, false, payload.lineage?.attempt);
 					}
 				}),

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

@@ -27,7 +27,7 @@
  * skipped, never fatal.
  */
 
-import { closeSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
 import { withStateFileLockSync } from "../../core/state-file-lock.js";
@@ -74,13 +74,13 @@ export interface OutOfTurnPromptCache {
 
 /** Provider-reported usage for one out-of-turn call. */
 export interface OutOfTurnUsage {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	reasoning: number;
-	totalTokens: number;
-	costUsd: number;
+	input: number | null;
+	output: number | null;
+	cacheRead: number | null;
+	cacheWrite: number | null;
+	reasoning: number | null;
+	totalTokens: number | null;
+	costUsd: number | null;
 	costProvenance: CostProvenance;
 }
 
@@ -97,6 +97,8 @@ export interface OutOfTurnUsageRow {
 	target: string;
 	attributedModelId: string;
 	usage: OutOfTurnUsage;
+	/** New failed-compaction rows preserve unknown usage as null. Legacy rows are unchanged. */
+	callOutcome?: "success" | "error" | "aborted";
 	/** Present when the caller measured the call. */
 	timing?: OutOfTurnTiming;
 	/** Present when the serving backend reported prefill facts. */
@@ -115,21 +117,31 @@ export function outOfTurnUsagePath(stateDir: string): string {
 let appendsSinceBoundCheck = BOUND_CHECK_INTERVAL;
 
 /**
- * Append one priced out-of-turn call. Never throws: this runs on the same path
- * that answers an operator's side question, and a failed bookkeeping write must
- * not take the answer down with it.
+ * Append one out-of-turn call. Optional bookkeeping keeps its existing diagnostic
+ * write policy. Required failed-compaction records flush the append and throw on
+ * a failed or incomplete write, so their caller cannot report recorded spending.
  */
-export function appendOutOfTurnUsageRow(stateDir: string, row: OutOfTurnUsageRow): void {
+export function appendOutOfTurnUsageRow(
+	stateDir: string,
+	row: OutOfTurnUsageRow,
+	options: { required?: boolean } = {},
+): void {
 	const path = outOfTurnUsagePath(stateDir);
 	try {
 		mkdirSync(dirname(path), { recursive: true });
 		const fd = openSync(path, "a");
 		try {
-			writeSync(fd, `${JSON.stringify(row)}\n`);
+			const line = `${JSON.stringify(row)}\n`;
+			const written = writeSync(fd, line);
+			if (options.required) {
+				if (written !== Buffer.byteLength(line)) throw new Error("incomplete usage row write");
+				fsyncSync(fd);
+			}
 		} finally {
 			closeSync(fd);
 		}
 	} catch (error) {
+		if (options.required) throw new Error(`compaction usage row not written: ${messageOf(error)}`, { cause: error });
 		process.stderr.write(`[clio-coder:usage] out-of-turn usage row not written: ${messageOf(error)}\n`);
 		return;
 	}
@@ -205,11 +217,25 @@ 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" && label !== "prewarm" && label !== "background-memory")
+	if (
+		label !== "side-question" &&
+		label !== "handoff" &&
+		label !== "prewarm" &&
+		label !== "background-memory" &&
+		label !== "failed-compaction"
+	)
 		return null;
 	if (typeof value.timestamp !== "string" || value.timestamp.length === 0) return null;
 	if (!isRecord(value.usage)) return null;
 	const usage = value.usage;
+	if (
+		label === "failed-compaction" &&
+		value.callOutcome !== "success" &&
+		value.callOutcome !== "error" &&
+		value.callOutcome !== "aborted"
+	)
+		return null;
+	const reading = label === "failed-compaction" ? nullableNumber : numberOr0;
 	const timing = asTiming(value.timing);
 	const promptCache = asPromptCache(value.promptCache);
 	return {
@@ -223,15 +249,16 @@ function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 				? value.attributedModelId
 				: "unknown",
 		usage: {
-			input: numberOr0(usage.input),
-			output: numberOr0(usage.output),
-			cacheRead: numberOr0(usage.cacheRead),
-			cacheWrite: numberOr0(usage.cacheWrite),
-			reasoning: numberOr0(usage.reasoning),
-			totalTokens: numberOr0(usage.totalTokens),
-			costUsd: numberOr0(usage.costUsd),
+			input: reading(usage.input),
+			output: reading(usage.output),
+			cacheRead: reading(usage.cacheRead),
+			cacheWrite: reading(usage.cacheWrite),
+			reasoning: reading(usage.reasoning),
+			totalTokens: reading(usage.totalTokens),
+			costUsd: reading(usage.costUsd),
 			costProvenance: asCostProvenance(usage.costProvenance),
 		},
+		...(label === "failed-compaction" ? { callOutcome: value.callOutcome as "success" | "error" | "aborted" } : {}),
 		...(timing === null ? {} : { timing }),
 		...(promptCache === null ? {} : { promptCache }),
 	};
@@ -259,6 +286,10 @@ function asCostProvenance(value: unknown): CostProvenance {
 	return value === "known" || value === "known_free" || value === "estimated" ? value : "unknown";
 }
 
+function nullableNumber(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
 function numberOr0(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }

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> = {};
@@ -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

@@ -341,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 {
@@ -423,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 (
@@ -524,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
@@ -570,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);
 		});
 	}
@@ -673,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(
@@ -1046,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,
@@ -1167,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 });
@@ -1177,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 {
@@ -1185,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
 		);
 	}