@iowarp/clio-coder 0.4.7 → 0.4.8

package/src/domains/dispatch/extension.ts

@@ -21,7 +21,7 @@ import { BusChannels, type DispatchCompletedPayload, type DispatchRunIdentity }
 import { DEFAULT_SETTINGS, type DelegationToolGovernance } from "../../core/defaults.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
 import { gatewayRoutingObservationFromRecord } from "../../core/gateway-routing.js";
-import { GUARDRAIL_DEFAULTS } from "../../core/guardrails.js";
+import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../../core/guardrails.js";
 import { readClioVersion, readPiMonoVersion } from "../../core/package-root.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { protectedResidencyModels } from "../../core/residency-protection.js";
@@ -325,7 +325,10 @@ interface RunTokenMeter {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
+	/** Native calls are priced individually by the SDK, including cache TTLs and context tiers. */
+	costUsd?: number;
 }
 
 interface ActiveRun {
@@ -458,6 +461,7 @@ function sealRouteDecision(draft: RunReceiptDraft, decision: RouteDecisionV1): R
 export const UNKNOWN_PRICING_ADMISSION_ESTIMATE_USD = 1;
 
 function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["rates"]): number {
+	if (meter.costUsd !== undefined) return meter.costUsd;
 	if (pricing === null) return 0;
 	return (
 		(meter.inputTokens * pricing.input +
@@ -468,6 +472,39 @@ function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["
 	);
 }
 
+function accumulateNativeUsage(
+	meter: RunTokenMeter,
+	usage: Record<string, unknown>,
+	pricing: EffectivePricing["rates"],
+): void {
+	const count = (value: unknown): number =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+	const call: RunTokenMeter = {
+		inputTokens: count(usage.input),
+		outputTokens: count(usage.output),
+		cacheReadTokens: count(usage.cacheRead),
+		cacheWriteTokens: count(usage.cacheWrite),
+		reasoningTokens: extractReasoningTokenCount(usage),
+	};
+	const reported = isRecord(usage.cost) ? usage.cost.total : undefined;
+	// An SDK total is already priced with per-call tiers, service tier
+	// and cache-write lifetime. Never reprice it from an aggregate token count.
+	// Retain the target-rate fallback only for workers that omit calculated
+	// cost. Zero remains zero; its provenance still comes from the target.
+	const callCost =
+		typeof reported === "number" && Number.isFinite(reported) && reported >= 0
+			? reported
+			: calculateUsageCostUsd(call, pricing);
+	meter.costUsd = (meter.costUsd ?? 0) + callCost;
+	meter.inputTokens += call.inputTokens;
+	meter.outputTokens += call.outputTokens;
+	meter.cacheReadTokens += call.cacheReadTokens;
+	meter.cacheWriteTokens += call.cacheWriteTokens;
+	if (typeof usage.cacheWrite1h === "number" && usage.cacheWrite1h >= 0 && usage.cacheWrite1h <= call.cacheWriteTokens)
+		meter.cacheWrite1hTokens = (meter.cacheWrite1hTokens ?? 0) + usage.cacheWrite1h;
+	meter.reasoningTokens += call.reasoningTokens;
+}
+
 /**
  * Output-token figure the admission estimate prices a route against. Settings
  * always carry `defaults.maxTokens`; the fallback covers the callers that
@@ -3952,7 +3989,13 @@ export function createDispatchBundle(
 		}
 		timing.workerSpawnedAt = new Date(now()).toISOString();
 
-		const tokenMeter = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+		const tokenMeter: RunTokenMeter = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			reasoningTokens: 0,
+		};
 		const safetyDecisionCounts = { allowed: 0, blocked: 0, permissionRequested: 0 };
 		const blockedAttempts: SafetyBlockedAttempt[] = [];
 		const toolStats = new Map<string, ToolCallStat>();
@@ -4341,6 +4384,7 @@ export function createDispatchBundle(
 				outputTokenCount: tokenMeter.outputTokens,
 				cacheReadTokenCount: tokenMeter.cacheReadTokens,
 				cacheWriteTokenCount: tokenMeter.cacheWriteTokens,
+				...(tokenMeter.cacheWrite1hTokens === undefined ? {} : { cacheWrite1hTokenCount: tokenMeter.cacheWrite1hTokens }),
 				reasoningTokenCount: tokenMeter.reasoningTokens,
 				...(upstreamResponses.length > 0 ? { upstreamResponses: [...upstreamResponses] } : {}),
 				...(capturedOutput !== undefined ? { output: capturedOutput } : {}),
@@ -4427,6 +4471,7 @@ export function createDispatchBundle(
 				outputTokenCount: receipt.outputTokenCount ?? 0,
 				cacheReadTokenCount: receipt.cacheReadTokenCount ?? 0,
 				cacheWriteTokenCount: receipt.cacheWriteTokenCount ?? 0,
+				...(receipt.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1hTokenCount: receipt.cacheWrite1hTokenCount }),
 				reasoningTokenCount: receipt.reasoningTokenCount ?? 0,
 				staticShellHash: receipt.staticShellHash ?? null,
 				sessionShellHash: receipt.sessionShellHash ?? null,
@@ -4552,6 +4597,9 @@ export function createDispatchBundle(
 					dynamicHash: receiptDraft.dynamicHash ?? null,
 					cacheReadTokenCount: receiptDraft.cacheReadTokenCount ?? 0,
 					cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount ?? 0,
+					...(receiptDraft.cacheWrite1hTokenCount === undefined
+						? {}
+						: { cacheWrite1hTokenCount: receiptDraft.cacheWrite1hTokenCount }),
 					reasoningTokenCount: receiptDraft.reasoningTokenCount ?? 0,
 					heartbeatAt: heartbeatIso(acp.heartbeatAt),
 				};
@@ -4838,7 +4886,13 @@ export function createDispatchBundle(
 				throw error;
 			}
 		})();
-		const tokenMeter = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+		const tokenMeter: RunTokenMeter = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			reasoningTokens: 0,
+		};
 		const safetyDecisionCounts = { allowed: 0, blocked: 0, permissionRequested: 0 };
 		const escalationCounts = { requested: 0, approved: 0, denied: 0, timedOut: 0 };
 		const blockedAttempts: SafetyBlockedAttempt[] = [];
@@ -5118,11 +5172,7 @@ export function createDispatchBundle(
 			}
 			if (event.type === "message_end" && event.message?.role === "assistant" && isRecord(event.message.usage)) {
 				const u = event.message.usage;
-				tokenMeter.inputTokens += typeof u.input === "number" ? u.input : 0;
-				tokenMeter.outputTokens += typeof u.output === "number" ? u.output : 0;
-				tokenMeter.cacheReadTokens += typeof u.cacheRead === "number" ? u.cacheRead : 0;
-				tokenMeter.cacheWriteTokens += typeof u.cacheWrite === "number" ? u.cacheWrite : 0;
-				tokenMeter.reasoningTokens += extractReasoningTokenCount(u);
+				accumulateNativeUsage(tokenMeter, u, lifecycle.target.effectivePricing.rates);
 				const requestedModelId = readStringOrNull(event.message.model);
 				const responseModelIdObservation = responseModelIdObservationFromRecord(event.message, "not-observed");
 				const differingResponseModelId = readStringOrNull(event.message.responseModel);
@@ -5552,11 +5602,15 @@ export function createDispatchBundle(
 				outputTokenCount: tokenMeter.outputTokens,
 				cacheReadTokenCount: tokenMeter.cacheReadTokens,
 				cacheWriteTokenCount: tokenMeter.cacheWriteTokens,
+				...(tokenMeter.cacheWrite1hTokens === undefined ? {} : { cacheWrite1hTokenCount: tokenMeter.cacheWrite1hTokens }),
 				reasoningTokenCount: tokenMeter.reasoningTokens,
 				...(upstreamResponses.length > 0 ? { upstreamResponses: [...upstreamResponses] } : {}),
 				...(capturedOutput !== undefined ? { output: capturedOutput } : {}),
 				costUsd,
-				costProvenance: lifecycle.target.effectivePricing.provenance,
+				costProvenance:
+					lifecycle.target.effectivePricing.provenance === "unknown" && costUsd > 0
+						? "estimated"
+						: lifecycle.target.effectivePricing.provenance,
 				compiledPromptHash: lifecycle.compiledPromptHash,
 				staticCompositionHash: lifecycle.staticCompositionHash,
 				staticShellHash: lifecycle.staticCompositionHash,
@@ -5646,6 +5700,7 @@ export function createDispatchBundle(
 				outputTokenCount: receipt.outputTokenCount ?? 0,
 				cacheReadTokenCount: receipt.cacheReadTokenCount ?? 0,
 				cacheWriteTokenCount: receipt.cacheWriteTokenCount ?? 0,
+				...(receipt.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1hTokenCount: receipt.cacheWrite1hTokenCount }),
 				reasoningTokenCount: receipt.reasoningTokenCount ?? 0,
 				staticShellHash: receipt.staticShellHash ?? null,
 				sessionShellHash: receipt.sessionShellHash ?? null,
@@ -5891,6 +5946,9 @@ export function createDispatchBundle(
 					...(receiptDraft.cacheReadTokenCount !== undefined
 						? { cacheReadTokenCount: receiptDraft.cacheReadTokenCount }
 						: {}),
+					...(receiptDraft.cacheWrite1hTokenCount === undefined
+						? {}
+						: { cacheWrite1hTokenCount: receiptDraft.cacheWrite1hTokenCount }),
 					...(receiptDraft.cacheWriteTokenCount !== undefined
 						? { cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount }
 						: {}),
@@ -6672,7 +6730,11 @@ export function createDispatchBundle(
 			// No in-memory executor survives a process restart, so every active
 			// side-store lease from an earlier bundle is orphaned and must expire.
 			cleanupDispatchReservations({ startup: true, nowMs: now() });
-			ledger = openLedger();
+			ledger = openLedger({
+				get maxRuns() {
+					return getEffectiveSettings()?.fleet?.history?.maxRuns ?? resolveGuardrail("maxDispatchRuns");
+				},
+			});
 			// Symphony P10: restart recovery from durable artifacts. Adopt
 			// receipts whose ledger rows were lost to a crash between
 			// recordReceipt() and persist(); quarantine tampered ones.
@@ -6802,6 +6864,7 @@ export function createDispatchBundle(
 			const meter = run.meter;
 			const totalTokens = meter.inputTokens + meter.outputTokens + meter.cacheReadTokens + meter.cacheWriteTokens;
 			const costUsd = calculateUsageCostUsd(meter, run.pricing);
+			const costProvenance = run.costProvenance === "unknown" && costUsd > 0 ? "estimated" : run.costProvenance;
 			const startedMs = Date.parse(run.startedAt);
 			const elapsedMs = Number.isFinite(startedMs) ? Math.max(0, tickNow - startedMs) : 0;
 			const timing = deriveRunPhaseDurations(run.timing, run.startedAt, new Date(tickNow).toISOString());
@@ -6819,14 +6882,14 @@ export function createDispatchBundle(
 				timing,
 				tokens: { input: meter.inputTokens, output: meter.outputTokens, total: totalTokens },
 				costUsd,
-				costProvenance: run.costProvenance,
+				costProvenance,
 				node: run.node !== null ? { ...run.node } : null,
 			});
 			totals.inputTokens += meter.inputTokens;
 			totals.outputTokens += meter.outputTokens;
 			totals.totalTokens += totalTokens;
 			totals.costUsd += costUsd;
-			costAmounts.push({ usd: costUsd, provenance: run.costProvenance });
+			costAmounts.push({ usd: costUsd, provenance: costProvenance });
 			totals.runtimeSeconds += elapsedMs / 1000;
 		}
 		const retrying = [...retryQueue.values()].map((entry) => ({

package/src/domains/dispatch/index.ts

@@ -22,6 +22,7 @@ export type {
 	DispatchAssignment,
 } from "./assignment.js";
 export type { AssignmentVerdictOwner, DurableAssignmentRecord } from "./assignment-store.js";
+export { endpointCapacityUsage } from "./capacity-lease.js";
 export type { CodeStepOutcome, CodeStepRecord, CodeStepRunInput } from "./code-step.js";
 export {
 	canonicalCodeReport,

package/src/domains/dispatch/orphan-recovery.ts

@@ -78,6 +78,7 @@ function envelopeFromReceipt(receipt: RunReceipt, status: RunStatus, receiptPath
 	};
 	if (receipt.cacheReadTokenCount !== undefined) envelope.cacheReadTokenCount = receipt.cacheReadTokenCount;
 	if (receipt.cacheWriteTokenCount !== undefined) envelope.cacheWriteTokenCount = receipt.cacheWriteTokenCount;
+	if (receipt.cacheWrite1hTokenCount !== undefined) envelope.cacheWrite1hTokenCount = receipt.cacheWrite1hTokenCount;
 	if (receipt.reasoningTokenCount !== undefined) envelope.reasoningTokenCount = receipt.reasoningTokenCount;
 	if (receipt.inputTokenCount !== undefined) envelope.inputTokenCount = receipt.inputTokenCount;
 	if (receipt.outputTokenCount !== undefined) envelope.outputTokenCount = receipt.outputTokenCount;

package/src/domains/dispatch/receipt-integrity.ts

@@ -114,6 +114,7 @@ export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
 	outputTokenCount: true,
 	cacheReadTokenCount: true,
 	cacheWriteTokenCount: true,
+	cacheWrite1hTokenCount: true,
 	reasoningTokenCount: true,
 	upstreamResponses: true,
 	output: true,
@@ -211,6 +212,7 @@ function ledgerDigestFields(envelope: RunEnvelope): Record<string, unknown> {
 		tokenCount: envelope.tokenCount,
 		cacheReadTokenCount: envelope.cacheReadTokenCount,
 		cacheWriteTokenCount: envelope.cacheWriteTokenCount,
+		cacheWrite1hTokenCount: envelope.cacheWrite1hTokenCount,
 		reasoningTokenCount: envelope.reasoningTokenCount,
 		staticShellHash: envelope.staticShellHash,
 		sessionShellHash: envelope.sessionShellHash,
@@ -366,6 +368,7 @@ function firstLedgerMismatch(receipt: RunReceipt, envelope: RunEnvelope): string
 		["tokenCount", receipt.tokenCount, envelope.tokenCount],
 		["cacheReadTokenCount", receipt.cacheReadTokenCount ?? 0, envelope.cacheReadTokenCount ?? 0],
 		["cacheWriteTokenCount", receipt.cacheWriteTokenCount ?? 0, envelope.cacheWriteTokenCount ?? 0],
+		["cacheWrite1hTokenCount", receipt.cacheWrite1hTokenCount ?? 0, envelope.cacheWrite1hTokenCount ?? 0],
 		["reasoningTokenCount", receipt.reasoningTokenCount ?? 0, envelope.reasoningTokenCount ?? 0],
 		["staticShellHash", receipt.staticShellHash ?? null, envelope.staticShellHash ?? null],
 		["sessionShellHash", receipt.sessionShellHash ?? null, envelope.sessionShellHash ?? null],

package/src/domains/dispatch/state.ts

@@ -239,7 +239,6 @@ function capRuns(all: RunEnvelope[], maxRuns: number): RunEnvelope[] {
 }
 
 export function openLedger(opts?: LedgerOptions): Ledger {
-	const maxRuns = resolveMaxRuns(opts?.maxRuns);
 	let runs: RunEnvelope[] = readRuns();
 	// Ids this process has written since the last successful persist. See
 	// mergeRunsById: this is what separates our writes from a sibling's rows we
@@ -369,7 +368,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 				if (stateRootRemoved()) return;
 				const diskRuns = readRuns();
 				const merged = mergeRunsById(diskRuns, runs, dirty);
-				const capped = capRuns(merged, maxRuns);
+				const capped = capRuns(merged, resolveMaxRuns(opts?.maxRuns));
 				runs = capped;
 				atomicWrite(target, JSON.stringify(capped, null, 2));
 				// A run that left the ring has no ledger row to view any more, so its

package/src/domains/dispatch/types.ts

@@ -504,6 +504,7 @@ export interface RunEnvelope {
 	reasoningTokenCount?: number;
 	cacheReadTokenCount?: number;
 	cacheWriteTokenCount?: number;
+	cacheWrite1hTokenCount?: number;
 	staticShellHash?: string | null;
 	sessionShellHash?: string | null;
 	dynamicHash?: string | null;
@@ -872,6 +873,7 @@ export interface RunReceipt {
 	outputTokenCount?: number;
 	cacheReadTokenCount?: number;
 	cacheWriteTokenCount?: number;
+	cacheWrite1hTokenCount?: number;
 	reasoningTokenCount?: number;
 	upstreamResponses?: RunReceiptUpstreamResponse[];
 	/** Bounded final/partial assistant output; absent when none was captured. */

package/src/domains/eval/metrics/tracked.ts

@@ -42,6 +42,7 @@ export interface BuildEvalTrackedMetricsInput {
 }
 
 interface AssistantCall {
+	turnId: string;
 	timestamp: string | null;
 	payload: Record<string, unknown>;
 	promptCache: Record<string, unknown> | null;
@@ -175,7 +176,7 @@ export function buildEvalTrackedMetrics(input: BuildEvalTrackedMetricsInput): Ev
 			receiptToolErrors === undefined
 				? { value: ledgerToolErrors, source: "ledger" }
 				: { value: receiptToolErrors, source: "receipt" },
-		ttftMsFirstCall: firstCallTtft(calls),
+		ttftMsFirstCall: firstCallTtft(calls, input.ledgerEntries),
 		wallClockMs: wallClockMetric(input.receipt, input.fallbackWallClockMs),
 		contextTokensAtEnd: contextTokensAtEnd(calls, compactionEntries),
 		compactions: { value: compactionEntries.length, source: "ledger" },
@@ -210,6 +211,7 @@ function assistantCalls(entries: ReadonlyArray<SessionEntry>): AssistantCall[] {
 		if (promptCache === null && timing === null && usage === null) return [];
 		return [
 			{
+				turnId: entry.turnId,
 				timestamp: entry.payload.timestampEstimated === true ? null : entry.timestamp,
 				payload: entry.payload,
 				promptCache,
@@ -279,7 +281,24 @@ function reasoningMetric(
 	return measured ? { value: total, source: "ledger" } : { value: null, source: "estimated" };
 }
 
-function firstCallTtft(calls: ReadonlyArray<AssistantCall>): EvalSourcedNullableNumber {
+function firstCallTtft(
+	calls: ReadonlyArray<AssistantCall>,
+	entries: ReadonlyArray<SessionEntry>,
+): EvalSourcedNullableNumber {
+	// Parent links are causal evidence; wall-clock corrections must not promote
+	// a later call in the same session. Compare timestamps only across roots.
+	const parents = new Map(entries.map((entry) => [entry.turnId, entry.parentTurnId]));
+	const callIds = new Set(calls.map((call) => call.turnId));
+	const hasEarlierCall = (call: AssistantCall): boolean => {
+		const visited = new Set<string>([call.turnId]);
+		let parent = parents.get(call.turnId);
+		while (parent != null && !visited.has(parent)) {
+			if (callIds.has(parent)) return true;
+			visited.add(parent);
+			parent = parents.get(parent);
+		}
+		return false;
+	};
 	// Session directories are read by name, not by call time. Select without
 	// reordering the evidence or borrowing a later call's available timing.
 	let first: AssistantCall | undefined;
@@ -288,6 +307,7 @@ function firstCallTtft(calls: ReadonlyArray<AssistantCall>): EvalSourcedNullable
 		if (call.timestamp === null) return { value: null, source: "estimated" };
 		const at = Date.parse(call.timestamp);
 		if (!Number.isFinite(at)) return { value: null, source: "estimated" };
+		if (hasEarlierCall(call)) continue;
 		if (at < firstAt) {
 			first = call;
 			firstAt = at;

package/src/domains/extensions/operator-runtime.ts

@@ -297,7 +297,9 @@ export class OperatorExtensionRuntime {
 				message: `operator generation ${next}: ${ready} ready, ${degraded} degraded; tool schemas remain frozen${hooks ? `; hooks/snapshot generation ${hooks.generation}` : ""}`,
 			};
 		} catch (error) {
-			for (const process of staged.values()) this.retire(process, "reload-rejected");
+			for (const process of new Set([...this.processes.values(), ...staged.values()])) {
+				this.retire(process, "reload-rejected");
+			}
 			this.processes.clear();
 			result = {
 				status: this.generation === next ? "committed" : "rejected",

package/src/domains/middleware/hooks.ts

@@ -10,8 +10,8 @@
  *
  * There is no arbitrary script execution: `command` takes an argv array and is
  * run without a shell, so there is no string to inject into. Hooks never
- * replace the safety policy. They register after the guard hooks and can only
- * add effects (including requesting `block_tool`); the durable safety contract
+ * replace the safety policy. They can only add effects (including requesting
+ * `block_tool`); the durable safety contract
  * still classifies every tool call independently and a hook cannot grant a
  * permission safety would deny.
  *

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

@@ -27,6 +27,7 @@ export interface BackgroundMemoryStepUsage {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoning: number;
 	totalTokens: number;
 	costUsd: number;
@@ -83,6 +84,7 @@ export function backgroundMemoryUsageRow(
 			output: usage.output,
 			cacheRead: usage.cacheRead,
 			cacheWrite: usage.cacheWrite,
+			...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: usage.cacheWrite1h }),
 			reasoning: usage.reasoning,
 			totalTokens: usage.totalTokens,
 			costUsd: usage.costUsd,
@@ -122,6 +124,7 @@ export function recordBackgroundMemoryStep(input: RecordBackgroundMemoryStepInpu
 			output: input.usage.output,
 			cacheRead: input.usage.cacheRead,
 			cacheWrite: input.usage.cacheWrite,
+			...(input.usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: input.usage.cacheWrite1h }),
 			reasoningTokens: input.usage.reasoning,
 			totalTokens: input.usage.totalTokens,
 			apiCalls: 1,

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

@@ -29,6 +29,7 @@ function observedUsage(call: CompactionCallObservation): OutOfTurnUsage {
 		output: reading(raw.output),
 		cacheRead: reading(raw.cacheRead),
 		cacheWrite: reading(raw.cacheWrite),
+		...(raw.cacheWrite1h === undefined ? {} : { cacheWrite1h: reading(raw.cacheWrite1h) }),
 		reasoning: reasoning !== null && reasoning > 0 ? reasoning : null,
 		totalTokens: reading(raw.totalTokens),
 		costUsd,
@@ -72,6 +73,7 @@ export function recordFailedCompactionCalls(
 				output: usage.output ?? 0,
 				cacheRead: usage.cacheRead ?? 0,
 				cacheWrite: usage.cacheWrite ?? 0,
+				...(typeof usage.cacheWrite1h === "number" ? { cacheWrite1h: usage.cacheWrite1h } : {}),
 				reasoningTokens: usage.reasoning ?? 0,
 				totalTokens: usage.totalTokens ?? 0,
 				apiCalls: 1,

package/src/domains/observability/cost.ts

@@ -127,6 +127,7 @@ export interface UsageBreakdown {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	apiCalls?: number;
@@ -151,6 +152,7 @@ export interface CostEntry {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	apiCalls?: number;
 	/** Absent on an ordinary turn's call. */
@@ -215,6 +217,7 @@ export function createCostTracker(): CostTracker {
 				output,
 				cacheRead,
 				cacheWrite,
+				...(breakdown?.cacheWrite1h === undefined ? {} : { cacheWrite1h: breakdown.cacheWrite1h }),
 				reasoningTokens,
 				...(apiCalls !== undefined ? { apiCalls } : {}),
 				...(label !== undefined ? { label } : {}),
@@ -224,6 +227,7 @@ export function createCostTracker(): CostTracker {
 			totals.output += output;
 			totals.cacheRead += cacheRead;
 			totals.cacheWrite += cacheWrite;
+			if (breakdown?.cacheWrite1h !== undefined) totals.cacheWrite1h = (totals.cacheWrite1h ?? 0) + breakdown.cacheWrite1h;
 			totals.reasoningTokens += reasoningTokens;
 			totals.totalTokens += tokens;
 			return resolvedUsd;
@@ -247,6 +251,7 @@ export function createCostTracker(): CostTracker {
 			totals.output = 0;
 			totals.cacheRead = 0;
 			totals.cacheWrite = 0;
+			delete totals.cacheWrite1h;
 			totals.reasoningTokens = 0;
 			totals.totalTokens = 0;
 		},

package/src/domains/observability/extension.ts

@@ -64,6 +64,7 @@ function recordDispatchCost(
 			output: payload.outputTokenCount ?? 0,
 			cacheRead: payload.cacheReadTokenCount ?? 0,
 			cacheWrite: payload.cacheWriteTokenCount ?? 0,
+			...(payload.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1h: payload.cacheWrite1hTokenCount }),
 			reasoningTokens: payload.reasoningTokenCount ?? 0,
 			totalTokens: payload.tokenCount,
 		},

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

@@ -78,6 +78,7 @@ export interface OutOfTurnUsage {
 	output: number | null;
 	cacheRead: number | null;
 	cacheWrite: number | null;
+	cacheWrite1h?: number | null;
 	reasoning: number | null;
 	totalTokens: number | null;
 	costUsd: number | null;
@@ -253,6 +254,7 @@ function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 			output: reading(usage.output),
 			cacheRead: reading(usage.cacheRead),
 			cacheWrite: reading(usage.cacheWrite),
+			...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: nullableNumber(usage.cacheWrite1h) }),
 			reasoning: reading(usage.reasoning),
 			totalTokens: reading(usage.totalTokens),
 			costUsd: reading(usage.costUsd),

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

@@ -202,6 +202,7 @@ export interface TraceSpendInput {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	inputCostUsd?: number | null;
@@ -234,6 +235,7 @@ export interface SessionTurnUsage {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd?: number | null;
@@ -363,6 +365,7 @@ export interface TracePhaseRow {
 	output_tokens: number | null;
 	cache_read_tokens: number | null;
 	cache_write_tokens: number | null;
+	cache_write_1h_tokens?: number | null;
 	reasoning_tokens: number | null;
 	total_tokens: number | null;
 	input_cost_usd: number | null;
@@ -443,7 +446,7 @@ CREATE TABLE phases (
   error TEXT,
   started_at TEXT,
   ended_at TEXT,
-  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER,
+  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER, cache_write_1h_tokens INTEGER,
   reasoning_tokens INTEGER, total_tokens INTEGER,
   input_cost_usd REAL, output_cost_usd REAL, cache_read_cost_usd REAL, cache_write_cost_usd REAL,
   total_cost_usd REAL,
@@ -544,6 +547,13 @@ function ensureRunSourceColumn(db: DatabaseSync): void {
 	db.prepare("UPDATE runs SET source = 'session' WHERE assignment_id = ?").run(SESSION_TRACE_ASSIGNMENT_ID);
 }
 
+/** Missing lifetime detail stays NULL in older traces; it cannot be reconstructed. */
+function ensureCacheWriteLifetimeColumn(db: DatabaseSync): void {
+	const columns = db.prepare("PRAGMA table_info(phases)").all() as { name: string }[];
+	if (!columns.some((column) => column.name === "cache_write_1h_tokens"))
+		db.exec("ALTER TABLE phases ADD COLUMN cache_write_1h_tokens INTEGER;");
+}
+
 /**
  * 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
@@ -591,6 +601,7 @@ export class TraceStore {
 		this.transaction(() => {
 			ensureProcessOwnerColumns(this.db);
 			ensureRunSourceColumn(this.db);
+			ensureCacheWriteLifetimeColumn(this.db);
 			reconcileAbandonedRuns(this.db);
 		});
 	}
@@ -799,7 +810,7 @@ export class TraceStore {
 	recordSpend(input: TraceSpendInput): void {
 		this.transaction(() => {
 			this.db
-				.prepare(`UPDATE phases SET input_tokens=?, output_tokens=?, cache_read_tokens=?, cache_write_tokens=?,
+				.prepare(`UPDATE phases SET input_tokens=?, output_tokens=?, cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?,
           reasoning_tokens=?, total_tokens=?, input_cost_usd=?, output_cost_usd=?, cache_read_cost_usd=?,
           cache_write_cost_usd=?, total_cost_usd=?, context_tokens=?, context_window=? WHERE phase_id=? AND run_id=?`)
 				.run(
@@ -807,6 +818,7 @@ export class TraceStore {
 					input.outputTokens,
 					input.cacheReadTokens,
 					input.cacheWriteTokens,
+					input.cacheWrite1hTokens ?? null,
 					input.reasoningTokens,
 					input.totalTokens,
 					input.inputCostUsd ?? null,
@@ -982,7 +994,7 @@ export class TraceStore {
 				);
 			this.db
 				.prepare(`UPDATE phases SET status=?, attempt=?, retries=?, ended_at=?, error=?, input_tokens=?, output_tokens=?,
-          cache_read_tokens=?, cache_write_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
+          cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
           WHERE phase_id=?`)
 				.run(
 					success ? "success" : "fail",
@@ -994,6 +1006,7 @@ export class TraceStore {
 					input.outputTokenCount ?? null,
 					input.cacheReadTokenCount ?? null,
 					input.cacheWriteTokenCount ?? null,
+					input.cacheWrite1hTokenCount ?? null,
 					input.reasoningTokenCount ?? null,
 					input.tokenCount ?? null,
 					input.costUsd ?? null,
@@ -1113,7 +1126,7 @@ export class TraceStore {
 				.run(input.status, input.at, usage?.totalTokens ?? null, usage?.costUsd ?? null, input.runId);
 			this.db
 				.prepare(`UPDATE phases SET status=?, ended_at=?, error=?, input_tokens=?, output_tokens=?,
-          cache_read_tokens=?, cache_write_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
+          cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
           WHERE phase_id=?`)
 				.run(
 					input.status,
@@ -1123,6 +1136,7 @@ export class TraceStore {
 					usage?.outputTokens ?? null,
 					usage?.cacheReadTokens ?? null,
 					usage?.cacheWriteTokens ?? null,
+					usage?.cacheWrite1hTokens ?? null,
 					usage?.reasoningTokens ?? null,
 					usage?.totalTokens ?? null,
 					usage?.costUsd ?? null,
@@ -1186,13 +1200,24 @@ function traceDatabaseFootprintBytes(path: string): number {
 	return total;
 }
 
+export interface TraceRunCursor {
+	startedAt: string;
+	runId: string;
+}
+
+export interface TraceRunsPageOptions {
+	before?: TraceRunCursor;
+	limit?: number;
+	filter?: { source?: TraceRunRow["source"]; status?: TraceRunRow["status"]; q?: string };
+}
+
 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
+	 * web application 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.
 	 */
@@ -1223,6 +1248,40 @@ export class TraceReader {
 			.all(clampInt(limit, 1, 500)) as unknown as TraceRunRow[];
 	}
 
+	/** Stable keyset pagination, including read-only databases predating runs.source. */
+	runsPage({ before, limit = 50, filter = {} }: TraceRunsPageOptions = {}): {
+		runs: TraceRunRow[];
+		nextBefore: TraceRunCursor | null;
+	} {
+		const size = clampInt(limit, 1, 500);
+		const where: string[] = [],
+			args: SQLInputValue[] = [];
+		if (before) {
+			where.push("(started_at < ? OR (started_at = ? AND run_id < ?))");
+			args.push(before.startedAt, before.startedAt, before.runId);
+		}
+		if (filter.source) {
+			where.push("source = ?");
+			args.push(filter.source);
+		}
+		if (filter.status) {
+			where.push("status = ?");
+			args.push(filter.status);
+		}
+		if (filter.q) {
+			where.push("(run_id LIKE ? OR agent LIKE ? OR model LIKE ? OR status LIKE ? OR request LIKE ?)");
+			args.push(...Array<string>(5).fill(`%${filter.q}%`));
+		}
+		const rows = this.db
+			.prepare(
+				`SELECT * FROM (SELECT ${this.runsSourceExpr} FROM runs) ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY started_at DESC, run_id DESC LIMIT ?`,
+			)
+			.all(...args, size + 1) as unknown as TraceRunRow[];
+		const runs = rows.slice(0, size),
+			last = runs.at(-1);
+		return { runs, nextBefore: rows.length > size && last ? { startedAt: last.started_at, runId: last.run_id } : null };
+	}
+
 	run(runId: string): TraceRunRow | null {
 		return (
 			(this.db.prepare(`SELECT ${this.runsSourceExpr} FROM runs WHERE run_id=?`).get(runId) as unknown as
@@ -1567,6 +1626,7 @@ function terminalUsage(input: DispatchCompletedPayload | DispatchFailedPayload):
 		output: input.outputTokenCount ?? 0,
 		cache_read: input.cacheReadTokenCount ?? 0,
 		cache_write: input.cacheWriteTokenCount ?? 0,
+		...(input.cacheWrite1hTokenCount === undefined ? {} : { cache_write_1h: input.cacheWrite1hTokenCount }),
 		reasoning_tokens: input.reasoningTokenCount ?? 0,
 		total_tokens: input.tokenCount,
 	};