auto-model-router 0.4.3 → 0.4.4

package/.gitattributes

@@ -0,0 +1,2 @@
+# SQLite fixtures must never get line-ending conversion (core.autocrlf is on for this checkout).
+*.db binary

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.4.3",
+    "version": "0.4.4",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.4.3",
+      "version": "0.4.4",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -562,7 +562,9 @@ as the placeholder — empty input keeps it, `-` clears an optional field,
 credentials show as `set`/`unset` and are never echoed. `Save and exit` writes the merged config
 (schema-checked and backed up first). Tier, task, filter, classifier,
 hysteresis, exploration, compaction, cache and budget changes hot-reload;
-restart omp for `server`, `openrouter`, `ollama`, `context` and `ledger`.
+restart omp for `server` (except `subagentProfile`), `openrouter`, `context`,
+`ledger.path` and the Ollama connection keys; `ollama.costBias`,
+`ollama.biasUntilUsage` and `ledger.retentionDays` hot-reload too.
 
 ### Via `auto-model-router config` (text wizard / CLI)
 
@@ -822,6 +824,12 @@ is a ledger row (`requestedModel` `digest`) and the report totals them.
 | `maxCostUsd` | `0.02` | Skip when the digest itself would cost more. |
 | `timeoutMs` | `25000` | The raw result stands if the cheap model is slower. |
 
+Quality signal: when the agent later calls the same tool with the same
+primary argument (re-reads a digested file, re-runs a digested grep), the
+router marks that digest's ledger row wasted. The report's `digests` line
+shows the re-run rate; a high rate means the digest is dropping what the
+task needed, and `digest.maxOutputTokens` or `digest.model` is the lever.
+
 ### `report` — usage-report options
 
 | Key | Default | Meaning |
@@ -838,6 +846,7 @@ is a ledger row (`requestedModel` `digest`) and the report totals them.
 | `blendMinSamples` | `25` | Turns before the measured blend replaces the fallback. |
 | `fallbackBlend` | input `1.5`, output `7.5` | Pre-measurement blend (USD/Mtok) for omp's cost display. |
 | `conversationTtlMs` | `604800000` (7 d) | Drop conversation state untouched this long. |
+| `retentionDays` | `365` | Delete ledger rows older than this, checked hourly; `0` keeps everything. The ledger grows about 2.5 MB a day under steady use. Freed pages are reused, so the file stops growing rather than shrinking. |
 
 ### Top-level
 

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+preload = ["./test/support/preload.ts"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/catalog/composite.ts

@@ -23,6 +23,8 @@ export interface CompositeBias {
 	/** Plan usage fraction at which the bias switches off (list price). */
 	biasUntilUsage: number;
 	usage: OllamaUsageSource;
+	/** When given, read on every use instead of the static pair, so a config hot reload applies. */
+	live?: () => { costBias: number; biasUntilUsage: number };
 }
 
 export function createCompositeCatalog(
@@ -39,7 +41,8 @@ export function createCompositeCatalog(
 
 	/** The multiplier in force from the latest usage reading (no network). */
 	function currentBias(): number {
-		return effectiveOllamaBias(bias.costBias, bias.biasUntilUsage, bias.usage.peek());
+		const b = bias.live?.() ?? bias;
+		return effectiveOllamaBias(b.costBias, b.biasUntilUsage, bias.usage.peek());
 	}
 
 	function combine(base: CatalogSnapshot, models: readonly CatalogModel[]): CatalogSnapshot {

package/src/cli/config-wizard.ts

@@ -344,6 +344,7 @@ export const WIZARD_SECTIONS: readonly SectionSpec[] = [
 			{ path: "ledger.fallbackBlend.inputPerMtok", label: "Fallback blend input $/Mtok", kind: "number", min: 0 },
 			{ path: "ledger.fallbackBlend.outputPerMtok", label: "Fallback blend output $/Mtok", kind: "number", min: 0 },
 			{ path: "ledger.conversationTtlMs", label: "Conversation TTL", kind: "number", min: 1, hint: "ms" },
+			{ path: "ledger.retentionDays", label: "Ledger retention", kind: "number", min: 0, hint: "days; 0 keeps everything" },
 		],
 	},
 	{

package/src/config/defaults.ts

@@ -337,6 +337,7 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// so early cost reporting never underreports.
 		fallbackBlend: { inputPerMtok: 1.5, outputPerMtok: 7.5 },
 		conversationTtlMs: 7 * 24 * 60 * 60 * 1000,
+		retentionDays: 365,
 	},
 	// On by default: an absolute floor that no available model meets is how the
 	// router ends up serving every turn from the cheapest tier.

package/src/config/hot-reload.ts

@@ -90,15 +90,47 @@ export interface WatchConfigOptions {
 }
 
 /**
- * Watches `path` and applies valid changes to `live` in place. `frozen` blocks
- * (top-level names) are re-copied from `pinned` after every reload so file
- * edits to construction-captured blocks cannot silently diverge.
+ * Config paths captured at construction, so a file edit cannot reach the
+ * running process: the socket, the upstream clients, the agentdox bridge, the
+ * ledger file. Everything else, including `ollama.costBias`,
+ * `ollama.biasUntilUsage`, `server.subagentProfile` and `ledger.retentionDays`,
+ * is read at call time and hot-reloads. A bare block name pins the whole
+ * block; `block.key` pins one key and lets its siblings through.
+ */
+export const PINNED_CONFIG_PATHS: readonly string[] = [
+	"server.host",
+	"server.port",
+	"server.apiKey",
+	"server.harnessId",
+	"server.maxConcurrentTurns",
+	"openrouter",
+	"ollama.enabled",
+	"ollama.baseUrl",
+	"ollama.apiKey",
+	"ollama.timeoutMs",
+	"ollama.catalogTtlMs",
+	"ollama.includeLocal",
+	"ollama.prices",
+	"ollama.twins",
+	"ollama.usagePollMs",
+	"ollama.quotaCooldownMs",
+	"ollama.rateLimitCooldownMs",
+	"ollama.planCreditsUsd",
+	"context",
+	"ledger.path",
+];
+
+/**
+ * Watches `path` and applies valid changes to `live` in place. `frozen`
+ * entries are re-copied from `pinned` after every reload so file edits to
+ * construction-captured settings cannot silently diverge: a top-level name
+ * pins the whole block, `block.key` pins one key of it.
  */
 export function watchConfig(
 	path: string,
 	live: RouterConfig,
 	pinned: RouterConfig,
-	frozen: readonly (keyof RouterConfig)[],
+	frozen: readonly string[],
 	opts: WatchConfigOptions = {},
 ): ConfigWatcher {
 	let closed = false;
@@ -119,14 +151,31 @@ export function watchConfig(
 		}
 		lastError = "";
 
-		const frozenSet = new Set(frozen);
+		const frozenBlocks = new Set(frozen.filter((f) => !f.includes(".")));
+		const frozenKeys = new Map<string, string[]>();
+		for (const f of frozen) {
+			const dot = f.indexOf(".");
+			if (dot < 0) continue;
+			const block = f.slice(0, dot);
+			frozenKeys.set(block, [...(frozenKeys.get(block) ?? []), f.slice(dot + 1)]);
+		}
 		const changed: string[] = [];
 		const next = result.cfg as unknown as Record<string, unknown>;
+		const pinnedRec = pinned as unknown as Record<string, unknown>;
 		for (const key of Object.keys(next)) {
-			// Frozen blocks belong to construction: keep the pinned values.
-			const value = frozenSet.has(key as keyof RouterConfig)
-				? (pinned as unknown as Record<string, unknown>)[key]
-				: next[key];
+			// Frozen blocks belong to construction: keep the pinned values. A
+			// partially frozen block takes the file's siblings and the pinned keys.
+			let value = frozenBlocks.has(key) ? pinnedRec[key] : next[key];
+			const keys = frozenKeys.get(key);
+			if (keys !== undefined && !frozenBlocks.has(key) && value !== null && typeof value === "object") {
+				const merged: Record<string, unknown> = { ...(value as Record<string, unknown>) };
+				const pinnedBlock = (pinnedRec[key] ?? {}) as Record<string, unknown>;
+				for (const k of keys) {
+					if (pinnedBlock[k] === undefined) delete merged[k];
+					else merged[k] = pinnedBlock[k];
+				}
+				value = merged;
+			}
 			const before = JSON.stringify((live as unknown as Record<string, unknown>)[key]);
 			const after = JSON.stringify(value);
 			if (before !== after) changed.push(key);

package/src/config/schema.ts

@@ -229,6 +229,7 @@ const ledger = z.strictObject({
 	blendMinSamples: z.number().int().nonnegative().optional(),
 	fallbackBlend: fallbackBlend.optional(),
 	conversationTtlMs: z.number().positive().optional(),
+	retentionDays: z.number().int().nonnegative().optional(),
 });
 
 // Complete entries: arrays replace wholesale, so a partial profile would

package/src/config/types.ts

@@ -657,6 +657,13 @@ export interface LedgerConfig {
 	fallbackBlend: { inputPerMtok: number; outputPerMtok: number };
 	/** Drop conversation state untouched for longer than this, ms. */
 	conversationTtlMs: number;
+	/**
+	 * Delete ledger rows older than this many days (checked hourly). 0 keeps
+	 * everything. The ledger grows ~2.5 MB a day under steady use; trust,
+	 * reports and replay only read windows well inside a year. Freed pages
+	 * are reused, so the file stops growing rather than shrinking.
+	 */
+	retentionDays: number;
 }
 
 /**

package/src/cost/ledger.ts

@@ -375,6 +375,8 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 	);
 	const ratioStmt = db.query("SELECT est_bytes, actual_tokens, samples FROM token_calibration WHERE tokenizer = ?");
 	const recentStmt = db.query("SELECT * FROM ledger ORDER BY created_at_ms DESC LIMIT ?");
+	const pruneStmt = db.query("DELETE FROM ledger WHERE created_at_ms < ?");
+	const wasteStmt = db.query("UPDATE ledger SET wasted = 1 WHERE id = ?");
 	const providerSpendStmt = db.query(
 		"SELECT COALESCE(SUM(COALESCE(reported_usd, predicted_usd)), 0) AS total FROM ledger WHERE created_at_ms >= ? AND COALESCE(served_slug, slug) LIKE ?",
 	);
@@ -623,6 +625,13 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			const row = providerSpendStmt.get(sinceMs, `${slugPrefix}%`) as { total: number } | null;
 			return row?.total ?? 0;
 		},
+		prune(retentionDays: number, nowMs = Date.now()): number {
+			if (retentionDays <= 0) return 0;
+			return pruneStmt.run(nowMs - retentionDays * DAY_MS).changes;
+		},
+		markWasted(id: string): void {
+			wasteStmt.run(id);
+		},
 		latestForSession(ompSessionId: string): LedgerEntry | null {
 			if (ompSessionId === "") return null;
 			const row = sessionStmt.get(ompSessionId, 1) as LedgerRow | null;

package/src/cost/report.ts

@@ -34,6 +34,12 @@ export interface ReportTotals {
 	digests: number;
 	digestSpendUsd: number;
 	digestInputTokens: number;
+	/** Digests the agent went back on: the same tool re-run with the same primary argument afterwards (row marked wasted). */
+	digestReruns: number;
+	/** Forecast accuracy over clean kept rows with a reported cost: mean |predicted − reported| ÷ reported, and the share over-predicted. */
+	forecastSamples: number;
+	forecastMeanError: number;
+	forecastOverShare: number;
 }
 
 export interface ReportRow {
@@ -134,6 +140,8 @@ const COMP = "json_extract(usage, '$.completionTokens')";
 const PROVIDER = "CASE WHEN slug LIKE 'ollama/%' THEN 'ollama' ELSE 'openrouter' END";
 const STREAMED = "ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL";
 const EST = "json_extract(usage, '$.cachedEstimated') = 1";
+/** Rows a forecast can be judged on: a reported cost, a prediction, clean and kept, not a side call. */
+const FORECASTABLE = "reported_usd > 0 AND predicted_usd IS NOT NULL AND wasted = 0 AND error IS NULL AND requested_model <> 'digest'";
 
 const ROW_SELECT = `
 	COUNT(*) AS dispatches,
@@ -213,6 +221,10 @@ export function buildUsageReport(
 				SUM(CASE WHEN requested_model = 'digest' THEN 1 ELSE 0 END) AS digests,
 				COALESCE(SUM(CASE WHEN requested_model = 'digest' THEN ${USD} ELSE 0 END), 0) AS digest_spend,
 				COALESCE(SUM(CASE WHEN requested_model = 'digest' THEN ${PT} ELSE 0 END), 0) AS digest_input,
+				SUM(CASE WHEN requested_model = 'digest' AND wasted = 1 THEN 1 ELSE 0 END) AS digest_reruns,
+				SUM(CASE WHEN ${FORECASTABLE} THEN 1 ELSE 0 END) AS fc_n,
+				COALESCE(SUM(CASE WHEN ${FORECASTABLE} THEN ABS(predicted_usd - reported_usd) / reported_usd END), 0) AS fc_err,
+				SUM(CASE WHEN ${FORECASTABLE} AND predicted_usd > reported_usd THEN 1 ELSE 0 END) AS fc_over,
 				SUM(CASE WHEN escalation_signal IS NOT NULL THEN 1 ELSE 0 END) AS escalations,
 				SUM(CASE WHEN instr(reasons, 'failover:') > 0 THEN 1 ELSE 0 END) AS failovers,
 				SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) AS errors,
@@ -232,6 +244,10 @@ export function buildUsageReport(
 		digests: number | null;
 		digest_spend: number;
 		digest_input: number;
+		digest_reruns: number | null;
+		fc_n: number | null;
+		fc_err: number;
+		fc_over: number | null;
 		escalations: number | null;
 		failovers: number | null;
 		errors: number | null;
@@ -354,6 +370,10 @@ export function buildUsageReport(
 			digests: t.digests ?? 0,
 			digestSpendUsd: t.digest_spend,
 			digestInputTokens: t.digest_input,
+			digestReruns: t.digest_reruns ?? 0,
+			forecastSamples: t.fc_n ?? 0,
+			forecastMeanError: (t.fc_n ?? 0) > 0 ? t.fc_err / (t.fc_n ?? 1) : 0,
+			forecastOverShare: (t.fc_n ?? 0) > 0 ? (t.fc_over ?? 0) / (t.fc_n ?? 1) : 0,
 		},
 		providers,
 		models,
@@ -419,7 +439,12 @@ export function reportView(r: UsageReport, opts: { maxModels?: number } = {}): R
 		);
 	}
 	if (t.digests > 0) {
-		summary.push(`digests: ${num(t.digests)} tool results condensed (${num(t.digestInputTokens)} tok read by a cheap model) for ${usd(t.digestSpendUsd)}`);
+		summary.push(
+			`digests: ${num(t.digests)} tool results condensed (${num(t.digestInputTokens)} tok read by a cheap model) for ${usd(t.digestSpendUsd)} · re-run rate ${pct(t.digestReruns / t.digests)} (${num(t.digestReruns)} fetched again in full)`,
+		);
+	}
+	if (t.forecastSamples > 0) {
+		summary.push(`forecast: mean error ${pct(t.forecastMeanError)} of reported cost over ${num(t.forecastSamples)} turns · ${pct(t.forecastOverShare)} over-predicted`);
 	}
 	if (t.subagentDispatches > 0) {
 		summary.push(`subagents: ${num(t.subagentDispatches)} dispatches, ${usd(t.subagentSpendUsd)} (${pct(t.spendUsd > 0 ? t.subagentSpendUsd / t.spendUsd : 0)} of spend)`);

package/src/cost/types.ts

@@ -303,4 +303,8 @@ export interface Ledger {
 	latestForSession?(ompSessionId: string): LedgerEntry | null;
 	/** Newest entries for an omp session, newest first. Optional. */
 	entriesForSession?(ompSessionId: string, limit: number): LedgerEntry[];
+	/** Deletes rows older than `retentionDays` (0 ⇒ none); returns how many. Optional. */
+	prune?(retentionDays: number, nowMs?: number): number;
+	/** Marks one row wasted after the fact (a digest the agent went back on). Optional. */
+	markWasted?(id: string): void;
 }

package/src/router/compaction.ts

@@ -64,7 +64,7 @@ export function validatePlan(
  * for the resource a call operates on (a `path`, `id`, `query`, ...). Used to
  * detect when a later call supersedes an earlier read of the same resource.
  */
-function primaryArg(argsJson: string): string | null {
+export function primaryArg(argsJson: string): string | null {
 	try {
 		const parsed: unknown = JSON.parse(argsJson);
 		if (parsed !== null && typeof parsed === "object") {

package/src/router/select.ts

@@ -8,7 +8,7 @@
 
 import type { CatalogSnapshot } from "../catalog/types.ts";
 import type { ProfileConfig, RouterConfig } from "../config/types.ts";
-import { priceAt } from "../cost/forecast.ts";
+import { forecast, priceAt } from "../cost/forecast.ts";
 import type { Ledger } from "../cost/types.ts";
 import { explorationDraw } from "./explore.ts";
 import type { CompactionEdit, NormRequest, ReasoningLevel } from "../wire/types.ts";
@@ -610,13 +610,33 @@ export function select(args: SelectArgs): Decision {
 	}
 	const stripAssistantReasoning = !(chosen.model.supportsReasoning && REASONING_REPLAY_AUTHORS[chosen.model.author] === true);
 
+	// The recorded forecast is the EXPECTED price of this dispatch, not the
+	// cold worst case candidates are ranked on. When the chosen model's cache
+	// is warm, the previous prompt's tokens are priced as cache reads at the
+	// model's measured hit rate; coldUsd stays the cold figure the budget
+	// guards used. Before this every recorded forecast was cold while nine
+	// turns in ten were warm: 89% over-predicted, median error 220%.
+	let expectedForecast = chosen.forecast;
+	if (warmSlug !== null && chosen.model.slug === warmSlug && effFeatures.promptTokens > 0 && state.lastPromptTokens > 0) {
+		const cachedShare = Math.min(1, state.lastPromptTokens / effFeatures.promptTokens);
+		let images = 0;
+		if (req.hasImages) for (const m of req.messages) images += m.images;
+		const warm = forecast(chosen.model, {
+			promptTokens: effFeatures.promptTokens,
+			completionTokens: EXPECTED_COMPLETION_TOKENS,
+			cacheHitRate: cacheHitExpectation(chosen.model.slug).rate * cachedShare,
+			images,
+		});
+		expectedForecast = { ...warm, coldUsd: chosen.forecast.coldUsd };
+	}
+
 	return {
 		slug: chosen.model.slug,
 		fallbacks,
 		tier: chosenTier,
 		classification: cls,
 		features,
-		forecast: chosen.forecast,
+		forecast: expectedForecast,
 		sessionId: state.sessionId,
 		sticky,
 		cacheBreakpointMessageIndices,

package/src/server/compaction-digest.ts

@@ -23,6 +23,8 @@ import type { DigestRequest, DigestResult } from "./digest.ts";
 
 export interface CompactionDigester {
 	digest(req: DigestRequest): Promise<DigestResult>;
+	/** See Digester.noteToolCalls; optional so a fake need not implement it. */
+	noteToolCalls?(ompSessionId: string, calls: readonly { name: string; argsJson: string }[], nowMs?: number): number;
 }
 
 export interface DigestCompactionArgs {

package/src/server/digest.ts

@@ -23,6 +23,7 @@ import type { DigestConfig, RouterConfig } from "../config/types.ts";
 import { computeCost, forecast } from "../cost/forecast.ts";
 import type { Ledger, LedgerEntry } from "../cost/types.ts";
 import { buildCandidates } from "../router/candidates.ts";
+import { primaryArg } from "../router/compaction.ts";
 import { extractFeatures } from "../router/features.ts";
 import { TIER_ORDER, type Tier } from "../router/types.ts";
 import { estimateTokens } from "../tokens/estimate.ts";
@@ -107,8 +108,31 @@ function syntheticRequest(req: DigestRequest, promptText: string): NormRequest {
 	};
 }
 
-export function createDigester(deps: DigesterDeps): { digest(req: DigestRequest): Promise<DigestResult> } {
+/** A digest the agent may still go back on: same tool, same primary argument, within RERUN_WINDOW_MS. */
+interface RecentDigest {
+	tool: string;
+	arg: string | null;
+	atMs: number;
+	ledgerId: string;
+	rerun: boolean;
+}
+const RERUN_WINDOW_MS = 2 * 3_600_000;
+const RECENT_PER_SESSION = 50;
+
+export interface Digester {
+	digest(req: DigestRequest): Promise<DigestResult>;
+	/**
+	 * Quality signal: the tool calls a session just made. One that repeats a
+	 * recent digest (same tool, same primary argument) means the agent went
+	 * back for the full output; that digest's ledger row is marked wasted and
+	 * the report shows the re-run rate. Returns how many were marked.
+	 */
+	noteToolCalls(ompSessionId: string, calls: readonly { name: string; argsJson: string }[], nowMs?: number): number;
+}
+
+export function createDigester(deps: DigesterDeps): Digester {
 	const { cfg, catalog, ledger, upstream, log } = deps;
+	const recent = new Map<string, RecentDigest[]>();
 
 	/** Cheapest simple-tier model that fits the prompt, or the configured one. */
 	async function pickModel(req: NormRequest, promptTokens: number): Promise<CatalogModel | null> {
@@ -229,6 +253,11 @@ export function createDigester(deps: DigesterDeps): { digest(req: DigestRequest)
 			}
 			if (error !== null) return { digested: false, reason: `digest model failed: ${error}` };
 			if (text === "" || text.length >= inputBytes * 0.9) return { digested: false, reason: "digest did not shrink the output" };
+			if (req.ompSessionId !== "") {
+				const list = recent.get(req.ompSessionId) ?? [];
+				list.push({ tool: req.toolName.toLowerCase(), arg: primaryArg(JSON.stringify(req.input)), atMs: startedAt, ledgerId: entry.id, rerun: false });
+				recent.set(req.ompSessionId, list.slice(-RECENT_PER_SESSION));
+			}
 			return {
 				digested: true,
 				text: `${digestMarker(req.toolName, req.input, model.slug, inputBytes, text.length)}\n${text}`,
@@ -239,5 +268,30 @@ export function createDigester(deps: DigesterDeps): { digest(req: DigestRequest)
 				ms,
 			};
 		},
+		noteToolCalls(ompSessionId, calls, nowMs = Date.now()) {
+			const list = recent.get(ompSessionId);
+			if (list === undefined || list.length === 0) return 0;
+			let marked = 0;
+			for (const c of calls) {
+				const tool = c.name.toLowerCase();
+				const arg = primaryArg(c.argsJson);
+				if (arg === null) continue;
+				for (const d of list) {
+					if (d.rerun || d.tool !== tool || d.arg !== arg || nowMs - d.atMs > RERUN_WINDOW_MS) continue;
+					d.rerun = true;
+					marked++;
+					try {
+						ledger.markWasted?.(d.ledgerId);
+					} catch (err) {
+						log.debug("digest re-run mark failed", { error: err instanceof Error ? err.message : String(err) });
+					}
+					log.info("digest re-run: the agent fetched the full output after all", { tool, arg: arg.slice(0, 80) });
+				}
+			}
+			const kept = list.filter((d) => nowMs - d.atMs <= RERUN_WINDOW_MS);
+			if (kept.length === 0) recent.delete(ompSessionId);
+			else recent.set(ompSessionId, kept);
+			return marked;
+		},
 	};
 }

package/src/server/http.ts

@@ -17,7 +17,7 @@ import { UpstreamError } from "../upstream/types.ts";
 import { apiKeySource, ollamaKeySource } from "../config/load.ts";
 import { ollamaMeter } from "../upstream/ollama-usage.ts";
 import { routerConfigPath } from "../cli/config-cmd.ts";
-import { watchConfig } from "../config/hot-reload.ts";
+import { PINNED_CONFIG_PATHS, watchConfig } from "../config/hot-reload.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { createLogger } from "../util/log.ts";
 import { openDb } from "../util/sqlite.ts";
@@ -202,15 +202,16 @@ export function startServer(cfg: RouterConfig): StartedServer {
 
 	// Hot reload: ranking knobs (tiers, filters, escalation, budgets, …) take
 	// effect on the next turn without a restart, because every consumer reads
-	// the shared config object at call time. Construction-captured blocks
-	// (server socket, OpenRouter client, agentdox bridge) are pinned — editing
-	// those still requires a restart, and the watcher says so explicitly.
-	const pinned = { ...cfg };
+	// the shared config object at call time. Construction-captured settings
+	// (server socket, upstream clients, agentdox bridge, ledger file) are
+	// pinned by path (PINNED_CONFIG_PATHS); editing those still requires a
+	// restart. The blocks are deep-copied so a reload cannot mutate the pin.
+	const pinned = structuredClone(cfg);
 	const configWatcher = watchConfig(
 		routerConfigPath(),
 		cfg,
 		pinned,
-		["server", "openrouter", "ollama", "context", "ledger"],
+		PINNED_CONFIG_PATHS,
 		{
 			onReload: ({ changed }) => {
 				log.info("config reloaded", { changed: changed.join(", ") });
@@ -269,6 +270,20 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	}, 60_000);
 	pruneTimer.unref();
 
+	// Ledger retention: hourly, and once at boot so a lowered setting takes
+	// effect without waiting. Reads the live config, so it hot-reloads.
+	const retain = (): void => {
+		try {
+			const dropped = ledger.prune?.(cfg.ledger.retentionDays) ?? 0;
+			if (dropped > 0) log.info("pruned ledger rows past retention", { dropped, retentionDays: cfg.ledger.retentionDays });
+		} catch (err) {
+			log.warn("ledger retention prune failed", { error: err instanceof Error ? err.message : String(err) });
+		}
+	};
+	const retentionTimer = setInterval(retain, 3_600_000);
+	retentionTimer.unref();
+	setTimeout(retain, 5_000).unref();
+
 	// Periodically refetch the (key-scoped) catalog in the background so
 	// guardrail/preference changes are picked up without needing traffic and a
 	// TTL expiry. catalogRefreshMs === 0 disables this.

package/src/server/providers.ts

@@ -54,6 +54,7 @@ export function createProviders(cfg: RouterConfig, db: Database, log: Logger = c
 			costBias: cfg.ollama.costBias,
 			biasUntilUsage: cfg.ollama.biasUntilUsage,
 			usage: ollamaUsage,
+			live: () => ({ costBias: cfg.ollama.costBias, biasUntilUsage: cfg.ollama.biasUntilUsage }),
 		}),
 		ollama,
 		ollamaUsage,

package/src/server/turn.ts

@@ -114,6 +114,17 @@ export async function runTurn(
 	const log = createLogger(config.logLevel);
 	const state = conversations.load(req.conversationKey);
 	const turnNumber = state.turn + 1;
+	// Digest quality signal: the calls the agent just made, matched against
+	// recent digests of this session (a re-run of a digested read means the
+	// digest was not enough). The last assistant message holds this turn's calls.
+	if (deps.digester?.noteToolCalls !== undefined && req.ompSessionId !== "") {
+		for (let i = req.messages.length - 1; i >= 0; i--) {
+			const m = req.messages[i];
+			if (m === undefined || m.role !== "assistant") continue;
+			if (m.toolCalls.length > 0) deps.digester.noteToolCalls(req.ompSessionId, m.toolCalls.map((c) => ({ name: c.name, argsJson: c.argsJson })));
+			break;
+		}
+	}
 	// Request header wins; the configured default covers harnesses that send none.
 	const doxScope = req.agentdoxScope !== "" ? req.agentdoxScope : config.context.defaultScope;
 	const doxActive = bridge.enabled && doxScope !== "";

package/test/cache-control.test.ts

@@ -93,7 +93,7 @@ describe("planCacheBreakpoints", () => {
 	test("milestones follow post-compaction sizes", () => {
 		const req = loop(30);
 		const tail = req.messages.length - 1;
-		const plan = planCompaction(req.messages, BASE.compaction, req.promptBytes * 0.3, req.promptBytes);
+		const plan = planCompaction(req.messages, { ...BASE.compaction, enabled: true }, req.promptBytes * 0.3, req.promptBytes);
 		expect(plan.edits.length).toBeGreaterThan(0);
 		const options = cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 });
 		const raw = planCacheBreakpoints(req, MODEL, options).filter((i) => i !== 0 && i !== tail);

package/test/digest.test.ts

@@ -184,6 +184,28 @@ describe("createDigester", () => {
 		db.close();
 	});
 
+	test("a later call of the same tool with the same primary argument marks the digest wasted", async () => {
+		const cfg = cfgWith();
+		const db = openDb(":memory:");
+		const ledger = createLedger(db, cfg);
+		seedSession(ledger, "hard");
+		const dg = createDigester({ cfg, catalog, ledger, upstream: fakeUpstream(() => "Condensed.").upstream, log });
+		const r = await dg.digest({ ompSessionId: "omp-1", harnessId: "", toolName: "read", input: { path: "src/a.ts", offset: 1 }, content: BIG, query: "" });
+		expect(r.digested).toBe(true);
+		const row = () => ledger.recentEntries(10).find((e) => e.requestedModel === "digest")!;
+		expect(row().wasted).toBe(false);
+		// A different file, a different tool, another session: no match.
+		expect(dg.noteToolCalls("omp-1", [{ name: "read", argsJson: '{"path":"src/b.ts"}' }, { name: "grep", argsJson: '{"pattern":"src/a.ts"}' }])).toBe(0);
+		expect(dg.noteToolCalls("omp-2", [{ name: "read", argsJson: '{"path":"src/a.ts"}' }])).toBe(0);
+		expect(row().wasted).toBe(false);
+		// The same read again (case-insensitive tool name, any other args): the agent wanted the full output.
+		expect(dg.noteToolCalls("omp-1", [{ name: "Read", argsJson: '{"path":"src/a.ts","limit":50}' }])).toBe(1);
+		expect(row().wasted).toBe(true);
+		// Marked once; a third read does not count again.
+		expect(dg.noteToolCalls("omp-1", [{ name: "read", argsJson: '{"path":"src/a.ts"}' }])).toBe(0);
+		db.close();
+	});
+
 	test("a pinned digest model is used as-is", async () => {
 		const pinned = MODELS.find((m) => m.price.prompt > 0)!.slug;
 		const cfg = cfgWith({ model: pinned });

package/test/failover.test.ts

@@ -79,7 +79,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		report: { baselines: [], dailySummary: false },
 		digest: { enabled: false, minBytes: 12_000, maxBytes: 400_000, tools: ["read"], fromTier: "moderate", tier: "simple", model: "", maxOutputTokens: 700, maxCostUsd: 0.02, timeoutMs: 25_000 },
 		profiles: [],
-		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
+		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 , retentionDays: 0,},
 		adaptiveTierFloors: true,
 		adaptivePriceCeilings: false,
 		logLevel: "silent",

package/test/hot-reload.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
 import type { RouterConfig } from "../src/config/types.ts";
-import { readValidatedConfig, watchConfig, type ConfigWatcher } from "../src/config/hot-reload.ts";
+import { PINNED_CONFIG_PATHS, readValidatedConfig, watchConfig, type ConfigWatcher } from "../src/config/hot-reload.ts";
 
 const DIR = join(import.meta.dir, ".tmp-hot-reload");
 const CFG = join(DIR, "config.yml");
@@ -129,3 +129,39 @@ describe("watchConfig", () => {
 		expect(live.filters.latencyWeight).not.toBe(9.9);
 	});
 });
+
+describe("watchConfig pins by path", () => {
+	const CFG2 = join(DIR, "config-paths.yml");
+	const live: RouterConfig = structuredClone(DEFAULT_CONFIG);
+	let watcher: ConfigWatcher | null = null;
+
+	beforeAll(() => {
+		writeFileSync(CFG2, "");
+		const pinned = structuredClone(DEFAULT_CONFIG);
+		pinned.ollama.apiKey = "pinned-key";
+		watcher = watchConfig(CFG2, live, pinned, PINNED_CONFIG_PATHS);
+	});
+	afterAll(() => watcher?.close());
+
+	test("a pinned key inside a block keeps its construction value while its siblings hot-reload", async () => {
+		writeFileSync(CFG2, yamlOf({ ollama: { apiKey: "from-file", costBias: 0.25, biasUntilUsage: 0.5 }, server: { port: 1, subagentProfile: "auto" }, ledger: { retentionDays: 30 } }));
+		await settle();
+		expect(live.ollama.costBias).toBe(0.25);
+		expect(live.ollama.biasUntilUsage).toBe(0.5);
+		expect(live.ollama.apiKey).toBe("pinned-key");
+		expect(live.server.port).toBe(DEFAULT_CONFIG.server.port);
+		expect(live.server.subagentProfile).toBe("auto");
+		expect(live.ledger.retentionDays).toBe(30);
+		expect(live.ledger.path).toBe(DEFAULT_CONFIG.ledger.path);
+	});
+
+	test("the pinned path list names only real config keys", () => {
+		const root = DEFAULT_CONFIG as unknown as Record<string, Record<string, unknown>>;
+		for (const p of PINNED_CONFIG_PATHS) {
+			const [block = "", key] = p.split(".");
+			expect(block in root).toBe(true);
+			// Optional keys (server.apiKey, server.harnessId) are absent from the defaults but real.
+			if (key !== undefined && !["apiKey", "harnessId"].includes(key)) expect(key in root[block]!).toBe(true);
+		}
+	});
+});

package/test/migrations.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import { copyFileSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import { createFeedbackStore } from "../src/cost/feedback.ts";
+import { createLedger } from "../src/cost/ledger.ts";
+import { buildUsageReport } from "../src/cost/report.ts";
+import { buildDailySummary, createKv } from "../src/cost/summary.ts";
+import { createConversationStore } from "../src/router/state.ts";
+import { openDb } from "../src/util/sqlite.ts";
+
+/**
+ * Every ledger a past release wrote must open under the current bootstrap:
+ * the version lands on the current number, every prepared statement the
+ * router uses compiles against the migrated schema, the carried rows survive
+ * with their backfills, and the aggregates run. The fixtures come from
+ * tools/gen-migration-fixtures.ts (each tag's own bootstrap plus one row per
+ * table), so a column added without a guard, or a statement that assumes a
+ * column older files lack, fails here rather than on a user's install.
+ */
+
+const FIXTURES = join(import.meta.dir, "fixtures", "migrations");
+const files = readdirSync(FIXTURES).filter((f) => /^router-v\d+\.db$/.test(f)).sort((a, b) => Number(/\d+/.exec(a)![0]) - Number(/\d+/.exec(b)![0]));
+const CURRENT_VERSION = 17;
+
+describe("schema migrations from every shipped version", () => {
+	test("fixtures exist for the versions that shipped", () => {
+		expect(files.map((f) => Number(/\d+/.exec(f)![0]))).toEqual([4, 5, 10, 12, 13, 14, 16]);
+	});
+
+	for (const file of files) {
+		const from = Number(/\d+/.exec(file)![0]);
+		test(`v${from} → v${CURRENT_VERSION}: opens, migrates, keeps its rows, and every consumer runs`, () => {
+			const dir = mkdtempSync(join(tmpdir(), "amr-migrate-"));
+			const path = join(dir, "router.db");
+			copyFileSync(join(FIXTURES, file), path);
+			const cfg = structuredClone(DEFAULT_CONFIG);
+			cfg.ledger.path = path;
+			const db = openDb(path);
+			try {
+				expect((db.query("PRAGMA user_version").get() as { user_version: number }).user_version).toBe(CURRENT_VERSION);
+				// Every column the current code writes exists after migration.
+				const ledgerCols = new Set((db.query("PRAGMA table_info(ledger)").all() as { name: string }[]).map((c) => c.name));
+				for (const c of ["harness_id", "error_kind", "omp_session_id", "features", "explored_from", "hold_arm", "prompt_tokens_saved"]) expect(ledgerCols.has(c)).toBe(true);
+				const convCols = new Set((db.query("PRAGMA table_info(conversations)").all() as { name: string }[]).map((c) => c.name));
+				for (const c of ["context_version", "compaction_plan", "compaction_plan_tokens", "upgrade_deferred_tier"]) expect(convCols.has(c)).toBe(true);
+				// The fixture's ledger row survived the ALTERs with its values.
+				const row = db.query("SELECT id, error, slug FROM ledger").get() as { id: string; error: string | null; slug: string } | null;
+				expect(row).toEqual({ id: "fixture-id", error: "upstream_error: 502", slug: "fixture-slug" });
+				// Every prepared statement compiles and every consumer runs on the migrated file.
+				const ledger = createLedger(db, cfg);
+				const conversations = createConversationStore(db);
+				createFeedbackStore(db);
+				createKv(db);
+				expect(ledger.recentEntries(5)).toHaveLength(1);
+				expect(ledger.trust("fixture-slug")).not.toBeNull();
+				expect(ledger.softFailureSpikes?.()).toEqual([]);
+				expect(ledger.latestForSession?.("nope")).toBeNull();
+				expect(conversations.load("fixture-key").key).toBe("fixture-key");
+				expect(buildUsageReport(db, { windowDays: 3650 }).totals.dispatches).toBe(1);
+				expect(buildDailySummary(db, {}).current.dispatches).toBe(0);
+				expect(ledger.prune?.(0)).toBe(0);
+			} finally {
+				db.close();
+				try {
+					rmSync(dir, { recursive: true, force: true });
+				} catch {
+					// Windows keeps the file locked until the statements are collected; the temp dir is disposable.
+				}
+			}
+		});
+	}
+
+	test("a fresh database lands on the same version as a migrated one", () => {
+		const db = openDb(":memory:");
+		try {
+			expect((db.query("PRAGMA user_version").get() as { user_version: number }).user_version).toBe(CURRENT_VERSION);
+		} finally {
+			db.close();
+		}
+	});
+});

package/test/report-hub.test.ts

@@ -80,7 +80,7 @@ function report(over: Partial<UsageReport> = {}): UsageReport {
 			subagentSpendUsd: 0,
 			digests: 0,
 			digestSpendUsd: 0,
-			digestInputTokens: 0,
+			digestInputTokens: 0, digestReruns: 0, forecastSamples: 0, forecastMeanError: 0, forecastOverShare: 0,
 		},
 		providers: [row("openrouter", 2), row("ollama", 1)],
 		models: [

package/test/report.test.ts

@@ -229,7 +229,7 @@ describe("buildUsageReport", () => {
 			subagentSpendUsd: 0,
 			digests: 0,
 			digestSpendUsd: 0,
-			digestInputTokens: 0,
+			digestInputTokens: 0, digestReruns: 0, forecastSamples: 0, forecastMeanError: 0, forecastOverShare: 0,
 		});
 		expect(r.providers).toEqual([]);
 		expect(r.models).toEqual([]);
@@ -291,3 +291,31 @@ describe("renderUsageReport", () => {
 		db.close();
 	});
 });
+
+describe("digest re-runs and forecast accuracy", () => {
+	test("wasted digest rows count as re-runs; forecast error is judged on clean kept rows only", () => {
+		const { db, ledger } = seeded();
+		try {
+			ledger.record(entry({ requestedModel: "digest", conversationKey: "d1", reportedUsd: 0.001, predictedUsd: 0.001 }));
+			ledger.record(entry({ requestedModel: "digest", conversationKey: "d2", reportedUsd: 0.001, predictedUsd: 0.001, wasted: true }));
+			// Two clean turns: one predicted double, one predicted half.
+			ledger.record(entry({ predictedUsd: 0.02, reportedUsd: 0.01 }));
+			ledger.record(entry({ predictedUsd: 0.005, reportedUsd: 0.01 }));
+			// Excluded from the forecast judgement: wasted, errored, no reported cost.
+			ledger.record(entry({ predictedUsd: 1, reportedUsd: 0.01, wasted: true }));
+			ledger.record(entry({ predictedUsd: 1, reportedUsd: 0.01, error: "upstream_error: 500" }));
+			ledger.record(entry({ predictedUsd: 1, reportedUsd: null }));
+			const t = buildUsageReport(db, { windowDays: 1, nowMs: NOW }).totals;
+			expect(t.digests).toBe(2);
+			expect(t.digestReruns).toBe(1);
+			expect(t.forecastSamples).toBe(2);
+			expect(t.forecastMeanError).toBeCloseTo((1 + 0.5) / 2, 6);
+			expect(t.forecastOverShare).toBeCloseTo(0.5, 6);
+			const text = renderUsageReport(buildUsageReport(db, { windowDays: 1, nowMs: NOW }));
+			expect(text).toContain("re-run rate 50% (1 fetched again in full)");
+			expect(text).toContain("forecast: mean error 75% of reported cost over 2 turns · 50% over-predicted");
+		} finally {
+			db.close();
+		}
+	});
+});

package/test/select.test.ts

@@ -1052,6 +1052,30 @@ describe("hysteresis.confirmUpgradesBelowConfidence", () => {
 	});
 });
 
+describe("recorded forecast is the expected price, not the cold worst case", () => {
+	const warmSlug = "x-ai/grok-4.6";
+	test("a warm stay prices the previous prompt as cache reads; coldUsd keeps the cold figure", () => {
+		const cfg: RouterConfig = { ...BASE, hysteresis: { ...BASE.hysteresis, switchMargin: 1e6 } };
+		const d = run({
+			tier: "hard",
+			promptTokens: 80_000,
+			cfg,
+			st: state({ currentSlug: warmSlug, currentTier: "hard", cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now(), lastPromptTokens: 60_000 }),
+		});
+		expect(d.slug).toBe(warmSlug);
+		// 60k of the 80k prompt is the cached prefix; no reliability sample ⇒ assumed reliable.
+		expect(d.forecast.assumedCacheHitRate).toBeCloseTo(0.75, 6);
+		expect(d.forecast.expectedUsd).toBeLessThan(d.forecast.coldUsd);
+		expect(d.forecast.breakdown.cacheRead).toBeGreaterThan(0);
+	});
+
+	test("a cold turn records the cold price", () => {
+		const d = run({ tier: "hard", promptTokens: 80_000 });
+		expect(d.forecast.assumedCacheHitRate).toBe(0);
+		expect(d.forecast.expectedUsd).toBeLessThanOrEqual(d.forecast.coldUsd);
+	});
+});
+
 describe("cache reliability in the stay/switch comparison", () => {
 	const warmSlug = "x-ai/grok-4.6";
 	function ledgerWithReliability(rate: number | null, samples = 50): Ledger {

package/test/support/preload.ts

@@ -0,0 +1,19 @@
+/**
+ * Test preload (bunfig.toml `[test] preload`): isolate every test from the
+ * developer's live router home BEFORE any module loads.
+ *
+ * Five test files build their config with `loadConfig({})`, which layers
+ * `$AUTO_MODEL_ROUTER_HOME/config.yml` over the defaults. Run alone they read
+ * the real config and fail on whatever the developer has tuned; run in the
+ * full suite they happened to pass because an earlier file had already
+ * pointed the home at a temp dir. Doing it here makes both cases the same.
+ * Tests that want a specific home (config.test.ts, embed-lifecycle) still
+ * set their own; this only supplies the default.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+if (process.env.AUTO_MODEL_ROUTER_HOME === undefined) {
+	process.env.AUTO_MODEL_ROUTER_HOME = mkdtempSync(join(tmpdir(), "amr-test-home-"));
+}

package/test/tokens.test.ts

@@ -281,3 +281,27 @@ describe("ledger.softFailureSpikes", () => {
 		}
 	});
 });
+
+describe("ledger.prune and markWasted", () => {
+	test("prune deletes rows past retention and 0 keeps everything; markWasted flips one row", () => {
+		const db = openDb(":memory:");
+		try {
+			const ledger = createLedger(db, cfg);
+			const now = 1_800_000_000_000;
+			const DAY = 86_400_000;
+			for (let i = 0; i < 5; i++) ledger.record(entry({ createdAtMs: now - i * 100 * DAY }));
+			expect(ledger.prune?.(0, now)).toBe(0);
+			expect(ledger.recentEntries(10)).toHaveLength(5);
+			expect(ledger.prune?.(365, now)).toBe(1); // only the 400-day-old row
+			expect(ledger.recentEntries(10)).toHaveLength(4);
+			expect(ledger.prune?.(150, now)).toBe(2); // 200 and 300 days old
+			const left = ledger.recentEntries(10);
+			expect(left).toHaveLength(2);
+			expect(left.every((e) => e.wasted === false)).toBe(true);
+			ledger.markWasted?.(left[0]!.id);
+			expect(ledger.recentEntries(10).find((e) => e.id === left[0]!.id)?.wasted).toBe(true);
+		} finally {
+			db.close();
+		}
+	});
+});

package/test/turn.test.ts

@@ -79,7 +79,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		report: { baselines: [], dailySummary: false },
 		digest: { enabled: false, minBytes: 12_000, maxBytes: 400_000, tools: ["read"], fromTier: "moderate", tier: "simple", model: "", maxOutputTokens: 700, maxCostUsd: 0.02, timeoutMs: 25_000 },
 		profiles: [],
-		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
+		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 , retentionDays: 0,},
 		adaptiveTierFloors: true,
 		adaptivePriceCeilings: false,
 		logLevel: "silent",

package/tools/gen-migration-fixtures.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+/**
+ * Regenerates the old-schema ledger fixtures that test/migrations.test.ts
+ * opens with the CURRENT bootstrap.
+ *
+ *   bun tools/gen-migration-fixtures.ts
+ *
+ * For each release tag that changed the schema, the bootstrap of THAT tag is
+ * taken from git, run against a fresh file, and a dummy row is inserted into
+ * every table (filling each NOT NULL column without a default by its declared
+ * type), so the migrations have data to carry, not just DDL. The WAL is folded
+ * back into the main file and the result lands in test/fixtures/migrations/
+ * as router-v<user_version>.db. Small (a few dozen KB each); commit them.
+ *
+ * Re-run only when adding a NEW historical version: rewriting existing
+ * fixtures would erase the very thing the test guards.
+ */
+
+import { Database } from "bun:sqlite";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $ } from "bun";
+
+/** One tag per schema version that shipped. */
+const TAGS = ["v0.1.0", "v0.1.4", "v0.2.0", "v0.2.10", "v0.2.22", "v0.2.28", "v0.3.0"];
+const OUT_DIR = join(import.meta.dir, "..", "test", "fixtures", "migrations");
+mkdirSync(OUT_DIR, { recursive: true });
+const work = mkdtempSync(join(tmpdir(), "amr-migrations-"));
+
+function dummy(type: string, name: string): string | number {
+	const t = type.toUpperCase();
+	if (name === "id" || name === "key") return `fixture-${name}`;
+	if (name === "created_at_ms" || name === "updated_at_ms" || name === "fetched_at_ms") return 1_756_000_000_000;
+	if (t.includes("INT") || t.includes("REAL")) return 1;
+	if (name === "usage") return JSON.stringify({ promptTokens: 100, cachedTokens: 0, cacheWriteTokens: 0, completionTokens: 10, reasoningTokens: 0, images: 0 });
+	if (name === "reasons") return JSON.stringify(["fixture"]);
+	if (name === "payload") return JSON.stringify({ data: [] });
+	return `fixture-${name}`;
+}
+
+for (const tag of TAGS) {
+	const src = await $`git show ${tag}:src/util/sqlite.ts`.text();
+	const modPath = join(work, `sqlite-${tag}.ts`);
+	await Bun.write(modPath, src);
+	const dbPath = join(work, `${tag}.db`);
+	const mod = (await import(modPath)) as { openDb(path: string): Database };
+	const db = mod.openDb(dbPath);
+	const version = (db.query("PRAGMA user_version").get() as { user_version: number }).user_version;
+	const tables = (db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all() as { name: string }[]).map((r) => r.name);
+	for (const table of tables) {
+		const cols = db.query(`PRAGMA table_info(${table})`).all() as { name: string; type: string; notnull: number; dflt_value: string | null; pk: number }[];
+		// NOT NULL columns without a default, plus text primary keys (SQLite lets
+		// a TEXT PRIMARY KEY be NULL, but the router never writes one that way).
+		const fill = cols.filter((c) => (c.notnull === 1 && c.dflt_value === null && !(c.pk === 1 && c.type.toUpperCase().includes("INT"))) || (c.pk === 1 && !c.type.toUpperCase().includes("INT")));
+		// A ledger row with an error string exercises the v4 error_kind backfill.
+		const values = fill.map((c) => (table === "ledger" && c.name === "error" ? "upstream_error: 502" : dummy(c.type, c.name)));
+		if (fill.length === 0) continue;
+		db.run(`INSERT INTO ${table} (${fill.map((c) => c.name).join(", ")}) VALUES (${fill.map(() => "?").join(", ")})`, values);
+		if (table === "ledger" && cols.some((c) => c.name === "error")) db.run(`UPDATE ledger SET error = 'upstream_error: 502'`);
+	}
+	db.run("PRAGMA wal_checkpoint(TRUNCATE)");
+	db.run("PRAGMA journal_mode = DELETE");
+	db.close();
+	const out = join(OUT_DIR, `router-v${version}.db`);
+	await Bun.write(out, Bun.file(dbPath));
+	console.log(`${tag} → ${out} (user_version ${version}, tables: ${tables.join(", ")})`);
+}
+rmSync(work, { recursive: true, force: true });