auto-model-router 0.3.3 → 0.4.0

package/test/features.test.ts

@@ -306,3 +306,34 @@ describe("user-visible tool failure (review 2026-09-05)", () => {
 		expect(f.lastToolFailed).toBe(false);
 	});
 });
+
+describe("prompt anatomy", () => {
+	test("splits prompt bytes by role and marks the older half and stale tool results", () => {
+		// 24 non-system messages: 12 tool-call/result pairs. The newest 20
+		// non-system messages are "fresh"; the 4 before them hold 2 stale tool results.
+		const messages: unknown[] = [SYSTEM];
+		for (let i = 0; i < 12; i++) {
+			messages.push(toolCall(`c${i}`, "bash", `{"command":"ls ${i}"}`));
+			messages.push({ role: "tool", tool_call_id: `c${i}`, content: "x".repeat(100) });
+		}
+		messages.push({ role: "user", content: "y".repeat(50) });
+		const f = extractFeatures(req(messages), 5000);
+		const a = f.anatomy!;
+		expect(a.messages).toBe(26);
+		expect(a.systemBytes).toBe("You are a coding agent.".length);
+		expect(a.userBytes).toBe(50);
+		expect(a.toolBytes).toBe(1200);
+		// 25 non-system messages; the older half is the first 12 (6 pairs ⇒ 6 tool results).
+		expect(a.olderHalfBytes).toBeGreaterThanOrEqual(600);
+		expect(a.olderHalfBytes).toBeLessThan(1200);
+		// Stale: tool results among the first 25-20 = 5 non-system messages ⇒ results at index 1 and 3.
+		expect(a.staleToolBytes).toBe(200);
+	});
+
+	test("a bare chat request has no stale tool bytes", () => {
+		const a = extractFeatures(req([SYSTEM, { role: "user", content: "hi" }]), 20).anatomy!;
+		expect(a.toolBytes).toBe(0);
+		expect(a.staleToolBytes).toBe(0);
+		expect(a.olderHalfBytes).toBe(0);
+	});
+});

package/test/learned.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+
+import { auc, FEATURE_NAMES, learnedVector, predictRisk, trainLogistic, type LearnedModel } from "../src/router/learned.ts";
+
+/**
+ * The learned escalation-risk model: a deterministic logistic regression that
+ * must separate a synthetic dataset, score by rank correctly, and tolerate
+ * old ledger rows missing fields.
+ */
+
+describe("learnedVector", () => {
+	test("matches FEATURE_NAMES in length and tolerates missing fields", () => {
+		const v = learnedVector({});
+		expect(v).toHaveLength(FEATURE_NAMES.length);
+		expect(v.every((x) => x === 0)).toBe(true);
+		const w = learnedVector({ promptTokens: 1000, lastToolFailed: true, requestedReasoning: "high", complexityKeywords: ["refactor", "migrate"] });
+		expect(w[FEATURE_NAMES.indexOf("log_prompt_tokens")]).toBeCloseTo(Math.log1p(1000), 6);
+		expect(w[FEATURE_NAMES.indexOf("last_tool_failed")]).toBe(1);
+		expect(w[FEATURE_NAMES.indexOf("requested_reasoning")]).toBe(3);
+		expect(w[FEATURE_NAMES.indexOf("complexity_keywords")]).toBe(2);
+	});
+});
+
+describe("auc", () => {
+	test("perfect ranking is 1, inverted is 0, ties count half", () => {
+		expect(auc([0.9, 0.8, 0.1, 0.2], [1, 1, 0, 0])).toBe(1);
+		expect(auc([0.1, 0.2, 0.9, 0.8], [1, 1, 0, 0])).toBe(0);
+		expect(auc([0.5, 0.5], [1, 0])).toBe(0.5);
+		expect(auc([0.3], [1])).toBe(0.5);
+	});
+});
+
+describe("trainLogistic", () => {
+	test("separates a dataset where escalation follows failed tools and long prompts", () => {
+		const xs: number[][] = [];
+		const ys: number[] = [];
+		let seed = 7;
+		const rnd = () => ((seed = (seed * 1103515245 + 12345) % 2147483648) / 2147483648);
+		for (let i = 0; i < 2000; i++) {
+			const failed = rnd() < 0.1;
+			const prompt = Math.floor(rnd() * 150_000);
+			const y = failed && prompt > 60_000 ? (rnd() < 0.9 ? 1 : 0) : rnd() < 0.02 ? 1 : 0;
+			xs.push(learnedVector({ promptTokens: prompt, lastToolFailed: failed, turnDepth: Math.floor(rnd() * 100), toolCount: 12 }));
+			ys.push(y);
+		}
+		const fit = trainLogistic(xs.slice(0, 1600), ys.slice(0, 1600), { epochs: 300 });
+		const model: LearnedModel = { version: 1, trainedAtMs: 0, rows: 1600, positives: 0, names: [...FEATURE_NAMES], means: fit.means, stds: fit.stds, weights: fit.weights, bias: fit.bias, auc: 0 };
+		const scores = xs.slice(1600).map((x) => {
+			// predictRisk takes features; rebuild the same vector through it for parity.
+			const f = { promptTokens: Math.expm1(x[0]!), lastToolFailed: x[8] === 1, turnDepth: x[2]!, toolCount: x[3]! };
+			return predictRisk(model, f);
+		});
+		expect(auc(scores, ys.slice(1600))).toBeGreaterThan(0.85);
+		expect(fit.weights[FEATURE_NAMES.indexOf("last_tool_failed")]!).toBeGreaterThan(0);
+		expect(fit.weights[FEATURE_NAMES.indexOf("log_prompt_tokens")]!).toBeGreaterThan(0);
+	});
+
+	test("refuses an empty dataset", () => {
+		expect(() => trainLogistic([], [])).toThrow();
+	});
+});

package/test/ollama.test.ts

@@ -12,17 +12,30 @@ import {
 	parseOllamaListing,
 	parseOllamaShow,
 	type OllamaListing,
+	loadOllamaCatalogCache,
 } from "../src/catalog/ollama-catalog.ts";
 import { bareCloudName, ollamaRateFor } from "../src/catalog/ollama-prices.ts";
 import { normalizeCatalogModel } from "../src/catalog/openrouter-catalog.ts";
 import type { CatalogModel, CatalogSnapshot, CatalogSource } from "../src/catalog/types.ts";
 import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import { openDb } from "../src/util/sqlite.ts";
 import type { OllamaConfig, RouterConfig } from "../src/config/types.ts";
 import { buildCandidates } from "../src/router/candidates.ts";
 import { extractFeatures } from "../src/router/features.ts";
 import { createMultiUpstream } from "../src/upstream/multi.ts";
 import { classifyOllamaStatus, createOllamaClient, toOllamaBody } from "../src/upstream/ollama.ts";
-import { createOllamaUsageSource, effectiveOllamaBias, NO_USAGE, ollamaMeter, parseOllamaPlan, parseOllamaUsage, usageFraction } from "../src/upstream/ollama-usage.ts";
+import {
+	CALIBRATION_MAX_FACTOR,
+	CALIBRATION_MIN_FACTOR,
+	calibrationFrom,
+	createOllamaUsageSource,
+	effectiveOllamaBias,
+	NO_USAGE,
+	ollamaMeter,
+	parseOllamaPlan,
+	parseOllamaUsage,
+	usageFraction,
+} from "../src/upstream/ollama-usage.ts";
 import type { Dispatch, DispatchOptions, UpstreamClient } from "../src/upstream/types.ts";
 import { createLogger } from "../src/util/log.ts";
 import { parseChatRequest } from "../src/wire/openai/request.ts";
@@ -195,6 +208,20 @@ describe("createOllamaCatalog", () => {
 		expect(src.peek()).toHaveLength(1);
 	});
 
+	test("a built set is persisted, and a fresh source hydrates it before its first listing", async () => {
+		const db = openDb(":memory:");
+		const fetchImpl = async (url: string): Promise<Response> => Response.json({ models: url.endsWith("/api/tags") ? DAEMON_TAGS : [] });
+		const src = createOllamaCatalog(OLLAMA, log, fetchImpl, db);
+		const built = await src.get(OR_MODELS);
+		expect(built.length).toBeGreaterThan(0);
+		expect(loadOllamaCatalogCache(db).models.map((m) => m.slug)).toEqual(built.map((m) => m.slug));
+		// A new process: peek() answers from disk with no network at all.
+		const dead = async (): Promise<Response> => { throw new Error("offline"); };
+		const again = createOllamaCatalog(OLLAMA, log, dead, db);
+		expect(again.peek().map((m) => m.slug)).toEqual(built.map((m) => m.slug));
+		db.close();
+	});
+
 	test("a failed listing keeps the previous set", async () => {
 		let fail = false;
 		const fetchImpl = async (url: string): Promise<Response> => {
@@ -488,7 +515,7 @@ describe("ollama plan usage (credit-aware bias)", () => {
 		const source = { get: async () => ollamaModels, peek: () => ollamaModels, invalidate: () => {} };
 		const breaker = { available: () => true, cooldownUntilMs: () => null, lastTrip: () => null };
 		let used = 0.2;
-		const usage = { get: async () => ({ monthlyUsedFraction: used, monthlyUsageRaw: used * 100, activityCostUsd: null, requestsThisMonth: 0, plan: null, fetchedAtMs: 0 }), peek: () => ({ monthlyUsedFraction: used, monthlyUsageRaw: used * 100, activityCostUsd: null, requestsThisMonth: 0, plan: null, fetchedAtMs: 0 }) };
+		const usage = { get: async () => ({ monthlyUsedFraction: used, monthlyUsageRaw: used * 100, activityCostUsd: null, requestsThisMonth: 0, plan: null, fetchedAtMs: 0 }), peek: () => ({ monthlyUsedFraction: used, monthlyUsageRaw: used * 100, activityCostUsd: null, requestsThisMonth: 0, plan: null, fetchedAtMs: 0 }), calibration: () => null };
 		const catalog = createCompositeCatalog(openrouter, source, breaker, { costBias: 0.1, biasUntilUsage: 0.9, usage });
 
 		const a = await catalog.get();
@@ -538,3 +565,48 @@ describe("ollamaMeter", () => {
 		expect(parseOllamaPlan("nope")).toBeNull();
 	});
 });
+
+describe("ollama calibration", () => {
+	const s = (h: number, meterUsd: number, ledgerUsd: number) => ({ atMs: h * 3_600_000, meterUsd, ledgerUsd });
+
+	test("compares the newest reading with the oldest since the last meter reset", () => {
+		// Ledger estimated $4 over the span; the meter moved $5 ⇒ estimates run 20% low.
+		const c = calibrationFrom([s(0, 10, 20), s(12, 12.5, 22), s(24, 15, 24)])!;
+		expect(c.factor).toBeCloseTo(1.25, 6);
+		expect(c.spanHours).toBe(24);
+		expect(c.samples).toBe(3);
+		// A billing-cycle reset (meter drops) ends the span.
+		const reset = calibrationFrom([s(0, 50, 40), s(12, 0.5, 41), s(24, 1.5, 42)])!;
+		expect(reset.samples).toBe(2);
+		expect(reset.factor).toBeCloseTo(1, 6);
+	});
+
+	test("needs enough metered spend to mean anything, and clamps to 0.5–2×", () => {
+		expect(calibrationFrom([s(0, 1, 1), s(1, 1.03, 1.2)])).toBeNull(); // meter moved less than its resolution
+		expect(calibrationFrom([s(0, 1, 1), s(1, 2, 1.3)])).toBeNull(); // ledger moved less than $0.50
+		expect(calibrationFrom([s(0, 0, 0), s(1, 10, 1)])!.factor).toBe(CALIBRATION_MAX_FACTOR);
+		expect(calibrationFrom([s(0, 0, 0), s(1, 0.1, 10)])!.factor).toBe(CALIBRATION_MIN_FACTOR);
+		expect(calibrationFrom([s(0, 1, 1)])).toBeNull();
+	});
+
+	test("the source records a sample per poll and exposes the calibration", async () => {
+		const db = openDb(":memory:");
+		let ledgerUsd = 1;
+		let frac = 0.1;
+		const fetchImpl = async (url: string): Promise<Response> => {
+			if (url.endsWith("/api/me")) return Response.json({ Plan: "pro" });
+			return Response.json({ limits: { monthly: { usage: frac, models: [] } } });
+		};
+		const src = createOllamaUsageSource({ apiKey: "k", pollMs: 5, timeoutMs: 1000, log, fetchImpl, calibration: { db, ledgerUsd: () => ledgerUsd, planCreditsOverrideUsd: 0 } });
+		await src.get(); // meter $6 (10% of $60), ledger $1
+		expect(src.calibration()).toBeNull(); // one sample
+		await new Promise((r) => setTimeout(r, 20));
+		ledgerUsd = 3; // ledger +$2
+		frac = 0.15; // meter +$3
+		await src.get();
+		const c = src.calibration()!;
+		expect(c.factor).toBeCloseTo(1.5, 6);
+		expect((db.query("SELECT COUNT(*) n FROM ollama_meter_samples").get() as { n: number }).n).toBe(2);
+		db.close();
+	});
+});

package/test/report-hub.test.ts

@@ -79,14 +79,16 @@ function report(over: Partial<UsageReport> = {}): UsageReport {
 		},
 		providers: [row("openrouter", 2), row("ollama", 1)],
 		models: [
-			{ ...row("z-ai/glm", 2), provider: "openrouter", tiers: { simple: 6, moderate: 4 } },
-			{ ...row("ollama/kimi", 1), provider: "ollama", tiers: { hard: 10 } },
+			{ ...row("z-ai/glm", 2), provider: "openrouter", tiers: { simple: 6, moderate: 4 }, feedback: { good: 0, bad: 0 } },
+			{ ...row("ollama/kimi", 1), provider: "ollama", tiers: { hard: 10 }, feedback: { good: 0, bad: 0 } },
 		],
 		tiers: [row("simple", 2), row("hard", 1)],
 		days: [
 			{ day: "2026-09-05", dispatches: 10, spendUsd: 1.5, cacheHitRate: 0.8 },
 			{ day: "2026-09-06", dispatches: 10, spendUsd: 1.5, cacheHitRate: 0.8 },
 		],
+		anatomy: null,
+		baselines: [],
 		...over,
 	};
 }

package/test/report-logic.test.ts

@@ -66,6 +66,8 @@ describe("renderStatus", () => {
 				lastTrip: { kind: "quota", atMs: now - 120_000, message: "402" },
 				usage: { monthlyUsedFraction: 0.42, activityCostUsd: 3.1, fetchedAtMs: now },
 				meter: { usedUsd: 25.2, creditsUsd: 60, plan: "pro" },
+				calibration: { factor: 1.25, meterDeltaUsd: 5, ledgerDeltaUsd: 4, spanHours: 48 },
+				runway: { dailyBurnUsd: 1.5, creditsLeftUsd: 34.8, days: 23.2 },
 				costBias: { configured: 0.1, effective: 0.1, biasUntilUsage: 0.9 },
 			},
 			catalog: { models: 240, ageMs: 5 * 60_000, keyScoped: true, shrink: { fromModels: 300, toModels: 120, atMs: now } },
@@ -77,6 +79,7 @@ describe("renderStatus", () => {
 		expect(text).toContain("SHRANK 300 -> 120");
 		expect(text).toContain("COOLING DOWN");
 		expect(text).toContain("pro plan usage 42.0% ($25.20 of $60)");
+		expect(text).toContain("ollama billing: ledger estimate ×1.25 to match the meter (48h span) · burn $1.50/day · ~23 days of credits left");
 		expect(text).toContain("cost bias ×0.1 (until 90%)");
 		expect(text).toContain("last trip quota 2m ago");
 		expect(text).toContain("scope omp-router");

package/test/report.test.ts

@@ -156,6 +156,47 @@ describe("buildUsageReport", () => {
 		db.close();
 	});
 
+	test("prompt anatomy averages the recorded byte shares", () => {
+		const { db, ledger } = seeded();
+		const feat = (tool: number, older: number, stale: number) => ({ toolSchemaBytes: 1000, anatomy: { messages: 30, systemBytes: 1000, userBytes: 500, assistantBytes: 500, toolBytes: tool, olderHalfBytes: older, staleToolBytes: stale } });
+		ledger.record(entry({ features: feat(8000, 5000, 4000) }));
+		ledger.record(entry({ features: feat(6000, 4000, 2000) }));
+		ledger.record(entry({ features: null })); // pre-anatomy row: ignored
+		const r = buildUsageReport(db, { windowDays: 7, nowMs: NOW });
+		const a = r.anatomy!;
+		expect(a.rows).toBe(2);
+		// mean bytes: system 1000, user 500, assistant 500, tool 7000 ⇒ total 9000
+		expect(a.tool).toBeCloseTo(7000 / 9000, 6);
+		expect(a.system).toBeCloseTo(1000 / 9000, 6);
+		expect(a.schemas).toBeCloseTo(1000 / 9000, 6);
+		expect(a.olderHalf).toBeCloseTo(4500 / 9000, 6);
+		expect(a.staleTool).toBeCloseTo(3000 / 9000, 6);
+		expect(renderUsageReport(r)).toContain("prompt anatomy (mean of 2): tool results 78%");
+		db.close();
+	});
+
+	test("baselines price the window on one model with its own cache hit rate", () => {
+		const { db, ledger } = seeded();
+		ledger.record(entry({ reportedUsd: 0.5, usage: { promptTokens: 100_000, cachedTokens: 80_000, cacheWriteTokens: 0, completionTokens: 1_000, reasoningTokens: 0, images: 0 } }));
+		const r = buildUsageReport(db, {
+			windowDays: 7,
+			nowMs: NOW,
+			baselines: [
+				{ slug: "big/model", prompt: 15 / 1e6, completion: 75 / 1e6, cacheRead: 1.5 / 1e6 },
+				{ slug: "nocache/model", prompt: 3 / 1e6, completion: 15 / 1e6 },
+			],
+		});
+		// 20k fresh × $15/M + 80k cached × $1.5/M + 1k completion × $75/M = 0.30 + 0.12 + 0.075
+		expect(r.baselines[0]!.usd).toBeCloseTo(0.495, 6);
+		expect(r.baselines[0]!.savedShare).toBeCloseTo(1 - 0.5 / 0.495, 6);
+		// No cache rate published: every prompt token at list price.
+		expect(r.baselines[1]!.usd).toBeCloseTo(0.3 + 0.015, 6);
+		const text = renderUsageReport(r);
+		expect(text).toContain("same traffic on one model: big/model $0.4950 (router cost extra 1%)");
+		expect(text).toContain("nocache/model $0.3150 (router cost extra 59%)");
+		db.close();
+	});
+
 	test("empty ledger yields zeroed totals and null speeds", () => {
 		const { db } = seeded();
 		const r = buildUsageReport(db, { windowDays: 7, nowMs: NOW });
@@ -175,6 +216,8 @@ describe("buildUsageReport", () => {
 		});
 		expect(r.providers).toEqual([]);
 		expect(r.models).toEqual([]);
+		expect(r.anatomy).toBeNull();
+		expect(r.baselines).toEqual([]);
 		db.close();
 	});
 

package/test/select.test.ts

@@ -8,7 +8,8 @@ import type { ProfileConfig, RouterConfig } from "../src/config/types.ts";
 import type { Ledger } from "../src/cost/types.ts";
 import { extractFeatures } from "../src/router/features.ts";
 import { scoreHeuristic } from "../src/router/classify.ts";
-import { BudgetExceededError, select } from "../src/router/select.ts";
+import { latencyWeightFor } from "../src/router/candidates.ts";
+import { BudgetExceededError, monthPace, monthStartMs, select } from "../src/router/select.ts";
 import type { ConversationState, Tier } from "../src/router/types.ts";
 import { parseChatRequest } from "../src/wire/openai/request.ts";
 import type { NormRequest } from "../src/wire/types.ts";
@@ -996,3 +997,181 @@ describe("compaction.replanGrowthRatio (review 2026-09-05 §7)", () => {
 	});
 });
 
+
+describe("hysteresis.confirmUpgradesBelowConfidence", () => {
+	// A low-confidence heuristic upgrade from a warm model waits one turn.
+	// Measured: 65 of 67 moderate→hard upgrades in a week bounced back within
+	// 3 turns, each paying a cold hard-tier read of a ~120k prompt.
+	const warmSlug = run({ tier: "moderate" }).slug;
+	function upgrade(opts: { confidence?: number; source?: "heuristic" | "escalation"; st?: Partial<ConversationState>; cfg?: RouterConfig; lastToolFailed?: boolean }) {
+		const cfg = opts.cfg ?? BASE;
+		const req = request("now rework the whole scheduler");
+		const base = extractFeatures(req, 120_000);
+		const features = opts.lastToolFailed === true ? { ...base, lastToolFailed: true } : base;
+		const heuristic = scoreHeuristic(features, cfg);
+		return select({
+			req,
+			features,
+			classification: { ...heuristic, tier: "hard", confidence: opts.confidence ?? 0.45, source: opts.source ?? "heuristic" },
+			profile: PROFILE,
+			state: state({ turn: 4, currentTier: "moderate", currentSlug: warmSlug, cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now(), lastPromptTokens: 110_000, ...opts.st }),
+			snapshot: SNAPSHOT,
+			ledger: null,
+			cfg,
+			nowMs: Date.now(),
+		});
+	}
+
+	test("a low-confidence upgrade from a warm model is deferred to the held tier", () => {
+		const d = upgrade({});
+		expect(d.tier).toBe("moderate");
+		expect(d.upgradeDeferred).toBe("hard");
+		expect(d.reasons.some((r) => r.includes("upgrade moderate → hard deferred one turn"))).toBe(true);
+	});
+
+	test("a second consecutive upgrade classification confirms it", () => {
+		const d = upgrade({ st: { upgradeDeferredTier: "hard" } });
+		expect(d.tier).toBe("hard");
+		expect(d.upgradeDeferred).toBeNull();
+		expect(d.reasons.some((r) => r.includes("upgrade moderate → hard confirmed"))).toBe(true);
+	});
+
+	test("confident classifications, cold caches, escalations, failing tools and the off switch all upgrade at once", () => {
+		expect(upgrade({ confidence: 0.9 }).tier).toBe("hard");
+		expect(upgrade({ st: { cacheWarmAtMs: Date.now() - 3_600_000 } }).tier).toBe("hard");
+		expect(upgrade({ source: "escalation" }).tier).toBe("hard");
+		expect(upgrade({ lastToolFailed: true }).tier).toBe("hard");
+		const off: RouterConfig = { ...BASE, hysteresis: { ...BASE.hysteresis, confirmUpgradesBelowConfidence: 0 } };
+		expect(upgrade({ cfg: off }).tier).toBe("hard");
+		for (const d of [upgrade({ confidence: 0.9 }), upgrade({ source: "escalation" })]) expect(d.upgradeDeferred).toBeNull();
+	});
+
+	test("a downgrade or a same-tier turn is never deferred", () => {
+		const d = run({ tier: "simple", st: state({ turn: 4, currentTier: "moderate", currentSlug: warmSlug, cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now() }) });
+		expect(d.upgradeDeferred).toBeNull();
+	});
+});
+
+describe("cache reliability in the stay/switch comparison", () => {
+	const warmSlug = "x-ai/grok-4.6";
+	function ledgerWithReliability(rate: number | null, samples = 50): Ledger {
+		return {
+			record: () => {},
+			conversationSpend: () => 0,
+			spendSince: () => 0,
+			blendedRate: () => null,
+			trust: () => null,
+			allTrust: () => [],
+			latency: () => null,
+			tokenRatio: () => null,
+			recentEntries: () => [],
+			cacheReliability: (slug) => (rate === null || slug !== warmSlug ? null : { slug, samples, hitRate: rate }),
+		};
+	}
+	const stayCostOf = (ledger: Ledger, cfg: RouterConfig = BASE): number => {
+		const d = run({
+			tier: "hard",
+			promptTokens: 80_000,
+			cfg,
+			ledger,
+			st: state({ currentSlug: warmSlug, currentTier: "hard", cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now(), lastPromptTokens: 80_000 }),
+		});
+		const m = /cache: (?:keeping warm|switch) .*?stay \$([0-9.]+)/.exec(d.reasons.join("\n"));
+		if (m === null) throw new Error(`no stay/switch reason in ${d.reasons.join(" | ")}`);
+		return Number(m[1]);
+	};
+
+	test("an unreliable cache prices staying at the fresh rate, a reliable one at the cached rate", () => {
+		const reliable = stayCostOf(ledgerWithReliability(1));
+		const flaky = stayCostOf(ledgerWithReliability(0));
+		const unknown = stayCostOf(ledgerWithReliability(null));
+		expect(flaky).toBeGreaterThan(reliable);
+		expect(unknown).toBeCloseTo(reliable, 6);
+	});
+
+	test("too few samples, or the feature off, assume a reliable cache", () => {
+		const reliable = stayCostOf(ledgerWithReliability(1));
+		expect(stayCostOf(ledgerWithReliability(0, 3))).toBeCloseTo(reliable, 6);
+		const off: RouterConfig = { ...BASE, filters: { ...BASE.filters, cacheReliabilityMinSamples: 0 } };
+		expect(stayCostOf(ledgerWithReliability(0), off)).toBeCloseTo(reliable, 6);
+	});
+
+	test("the reason names the measured hit rate", () => {
+		const d = run({
+			tier: "hard",
+			promptTokens: 80_000,
+			ledger: ledgerWithReliability(0.5, 40),
+			st: state({ currentSlug: warmSlug, currentTier: "hard", cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now(), lastPromptTokens: 80_000 }),
+		});
+		expect(d.reasons.some((r) => r.includes("warm hit 50% over 40"))).toBe(true);
+	});
+});
+
+describe("session pin (forceSlug)", () => {
+	test("a pinned catalog model wins over ranking and the warm model; an unknown pin is ignored with a reason", () => {
+		const warmSlug = run({ tier: "moderate" }).slug;
+		const pinSlug = run({ tier: "hard" }).slug; // a real, differently-ranked model
+		const req = request("tidy the retry helper");
+		const features = extractFeatures(req, 50_000);
+		const base = {
+			req,
+			features,
+			classification: scoreHeuristic(features, BASE),
+			profile: PROFILE,
+			state: state({ currentSlug: warmSlug, currentTier: "moderate", cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now(), lastPromptTokens: 50_000 }),
+			snapshot: SNAPSHOT,
+			ledger: null,
+			cfg: { ...BASE, hysteresis: { ...BASE.hysteresis, switchMargin: 1e6 } },
+			nowMs: Date.now(),
+		};
+		const pinned = select({ ...base, forceSlug: pinSlug });
+		expect(pinned.slug).toBe(pinSlug);
+		expect(pinned.sticky).toBe(false);
+		expect(pinned.reasons.some((r) => r.includes(`pinned to ${pinSlug} by session override`))).toBe(true);
+		const unknown = select({ ...base, forceSlug: "nope/model" });
+		expect(unknown.slug).toBe(warmSlug); // the huge switch margin keeps the warm model
+		expect(unknown.reasons.some((r) => r.includes("pin nope/model ignored"))).toBe(true);
+	});
+});
+
+describe("budget.perMonthUsd pacing", () => {
+	test("monthPace spreads what is left over the days left, today included", () => {
+		const sep7 = Date.UTC(2026, 8, 7, 12);
+		expect(monthStartMs(sep7)).toBe(Date.UTC(2026, 8, 1));
+		const p = monthPace(sep7, 60, 30);
+		expect(p.daysLeft).toBe(24); // 7th..30th
+		expect(p.dailyCapUsd).toBeCloseTo(30 / 24, 6);
+		expect(monthPace(sep7, 60, 70).dailyCapUsd).toBe(0);
+		expect(monthPace(Date.UTC(2026, 8, 30, 12), 60, 0).daysLeft).toBe(1);
+	});
+
+	test("a month running ahead of pace tightens the daily cap and says so", () => {
+		const ledger: Ledger = {
+			record: () => {},
+			conversationSpend: () => 0,
+			spendSince: (sinceMs) => (sinceMs <= monthStartMs(Date.now()) + 1 ? 59.99 : 0), // month-to-date $59.99, last 24h $0
+			blendedRate: () => null,
+			trust: () => null,
+			allTrust: () => [],
+			latency: () => null,
+			tokenRatio: () => null,
+			recentEntries: () => [],
+		};
+		const cfg: RouterConfig = { ...BASE, budget: { ...BASE.budget, perMonthUsd: 60, onExceeded: "reject" } };
+		expect(() => run({ tier: "hard", promptTokens: 50_000, cfg, ledger })).toThrow(/month pacing: \$59\.99 of \$60 spent/);
+		// Under pace: the cap is generous and nothing breaches.
+		const easy: Ledger = { ...ledger, spendSince: () => 1 };
+		expect(run({ tier: "hard", promptTokens: 50_000, cfg, ledger: easy }).budgetDowngraded).toBe(false);
+	});
+});
+
+describe("filters.latencyWeightContinuation", () => {
+	test("applies only to tool-result continuations, and only when set", () => {
+		const f = { ...BASE.filters, latencyWeight: 0.75 };
+		expect(latencyWeightFor(f, false)).toBe(0.75);
+		expect(latencyWeightFor(f, true)).toBe(0.75);
+		const g = { ...f, latencyWeightContinuation: 0.1 };
+		expect(latencyWeightFor(g, false)).toBe(0.75);
+		expect(latencyWeightFor(g, true)).toBe(0.1);
+	});
+});

package/test/trust-attribution.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import { loadConfig } from "../src/config/load.ts";
 import { createLedger, LATENCY_WINDOW_ROWS } from "../src/cost/ledger.ts";
 import { EMPTY_USAGE, type LedgerEntry } from "../src/cost/types.ts";
+import { createConversationStore } from "../src/router/state.ts";
 import { openDb } from "../src/util/sqlite.ts";
 
 const cfg = loadConfig({});
@@ -244,11 +245,24 @@ describe("v4 migration", () => {
 		}
 	});
 
-	test("schema is at user_version 16", () => {
+	test("a deferred upgrade tier survives a save/load round trip", () => {
+		const db = openDb(":memory:");
+		const store = createConversationStore(db);
+		const st = store.load("conv-defer");
+		st.upgradeDeferredTier = "hard";
+		store.save(st);
+		expect(store.load("conv-defer").upgradeDeferredTier).toBe("hard");
+		st.upgradeDeferredTier = null;
+		store.save(st);
+		expect(store.load("conv-defer").upgradeDeferredTier).toBeNull();
+		db.close();
+	});
+
+	test("schema is at user_version 17", () => {
 		const db = openDb(":memory:");
 		try {
 			const row = db.query("PRAGMA user_version").get() as { user_version: number };
-			expect(row.user_version).toBe(16);
+			expect(row.user_version).toBe(17);
 		} finally {
 			db.close();
 		}
@@ -354,3 +368,45 @@ describe("v6 classifier instrumentation", () => {
 		}
 	});
 });
+
+describe("cache reliability signal", () => {
+	// Observed hit rate when a warm cache was expected: the previous kept turn
+	// of the conversation was on the same model within the warm TTL.
+	function seed(rows: Array<Partial<LedgerEntry>>) {
+		const db = openDb(":memory:");
+		const ledger = createLedger(db, cfg);
+		for (const r of rows) ledger.record(entry(r));
+		return { db, ledger };
+	}
+	const t0 = Date.UTC(2026, 8, 7, 12);
+	const usage = (prompt: number, cached: number, estimated = false) => ({ ...EMPTY_USAGE, promptTokens: prompt, cachedTokens: cached, ...(estimated ? { cachedEstimated: true } : {}) });
+
+	test("a model that hits when warm scores 1; one that misses scores 0; the first turn never counts", () => {
+		const { db, ledger } = seed([
+			{ conversationKey: "a", slug: "good/m", servedSlug: "good/m", createdAtMs: t0, usage: usage(50_000, 0) }, // first turn: no expectation
+			{ conversationKey: "a", slug: "good/m", servedSlug: "good/m", createdAtMs: t0 + 60_000, usage: usage(60_000, 50_000) },
+			{ conversationKey: "a", slug: "good/m", servedSlug: "good/m", createdAtMs: t0 + 120_000, usage: usage(70_000, 60_000) },
+			{ conversationKey: "b", slug: "flaky/m", servedSlug: "flaky/m", createdAtMs: t0, usage: usage(50_000, 0) },
+			{ conversationKey: "b", slug: "flaky/m", servedSlug: "flaky/m", createdAtMs: t0 + 60_000, usage: usage(60_000, 0) },
+			{ conversationKey: "b", slug: "flaky/m", servedSlug: "flaky/m", createdAtMs: t0 + 120_000, usage: usage(70_000, 30_000) },
+		]);
+		expect(ledger.cacheReliability?.("good/m")).toEqual({ slug: "good/m", samples: 2, hitRate: 1 });
+		const flaky = ledger.cacheReliability?.("flaky/m");
+		expect(flaky?.samples).toBe(2);
+		expect(flaky?.hitRate).toBeCloseTo(0.25, 6); // (0 + 30k/60k) / 2
+		expect(ledger.cacheReliability?.("never/m")).toBeNull();
+		db.close();
+	});
+
+	test("a switch, an idle gap past the TTL, or a router-estimated count is not a warm-expected sample", () => {
+		const { db, ledger } = seed([
+			{ conversationKey: "a", slug: "x/m", servedSlug: "x/m", createdAtMs: t0, usage: usage(50_000, 0) },
+			{ conversationKey: "a", slug: "y/m", servedSlug: "y/m", createdAtMs: t0 + 60_000, usage: usage(60_000, 0) }, // switch
+			{ conversationKey: "a", slug: "y/m", servedSlug: "y/m", createdAtMs: t0 + 60_000 + cfg.hysteresis.cacheWarmTtlMs + 1, usage: usage(70_000, 0) }, // gap
+			{ conversationKey: "a", slug: "y/m", servedSlug: "y/m", createdAtMs: t0 + 60_000 + cfg.hysteresis.cacheWarmTtlMs + 2, usage: usage(80_000, 70_000, true) }, // estimated
+		]);
+		expect(ledger.cacheReliability?.("x/m")).toBeNull();
+		expect(ledger.cacheReliability?.("y/m")).toBeNull();
+		db.close();
+	});
+});

package/test/turn.test.ts

@@ -46,10 +46,10 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			data: { axis: "intelligence", minQuality: 0 },
 			chat: { axis: "intelligence", minQuality: 0 },
 		},
-		filters: { allow: [], deny: [], includeFree: false, requireToolSupport: true, minTrust: 0.6, minTrustSamples: 5, trustScopedByHarness: false, trustWindowDays: 0, contextHeadroom: 1.2, latencyWeight: 0, latencyReferenceMs: 5000, latencyReferenceTokensPerSec: 30, latencyMinSamples: 20, escalationCostWeight: 0 },
+		filters: { allow: [], deny: [], includeFree: false, requireToolSupport: true, minTrust: 0.6, minTrustSamples: 5, trustScopedByHarness: false, trustWindowDays: 0, contextHeadroom: 1.2, latencyWeight: 0, latencyReferenceMs: 5000, latencyReferenceTokensPerSec: 30, cacheReliabilityMinSamples: 10, latencyMinSamples: 20, escalationCostWeight: 0 },
 		classifier: {
 			ambiguityThreshold: 0,
-			model: "test/adjudicator",
+			model: "test/adjudicator", learnedModelPath: "",
 			maxCostFraction: 0.1,
 			maxCostUsd: 0.01,
 			timeoutMs: 5000,
@@ -70,12 +70,13 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			escalateOnLengthStop: false,
 			...escalation,
 		},
-		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1 },
+		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1, confirmUpgradesBelowConfidence: 0.6 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
 		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, floorRatio: 1, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true, replanGrowthRatio: 1 },
 		budget: { onExceeded: "downgrade" },
+		report: { baselines: [] },
 		profiles: [],
 		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
 		adaptiveTierFloors: true,
@@ -160,6 +161,7 @@ function mkDecision(tier: Tier, slug: string, probe: Partial<ProbePlan> = {}): D
 		reasons: ["test decision"],
 		explored: null,
 		budgetDowngraded: false,
+		upgradeDeferred: null,
 	};
 }
 
@@ -895,4 +897,34 @@ describe("latency measurement covers the work the router actually does", () => {
 		expect(map.get("conv-test")!.cacheWarmSlug).toBe(ollamaModel.slug);
 	});
 
+	test("an Ollama estimate is scaled by the ledger-vs-meter calibration", async () => {
+		const ollamaModel: CatalogModel = {
+			slug: "ollama/glm-5.3-flash",
+			provider: "ollama",
+			canonicalSlug: "ollama/glm-5.3-flash",
+			name: "glm",
+			contextLength: 1_000_000,
+			supportsTools: true,
+			supportsReasoning: true,
+			reasoningMandatory: false,
+			supportsToolChoice: false,
+			inputModalities: ["text"],
+			price: { prompt: 0.15 / 1e6, cacheRead: 0.03 / 1e6, completion: 0.5 / 1e6 },
+			priceTiers: [],
+			quality: {},
+			tokenizer: "Other",
+			isFree: false,
+			createdAtMs: 0,
+			author: "ollama",
+		};
+		const priced = { ...catalog, find: (slug: string) => (slug === ollamaModel.slug ? ollamaModel : undefined) };
+		const { router } = mkRouter([mkDecision("simple", ollamaModel.slug)]);
+		const { upstream } = mkUpstream([{ kind: "chunks", chunks: [startChunk(ollamaModel.slug), textChunk("ok"), finishChunk("stop"), usageChunk({ promptTokens: 100_000, completionTokens: 0 }, null)] }]);
+		const { ledger, entries } = mkLedger();
+		const { store } = mkConversations();
+		await runTurn(mkReq(), mkSink().sink, { config: mkConfig(), router, upstream, ledger, conversations: store, catalog: priced, context: createDisabledBridge(), ollamaCostScale: () => 1.25 }, new AbortController().signal);
+		// 100k × $0.15/M = $0.015, scaled ×1.25.
+		expect(entries[0]!.reportedUsd).toBeCloseTo(0.01875, 6);
+	});
+
 });