@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/middleware/watchdog.ts

@@ -0,0 +1,281 @@
+/**
+ * The opt-in turn-end watchdog.
+ *
+ * A long agentic turn can leave the tree in a state nobody looked at: the
+ * model reports success, the operator reads the report, and the drift between
+ * what the board asked for and what the diff actually did stays invisible
+ * until someone reads the diff themselves. When `watchdog.enabled` is on, a
+ * turn that changed the tree is handed to one read-only verifier run briefed
+ * with the turn's coalesced diff and the board's current scope. Its blockers
+ * become one transcript notice and nothing else.
+ *
+ * What it deliberately does not do: it never auto-follows, never carries the
+ * turn onward, never queues a turn, and never mutates. A watchdog that could
+ * start work would be a second agent nobody asked for; this one can only tell
+ * the operator what it saw.
+ *
+ * The registration itself emits no middleware effects. It owns the decision of
+ * when to fire and the coalesced diff it fires with; the caller owns the
+ * dispatch and the notice.
+ */
+
+import { ToolNames } from "../../core/tool-names.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import type { MiddlewareEffect, MiddlewareHookInput } from "./types.js";
+
+export const WATCHDOG_REGISTRATION_ID = "observer.watchdog";
+
+/**
+ * Bound on the coalesced diff a watchdog briefing carries, in UTF-8 bytes. The
+ * run is meant to be cheap enough to spend on every mutating turn, so it is
+ * given the shape of the change rather than every byte of it.
+ */
+export const WATCHDOG_DIFF_MAX_BYTES = 12 * 1024;
+
+/** Bound on how many mutated paths the briefing names before it summarizes the rest. */
+export const WATCHDOG_PATHS_MAX = 40;
+
+export const WATCHDOG_TRUNCATION_MARKER = "\n[diff truncated]";
+
+/** Tools whose successful results carry a file diff worth coalescing. */
+const MUTATING_TOOL_NAMES = new Set<string>([ToolNames.Write, ToolNames.Edit, ToolNames.Artifact]);
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+export type WatchdogTriggerReason = "turn_end" | "cadence";
+
+export interface WatchdogTrigger {
+	reason: WatchdogTriggerReason;
+	/** The turn's coalesced diff, one block per mutated path in first-touch order. */
+	diff: string;
+	/** Paths the turn mutated, in first-touch order. */
+	paths: ReadonlyArray<string>;
+	/** The board's current scope, or null when the session has no task board. */
+	scope: string | null;
+	/** Tool calls seen in this turn when the trigger fired. */
+	toolCalls: number;
+}
+
+/** The live settings view the registration reads on every boundary, so a hot reload lands immediately. */
+export interface WatchdogSettingsView {
+	enabled: boolean;
+	target?: string;
+	cadenceToolCalls?: number;
+}
+
+export interface WatchdogDeps {
+	getSettings: () => Readonly<WatchdogSettingsView>;
+	/** The board's current scope line, or null when there is no board. */
+	getScope?: () => string | null;
+	/**
+	 * Dispatch the watchdog run and deliver whatever it found. Resolves when the
+	 * run has settled; the registration awaits only to know the in-flight slot is
+	 * free again, never to hold the turn.
+	 */
+	run: (trigger: WatchdogTrigger) => Promise<void>;
+	/**
+	 * False on a surface that must never fire the watchdog whatever the setting
+	 * says. Headless and ACP runs pass false: neither has an operator watching a
+	 * transcript, so a notice they cannot read is a worker run spent on nothing.
+	 */
+	firesOnThisSurface?: boolean;
+}
+
+export interface WatchdogRegistration extends MiddlewareHookRegistration {
+	/** Triggers dropped because a watchdog run was already in flight. */
+	droppedTriggers(): number;
+	/** True while a watchdog run is outstanding. */
+	runInFlight(): boolean;
+	/** Resolves once no watchdog run is outstanding. */
+	whenIdle(): Promise<void>;
+}
+
+function stringValue(value: unknown): string | null {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function firstPath(details: Readonly<Record<string, unknown>> | undefined): string | null {
+	const paths = details?.paths;
+	if (!Array.isArray(paths)) return null;
+	for (const entry of paths) {
+		const path = stringValue(entry);
+		if (path !== null) return path;
+	}
+	return null;
+}
+
+/**
+ * Coalesce the per-call diffs of one turn into one diff.
+ *
+ * Per-path last-write-wins, in first-touch order. A turn that edited one file
+ * six times produced six diffs against six different base contents; replaying
+ * all of them tells a reviewer the history of the edit rather than its result,
+ * and the result is what the reviewer is being asked about.
+ */
+export function coalesceTurnDiff(
+	byPath: ReadonlyMap<string, string>,
+	maxBytes: number = WATCHDOG_DIFF_MAX_BYTES,
+): string {
+	const blocks: string[] = [];
+	let index = 0;
+	for (const [path, diff] of byPath) {
+		if (index >= WATCHDOG_PATHS_MAX) {
+			blocks.push(`[${byPath.size - WATCHDOG_PATHS_MAX} more changed path(s) omitted]`);
+			break;
+		}
+		blocks.push(`--- ${path}\n${diff}`);
+		index += 1;
+	}
+	const whole = blocks.join("\n\n");
+	if (Buffer.byteLength(whole, "utf8") <= maxBytes) return whole;
+	const room = Math.max(0, maxBytes - Buffer.byteLength(WATCHDOG_TRUNCATION_MARKER, "utf8"));
+	const buffer = Buffer.from(whole, "utf8");
+	let cut = Math.min(room, buffer.byteLength);
+	while (cut > 0) {
+		const next = buffer[cut];
+		if (next === undefined || (next & 0xc0) !== 0x80) break;
+		cut -= 1;
+	}
+	return `${buffer.subarray(0, cut).toString("utf8")}${WATCHDOG_TRUNCATION_MARKER}`;
+}
+
+/** The bounded, fixed task every watchdog run is given. It never varies with the diff. */
+export const WATCHDOG_TASK =
+	"Review the coalesced diff in the briefing against the scope it names. Report one check per concern: " +
+	"a change outside the stated scope, a change the scope required that the diff does not make, or a defect " +
+	"visible in the diff itself. Run no commands and change nothing.";
+
+/** The briefing body a watchdog run receives. Data, never instructions. */
+export function watchdogBriefing(trigger: WatchdogTrigger): string {
+	const scope = trigger.scope === null ? "(no task board; scope is unstated)" : trigger.scope;
+	const paths = trigger.paths.length === 0 ? "(none)" : trigger.paths.join("\n");
+	return [
+		"## Current scope",
+		scope,
+		"",
+		"## Changed paths",
+		paths,
+		"",
+		"## Coalesced diff for this turn",
+		trigger.diff,
+	].join("\n");
+}
+
+/**
+ * Build the registration. It is hooked on `after_tool` and `turn_end`:
+ * `after_tool` is where the diffs and the tool count come from, and `turn_end`
+ * is the boundary a mutating turn fires on.
+ */
+export function createWatchdogRegistration(deps: WatchdogDeps): WatchdogRegistration {
+	const diffByPath = new Map<string, string>();
+	let toolCalls = 0;
+	let dropped = 0;
+	let inFlight = false;
+	let outstanding: Promise<void> = Promise.resolve();
+
+	const active = (): WatchdogSettingsView | null => {
+		if (deps.firesOnThisSurface === false) return null;
+		let settings: Readonly<WatchdogSettingsView>;
+		try {
+			settings = deps.getSettings();
+		} catch {
+			return null;
+		}
+		return settings.enabled ? settings : null;
+	};
+
+	const resetTurn = (): void => {
+		diffByPath.clear();
+		toolCalls = 0;
+	};
+
+	const fire = (reason: WatchdogTriggerReason): void => {
+		if (diffByPath.size === 0) return;
+		// One run at a time. A watchdog slower than the turns that trigger it must
+		// not queue: a queued review describes a tree that has already moved on,
+		// and a backlog of them would outlive the session. The drop is counted so
+		// a starved cadence and a quiet one stay distinguishable.
+		if (inFlight) {
+			dropped += 1;
+			return;
+		}
+		const trigger: WatchdogTrigger = {
+			reason,
+			diff: coalesceTurnDiff(diffByPath),
+			paths: [...diffByPath.keys()].slice(0, WATCHDOG_PATHS_MAX),
+			scope: scopeNow(),
+			toolCalls,
+		};
+		inFlight = true;
+		// Started synchronously, so the in-flight slot is genuinely taken before
+		// this hook returns. Deferring the start to a microtask would let two
+		// triggers in the same tool batch both find the slot free.
+		let started: Promise<void>;
+		try {
+			started = deps.run(trigger);
+		} catch {
+			inFlight = false;
+			return;
+		}
+		outstanding = started
+			.catch(() => {
+				// A failed watchdog run is not a failed turn. The run's own reporting
+				// path already told the operator whatever it could.
+			})
+			.finally(() => {
+				inFlight = false;
+			});
+	};
+
+	const scopeNow = (): string | null => {
+		try {
+			return deps.getScope?.() ?? null;
+		} catch {
+			return null;
+		}
+	};
+
+	return {
+		id: WATCHDOG_REGISTRATION_ID,
+		description: "review a mutating turn's coalesced diff against the board scope with a read-only verifier run",
+		hooks: ["after_tool", "turn_end"],
+		evaluate(input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> {
+			const settings = active();
+			if (settings === null) {
+				// Still clear turn state so a mid-session disable cannot leave a diff
+				// behind that a later enable would fire on.
+				if (input.hook === "turn_end") resetTurn();
+				return NO_EFFECTS;
+			}
+			if (input.hook === "after_tool") {
+				toolCalls += 1;
+				recordMutation(input);
+				const cadence = settings.cadenceToolCalls;
+				// Mid-turn cadence keeps accumulating: turn end still reviews the whole
+				// turn, not just what landed after the last cadence firing.
+				if (cadence !== undefined && cadence >= 1 && toolCalls % cadence === 0) fire("cadence");
+				return NO_EFFECTS;
+			}
+			if (input.hook !== "turn_end") return NO_EFFECTS;
+			// A turn with no file mutations never fires. A middleware continuation
+			// re-evaluates turn_end with the accumulator already cleared, so it
+			// cannot fire a second run for the same change either.
+			fire("turn_end");
+			resetTurn();
+			return NO_EFFECTS;
+		},
+		droppedTriggers: () => dropped,
+		runInFlight: () => inFlight,
+		whenIdle: () => outstanding,
+	};
+
+	function recordMutation(input: MiddlewareHookInput): void {
+		if (input.metadata?.resultKind !== "ok") return;
+		if (input.toolName === undefined || !MUTATING_TOOL_NAMES.has(input.toolName)) return;
+		const diff = stringValue(input.toolResultDetails?.diff);
+		if (diff === null) return;
+		// Map.set on an existing key keeps its insertion position, so the newest
+		// diff for a path wins while the path keeps its first-touch order.
+		diffByPath.set(firstPath(input.toolResultDetails) ?? input.toolName, diff);
+	}
+}

package/src/domains/observability/contract.ts

@@ -1,7 +1,8 @@
+import type { ResponseModelIdObservationCounts } from "../../core/response-model-id.js";
 import type { TargetStatus } from "../providers/contract.js";
 import type { CostProvenance } from "../providers/index.js";
 import type { AccountabilitySummary } from "./accountability.js";
-import type { CostAggregate, CostEntry, UsageBreakdown } from "./cost.js";
+import type { CostAggregate, CostEntry, CostEntryLabel, UsageBreakdown } from "./cost.js";
 import type { MetricsView } from "./metrics.js";
 import type { TelemetrySnapshot } from "./telemetry.js";
 import type { SessionTurnTrace } from "./trace-store.js";
@@ -132,11 +133,17 @@ export interface ObservabilityContract {
 	 */
 	recordTokens(
 		providerId: string,
-		modelId: string,
+		attributedModelId: string,
 		tokens: number,
 		costUsd?: number,
 		breakdown?: Partial<UsageBreakdown>,
 		costProvenance?: CostProvenance,
+		modelIdFacts?: {
+			requestedModelIds: ReadonlyArray<string>;
+			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
+		},
+		/** Marks a priced call that was not an ordinary turn, such as a `/btw` side question. */
+		label?: CostEntryLabel,
 	): void;
 	/** Record final output token throughput for one completed assistant stream. */
 	recordTokenThroughput(snapshot: TokenThroughputSnapshot): void;

package/src/domains/observability/cost.ts

@@ -11,6 +11,7 @@
  * footer consumes the session sum through `ObservabilityContract.sessionTokens()`.
  */
 
+import type { ResponseModelIdObservationCounts } from "../../core/response-model-id.js";
 import { type CostProvenance, normalizeCostProvenance } from "../providers/index.js";
 
 export interface CostAmount {
@@ -110,9 +111,18 @@ export interface UsageBreakdown {
 	apiCalls?: number;
 }
 
+/**
+ * What produced a priced call, when it was not an ordinary turn. `/cost` and
+ * 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 interface CostEntry {
 	providerId: string;
-	modelId: string;
+	attributedModelId: string;
+	requestedModelIds: string[];
+	responseModelIdObservationCounts: ResponseModelIdObservationCounts;
 	tokens: number;
 	usd: number;
 	provenance: CostProvenance;
@@ -122,16 +132,23 @@ export interface CostEntry {
 	cacheWrite: number;
 	reasoningTokens: number;
 	apiCalls?: number;
+	/** Absent on an ordinary turn's call. */
+	label?: CostEntryLabel;
 }
 
 export interface CostTracker {
 	accumulate(
 		providerId: string,
-		modelId: string,
+		attributedModelId: string,
 		tokens: number,
 		usd?: number,
 		breakdown?: Partial<UsageBreakdown>,
 		provenance?: CostProvenance,
+		modelIdFacts?: {
+			requestedModelIds: ReadonlyArray<string>;
+			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
+		},
+		label?: CostEntryLabel,
 	): number;
 	sessionTotal(): number;
 	sessionCost(): CostAggregate;
@@ -149,7 +166,7 @@ export function createCostTracker(): CostTracker {
 	let total = 0;
 	const totals = emptyBreakdown();
 	return {
-		accumulate(providerId, modelId, tokens, usd, breakdown, costProvenance) {
+		accumulate(providerId, attributedModelId, tokens, usd, breakdown, costProvenance, modelIdFacts, label) {
 			const resolvedUsd = usd ?? 0;
 			const provenance = normalizeCostProvenance(costProvenance);
 			const input = breakdown?.input ?? 0;
@@ -160,7 +177,16 @@ export function createCostTracker(): CostTracker {
 			const apiCalls = breakdown?.apiCalls;
 			log.push({
 				providerId,
-				modelId,
+				attributedModelId,
+				requestedModelIds: [...(modelIdFacts?.requestedModelIds ?? [attributedModelId])],
+				responseModelIdObservationCounts: modelIdFacts
+					? { ...modelIdFacts.responseModelIdObservationCounts }
+					: {
+							reportedCalls: 0,
+							notReportedCalls: 0,
+							notObservedCalls: apiCalls ?? 1,
+							legacyDifferenceOnlyCalls: 0,
+						},
 				tokens,
 				usd: resolvedUsd,
 				provenance,
@@ -170,6 +196,7 @@ export function createCostTracker(): CostTracker {
 				cacheWrite,
 				reasoningTokens,
 				...(apiCalls !== undefined ? { apiCalls } : {}),
+				...(label !== undefined ? { label } : {}),
 			});
 			total += resolvedUsd;
 			totals.input += input;

package/src/domains/observability/extension.ts

@@ -259,9 +259,9 @@ export function createObservabilityBundle(
 			latestThroughput = null;
 			projection.refresh();
 		},
-		recordTokens(providerId, modelId, tokens, costUsd, breakdown, costProvenance) {
+		recordTokens(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts, label) {
 			telemetry.record("counter", "tokens.total", tokens);
-			cost.accumulate(providerId, modelId, tokens, costUsd, breakdown, costProvenance);
+			cost.accumulate(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts, label);
 			projection.refresh();
 		},
 		recordSessionTurn(sessionTurn) {

package/src/domains/observability/index.ts

@@ -30,6 +30,7 @@ export {
 	type CostAggregate,
 	type CostAmount,
 	type CostEntry,
+	type CostEntryLabel,
 	costAggregateForAmount,
 	costWasMeasured,
 	emptyCostAggregate,
@@ -40,6 +41,15 @@ export type { EvidenceIndexRow } from "./evidence-index.js";
 export { EVIDENCE_INDEX_FILE, MAX_EVIDENCE_INDEX_ROWS, readEvidenceIndex } from "./evidence-index.js";
 export { ObservabilityManifest } from "./manifest.js";
 export type { MetricsView } from "./metrics.js";
+export type { OutOfTurnUsage, OutOfTurnUsageReadResult, OutOfTurnUsageRow } from "./out-of-turn-usage.js";
+export {
+	appendOutOfTurnUsageRow,
+	MAX_OUT_OF_TURN_USAGE_ROWS,
+	OUT_OF_TURN_USAGE_DIR,
+	OUT_OF_TURN_USAGE_FILE,
+	outOfTurnUsagePath,
+	readOutOfTurnUsageRows,
+} from "./out-of-turn-usage.js";
 export type { ObservabilityProjection, ProjectionReadModel } from "./projection.js";
 export {
 	createObservabilityProjection,

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

@@ -0,0 +1,223 @@
+/**
+ * Durable record of the model calls that were billed beside a session rather
+ * than inside it: `/btw` side questions and `/handoff` extraction rounds.
+ *
+ * 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
+ * orient themselves must not become context those workers inherit, and
+ * `src/interactive/side-question.ts` states that promise as a contract. The
+ * money was still spent, though, and until this store existed the only record
+ * of it was the in-process cost tracker: `/cost` showed it for as long as the
+ * process lived, and `clio-coder usage report`, which reads the archive on
+ * disk, could not see it at all.
+ *
+ * So the spend gets its own file. One JSON line per priced out-of-turn call
+ * under `<stateDir>/usage/out-of-turn.jsonl`, carrying the label, the session
+ * it sat beside, the repo identity the session ledger is filed under (so
+ * `usage report --repo` filters these rows the same way it filters ledgers),
+ * the target and attributed model, and the provider-reported usage.
+ *
+ * Writes follow the audit-row conventions: one append-mode `writeSync` per
+ * row, so a line lands whole even with concurrent writers, and a failure is
+ * logged to stderr rather than thrown back into the interactive path. The file
+ * is a bounded ring: once it grows past {@link MAX_OUT_OF_TURN_USAGE_ROWS} the
+ * newest rows are rewritten atomically under the shared state-file lock and
+ * the oldest are dropped. Reads are tolerant; a malformed line is reported and
+ * skipped, never fatal.
+ */
+
+import { closeSync, 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";
+import type { CostProvenance } from "../providers/index.js";
+import type { CostEntryLabel } from "./cost.js";
+
+/** Directory under the state dir that holds cross-session usage side-cars. */
+export const OUT_OF_TURN_USAGE_DIR = "usage";
+
+/** Filename of the out-of-turn usage ledger inside {@link OUT_OF_TURN_USAGE_DIR}. */
+export const OUT_OF_TURN_USAGE_FILE = "out-of-turn.jsonl";
+
+/** Cap on retained rows. Matches the dispatch runs ledger and evidence index default. */
+export const MAX_OUT_OF_TURN_USAGE_ROWS = 1000;
+
+/**
+ * How many appends this process makes between bound checks. Counting rows means
+ * reading the file, and an out-of-turn round is rare enough that paying that on
+ * the first append of a process and periodically after it keeps the ring bounded
+ * without reading a megabyte per side question.
+ */
+const BOUND_CHECK_INTERVAL = 64;
+
+/** 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;
+	costProvenance: CostProvenance;
+}
+
+/** One priced model call that was billed beside a session rather than inside it. */
+export interface OutOfTurnUsageRow {
+	label: CostEntryLabel;
+	/** Session the round sat beside, or null when no session was current. */
+	sessionId: string | null;
+	/** The cwd hash the session ledger is filed under, so `--repo` can filter these rows. */
+	repoIdentity: string | null;
+	/** ISO-8601 timestamp of the call. */
+	timestamp: string;
+	/** Target id the round ran against. */
+	target: string;
+	attributedModelId: string;
+	usage: OutOfTurnUsage;
+}
+
+export interface OutOfTurnUsageReadResult {
+	rows: OutOfTurnUsageRow[];
+	errors: string[];
+}
+
+export function outOfTurnUsagePath(stateDir: string): string {
+	return join(stateDir, OUT_OF_TURN_USAGE_DIR, OUT_OF_TURN_USAGE_FILE);
+}
+
+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.
+ */
+export function appendOutOfTurnUsageRow(stateDir: string, row: OutOfTurnUsageRow): void {
+	const path = outOfTurnUsagePath(stateDir);
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		const fd = openSync(path, "a");
+		try {
+			writeSync(fd, `${JSON.stringify(row)}\n`);
+		} finally {
+			closeSync(fd);
+		}
+	} catch (error) {
+		process.stderr.write(`[clio:usage] out-of-turn usage row not written: ${messageOf(error)}\n`);
+		return;
+	}
+	appendsSinceBoundCheck += 1;
+	if (appendsSinceBoundCheck < BOUND_CHECK_INTERVAL) return;
+	appendsSinceBoundCheck = 0;
+	try {
+		boundOutOfTurnUsageFile(path);
+	} catch (error) {
+		process.stderr.write(`[clio:usage] out-of-turn usage ring not bounded: ${messageOf(error)}\n`);
+	}
+}
+
+/**
+ * Rewrite the file down to the newest {@link MAX_OUT_OF_TURN_USAGE_ROWS} lines
+ * when it has grown past the cap. Held under the state-file lock so a concurrent
+ * appender cannot lose a row into the rename, and written through
+ * `safeResourceWrite` so a crash mid-rewrite leaves the previous file intact.
+ */
+function boundOutOfTurnUsageFile(path: string): void {
+	withStateFileLockSync(path, () => {
+		let raw: string;
+		try {
+			raw = readFileSync(path, "utf8");
+		} catch {
+			return;
+		}
+		const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+		if (lines.length <= MAX_OUT_OF_TURN_USAGE_ROWS) return;
+		const kept = lines.slice(-MAX_OUT_OF_TURN_USAGE_ROWS);
+		safeResourceWrite(path, `${kept.join("\n")}\n`, { encoding: "utf8" });
+	});
+}
+
+/**
+ * Read every recorded out-of-turn call. A missing file is an empty read rather
+ * than an error: a machine where nobody has ever run `/btw` has nothing to
+ * report, and that is a different thing from a store that failed to open.
+ */
+export function readOutOfTurnUsageRows(stateDir: string): OutOfTurnUsageReadResult {
+	const path = outOfTurnUsagePath(stateDir);
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT" || err.code === "ENOTDIR") return { rows: [], errors: [] };
+		return { rows: [], errors: [`out-of-turn usage store unreadable: ${messageOf(error)}`] };
+	}
+	const rows: OutOfTurnUsageRow[] = [];
+	const errors: string[] = [];
+	const lines = raw.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (line === undefined || line.trim().length === 0) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line) as unknown;
+		} catch (error) {
+			errors.push(`${path}:${index + 1}: invalid JSON: ${messageOf(error)}`);
+			continue;
+		}
+		const row = asOutOfTurnUsageRow(parsed);
+		if (row === null) {
+			errors.push(`${path}:${index + 1}: not an out-of-turn usage row`);
+			continue;
+		}
+		rows.push(row);
+	}
+	return { rows, errors };
+}
+
+function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
+	if (!isRecord(value)) return null;
+	const label = value.label;
+	if (label !== "side-question" && label !== "handoff") return null;
+	if (typeof value.timestamp !== "string" || value.timestamp.length === 0) return null;
+	if (!isRecord(value.usage)) return null;
+	const usage = value.usage;
+	return {
+		label,
+		sessionId: typeof value.sessionId === "string" ? value.sessionId : null,
+		repoIdentity: typeof value.repoIdentity === "string" ? value.repoIdentity : null,
+		timestamp: value.timestamp,
+		target: typeof value.target === "string" && value.target.length > 0 ? value.target : "unknown",
+		attributedModelId:
+			typeof value.attributedModelId === "string" && value.attributedModelId.length > 0
+				? 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),
+			costProvenance: asCostProvenance(usage.costProvenance),
+		},
+	};
+}
+
+function asCostProvenance(value: unknown): CostProvenance {
+	return value === "known" || value === "known_free" || value === "estimated" ? value : "unknown";
+}
+
+function numberOr0(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/domains/providers/index.ts

@@ -32,6 +32,7 @@ export type { ModelCapabilityPatchTarget } from "./model-capabilities.js";
 export { applyModelCapabilityPatch, resolveModelCapabilities } from "./model-capabilities.js";
 export {
 	canonicalizeWireModelId,
+	contextSlotsForModel,
 	hasLiveModelCatalog,
 	loadedContextWindowForModel,
 	type ModelResidency,
@@ -96,6 +97,7 @@ export {
 	refineRuntimeTargetWithModelHints,
 	resolveRuntimeTarget,
 	runtimeResolutionWarnings,
+	runtimeResolutionWarningsBesideThinkingNotice,
 	runtimeTargetSnapshot,
 } from "./runtime-resolution.js";
 export {
@@ -126,6 +128,7 @@ export {
 	EMPTY_CAPABILITIES,
 	VALID_THINKING_LEVELS,
 } from "./types/capability-flags.js";
+export { type ContextWindowSlots, formatContextWindowSlots } from "./types/context-window-slots.js";
 export { type CostProvenance, normalizeCostProvenance } from "./types/cost-provenance.js";
 export type { KnowledgeBase, KnowledgeBaseEntry, KnowledgeBaseHit } from "./types/knowledge-base.js";
 export type {