auto-model-router 0.3.4 → 0.4.0

package/src/router/learned.ts

@@ -0,0 +1,202 @@
+/**
+ * A learned escalation-risk model over the recorded classifier features.
+ *
+ * The heuristic classifier's weights are hand-set. The ledger holds, for
+ * every served turn, the exact feature vector the classifier saw and whether
+ * the turn escalated (a cheaper attempt was probe-rejected). That is a
+ * labelled dataset — ~13k rows, ~1% positive — and this module is the
+ * smallest honest learner for it: standardised features, L2-regularised
+ * logistic regression by full-batch gradient descent, evaluated by AUC on a
+ * time-ordered holdout so the future is never trained on.
+ *
+ * Advisory by design. `tools/train-classifier.ts` fits and writes a model
+ * file; with `classifier.learnedModelPath` set, `classify()` scores each
+ * turn and records `learned: p(escalate)=…` in the decision trail so the
+ * signal can be judged against outcomes (and replayed) before it is ever
+ * allowed to move a tier.
+ */
+
+import type { Features } from "./types.ts";
+
+export const LEARNED_MODEL_VERSION = 1;
+
+/** Feature names in vector order. Adding one is a model-version change. */
+export const FEATURE_NAMES: readonly string[] = [
+	"log_prompt_tokens",
+	"log_new_content_tokens",
+	"turn_depth",
+	"tool_count",
+	"log_tool_schema_bytes",
+	"is_tool_result_continuation",
+	"tool_loop_depth",
+	"distinct_tools_used",
+	"last_tool_failed",
+	"repeated_tool_call",
+	"circular_tool_call",
+	"has_images",
+	"has_new_image",
+	"code_blocks",
+	"log_code_bytes",
+	"looks_like_diff",
+	"complexity_keywords",
+	"triviality_keywords",
+	"requested_reasoning",
+	"question_count",
+	"is_terse_instruction",
+];
+
+const REASONING_ORDINAL: Record<string, number> = { off: 0, minimal: 0.5, low: 1, medium: 2, high: 3, xhigh: 4, max: 5 };
+
+const log1p = (v: number): number => Math.log1p(Math.max(0, v));
+const b = (v: boolean | undefined): number => (v === true ? 1 : 0);
+
+/** The numeric vector for one turn, in FEATURE_NAMES order. Tolerates old rows missing fields. */
+export function learnedVector(f: Partial<Features>): number[] {
+	return [
+		log1p(f.promptTokens ?? 0),
+		log1p(f.newContentTokens ?? 0),
+		f.turnDepth ?? 0,
+		f.toolCount ?? 0,
+		log1p(f.toolSchemaBytes ?? 0),
+		b(f.isToolResultContinuation),
+		f.toolLoopDepth ?? 0,
+		f.distinctToolsUsed ?? 0,
+		b(f.lastToolFailed),
+		b(f.repeatedToolCall),
+		b(f.circularToolCall),
+		b(f.hasImages),
+		b(f.hasNewImage),
+		f.codeBlocks ?? 0,
+		log1p(f.codeBytes ?? 0),
+		b(f.looksLikeDiff),
+		Array.isArray(f.complexityKeywords) ? f.complexityKeywords.length : 0,
+		Array.isArray(f.trivialityKeywords) ? f.trivialityKeywords.length : 0,
+		REASONING_ORDINAL[f.requestedReasoning ?? "off"] ?? 0,
+		f.questionCount ?? 0,
+		b(f.isTerseInstruction),
+	];
+}
+
+export interface LearnedModel {
+	version: number;
+	trainedAtMs: number;
+	rows: number;
+	positives: number;
+	names: string[];
+	means: number[];
+	stds: number[];
+	weights: number[];
+	bias: number;
+	/** Holdout AUC at training time, for the record. */
+	auc: number;
+}
+
+const sigmoid = (z: number): number => 1 / (1 + Math.exp(-z));
+
+/** P(escalate) for one turn under a model. */
+export function predictRisk(model: LearnedModel, f: Partial<Features>): number {
+	const x = learnedVector(f);
+	let z = model.bias;
+	for (let i = 0; i < model.weights.length && i < x.length; i++) {
+		const std = model.stds[i] ?? 1;
+		z += (model.weights[i] ?? 0) * (((x[i] ?? 0) - (model.means[i] ?? 0)) / (std > 0 ? std : 1));
+	}
+	return sigmoid(z);
+}
+
+export interface TrainOptions {
+	epochs?: number;
+	learningRate?: number;
+	/** L2 strength on the weights (not the bias). */
+	l2?: number;
+	/** Weight on positive examples, to counter the ~1% base rate. Default: negatives/positives. */
+	positiveWeight?: number;
+}
+
+/** Fits weights on already-vectorised rows. Pure, deterministic. */
+export function trainLogistic(xs: number[][], ys: number[], opts: TrainOptions = {}): { weights: number[]; bias: number; means: number[]; stds: number[] } {
+	const n = xs.length;
+	const d = xs[0]?.length ?? 0;
+	if (n === 0 || d === 0) throw new Error("no training rows");
+	const means = new Array<number>(d).fill(0);
+	const stds = new Array<number>(d).fill(0);
+	for (const x of xs) for (let j = 0; j < d; j++) means[j]! += (x[j] ?? 0) / n;
+	for (const x of xs) for (let j = 0; j < d; j++) stds[j]! += ((x[j] ?? 0) - means[j]!) ** 2 / n;
+	for (let j = 0; j < d; j++) stds[j] = Math.sqrt(stds[j]!) || 1;
+	const z = xs.map((x) => x.map((v, j) => (v - means[j]!) / stds[j]!));
+
+	const positives = ys.reduce((s, y) => s + y, 0);
+	const posWeight = opts.positiveWeight ?? (positives > 0 ? (n - positives) / positives : 1);
+	const epochs = opts.epochs ?? 400;
+	const lr = opts.learningRate ?? 0.1;
+	const l2 = opts.l2 ?? 0.01;
+	const w = new Array<number>(d).fill(0);
+	let bias = 0;
+	for (let e = 0; e < epochs; e++) {
+		const gw = new Array<number>(d).fill(0);
+		let gb = 0;
+		let totalWeight = 0;
+		for (let i = 0; i < n; i++) {
+			const row = z[i]!;
+			let s = bias;
+			for (let j = 0; j < d; j++) s += w[j]! * row[j]!;
+			const y = ys[i]!;
+			const sw = y === 1 ? posWeight : 1;
+			const err = (sigmoid(s) - y) * sw;
+			for (let j = 0; j < d; j++) gw[j]! += err * row[j]!;
+			gb += err;
+			totalWeight += sw;
+		}
+		for (let j = 0; j < d; j++) w[j] = w[j]! - lr * (gw[j]! / totalWeight + l2 * w[j]!);
+		bias -= lr * (gb / totalWeight);
+	}
+	return { weights: w, bias, means, stds };
+}
+
+/** Area under the ROC curve by rank (Mann-Whitney), ties counted half. */
+export function auc(scores: number[], labels: number[]): number {
+	const pos: number[] = [];
+	const neg: number[] = [];
+	scores.forEach((s, i) => (labels[i] === 1 ? pos : neg).push(s));
+	if (pos.length === 0 || neg.length === 0) return 0.5;
+	const sortedNeg = [...neg].sort((a, b) => a - b);
+	let sum = 0;
+	for (const p of pos) {
+		// count negatives below p, plus half of ties
+		let lo = 0;
+		let hi = sortedNeg.length;
+		while (lo < hi) {
+			const mid = (lo + hi) >> 1;
+			if (sortedNeg[mid]! < p) lo = mid + 1;
+			else hi = mid;
+		}
+		let ties = 0;
+		for (let k = lo; k < sortedNeg.length && sortedNeg[k] === p; k++) ties++;
+		sum += lo + ties / 2;
+	}
+	return sum / (pos.length * neg.length);
+}
+
+/** Loads a model file once per path; null when absent or unreadable. */
+const modelCache = new Map<string, LearnedModel | null>();
+export async function loadLearnedModel(path: string): Promise<LearnedModel | null> {
+	if (path === "") return null;
+	const cached = modelCache.get(path);
+	if (cached !== undefined) return cached;
+	let model: LearnedModel | null = null;
+	try {
+		const parsed = (await Bun.file(path).json()) as Partial<LearnedModel>;
+		if (parsed.version === LEARNED_MODEL_VERSION && Array.isArray(parsed.weights) && Array.isArray(parsed.means) && Array.isArray(parsed.stds)) {
+			model = parsed as LearnedModel;
+		}
+	} catch {
+		model = null;
+	}
+	modelCache.set(path, model);
+	return model;
+}
+
+/** Test seam: forget loaded models. */
+export function resetLearnedModels(): void {
+	modelCache.clear();
+}

package/src/router/select.ts

@@ -43,6 +43,12 @@ export interface SelectArgs {
 	 * `buildCandidates` so a failover retry lands on a different model.
 	 */
 	excludeSlugs?: readonly string[];
+	/**
+	 * Session override (/router pin): route to this slug. Admitted into the
+	 * tier as if pinned there, then chosen over ranking, hysteresis and the
+	 * stay/switch comparison. Ignored when the catalog has no such model.
+	 */
+	forceSlug?: string;
 }
 
 /**
@@ -108,6 +114,20 @@ function hardSignal(f: Features): boolean {
 	return f.lastToolFailed || f.circularToolCall || f.repeatedToolCall || reasoning === "high" || reasoning === "xhigh" || reasoning === "max";
 }
 
+/** Start of the UTC calendar month containing `nowMs`. */
+export function monthStartMs(nowMs: number): number {
+	const d = new Date(nowMs);
+	return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
+}
+
+/** The daily ceiling that spends what remains of a monthly target evenly over the days left (today included). */
+export function monthPace(nowMs: number, perMonthUsd: number, spentUsd: number): { spentUsd: number; daysLeft: number; dailyCapUsd: number } {
+	const d = new Date(nowMs);
+	const daysInMonth = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+	const daysLeft = Math.max(1, daysInMonth - d.getUTCDate() + 1);
+	return { spentUsd, daysLeft, dailyCapUsd: Math.max(0, (perMonthUsd - spentUsd) / daysLeft) };
+}
+
 export function select(args: SelectArgs): Decision {
 	const { req, features, classification, profile, state, snapshot, ledger, cfg, nowMs } = args;
 	const reasons: string[] = [];
@@ -329,6 +349,14 @@ export function select(args: SelectArgs): Decision {
 	// The task type selects the quality axis and capability filters; the tier
 	// still bounds cost (task selects, tier budgets).
 	const warmSlug = cacheWarm ? state.cacheWarmSlug : null;
+	// Expected cache hit for a model: its observed rate once enough warm-expected
+	// samples exist (filters.cacheReliabilityMinSamples), else a reliable 1.
+	const cacheHitExpectation = (slug: string): { rate: number; measured: boolean; samples: number } => {
+		const min = cfg.filters.cacheReliabilityMinSamples;
+		const rel = min > 0 ? (ledger?.cacheReliability?.(slug) ?? null) : null;
+		if (rel === null || rel.samples < min) return { rate: 1, measured: false, samples: rel?.samples ?? 0 };
+		return { rate: rel.hitRate, measured: true, samples: rel.samples };
+	};
 	// Pre-fetch trust/latency signals for all candidate slugs in one batch
 	// query per signal kind, instead of per-model individual lookups.
 	const candidateSignals =
@@ -342,6 +370,11 @@ export function select(args: SelectArgs): Decision {
 		cfg.filters.escalationCostWeight > 0
 			? (ledger?.escalationCost?.(cfg.ledger.blendWindowDays)?.usdPerPromptToken ?? null)
 			: null;
+	// A pinned slug is admitted the way a config pin is: into the tier's pin
+	// list for this call only, so the quality floor cannot keep it out.
+	const pinSlug = args.forceSlug !== undefined && snapshot.models.some((m) => m.slug === args.forceSlug) ? args.forceSlug : undefined;
+	const buildCfg = pinSlug === undefined ? cfg : { ...cfg, tiers: { ...cfg.tiers, [effective]: { ...cfg.tiers[effective], pin: [...cfg.tiers[effective].pin, pinSlug] } } };
+	if (args.forceSlug !== undefined && pinSlug === undefined) reasons.push(`pin ${args.forceSlug} ignored: not in the catalog`);
 	const build = (t: Tier, relaxLevel = 0): { candidates: Candidate[]; rejected: Rejection[] } =>
 		buildCandidates({
 			req,
@@ -350,7 +383,7 @@ export function select(args: SelectArgs): Decision {
 			task: classification.task,
 			snapshot,
 			ledger,
-			cfg,
+			cfg: buildCfg,
 			expectedCompletionTokens: EXPECTED_COMPLETION_TOKENS,
 			warmSlug,
 			relaxLevel,
@@ -364,7 +397,9 @@ export function select(args: SelectArgs): Decision {
 	// search must rebuild at the same level, or it re-applies the strict config
 	let rescuedRelax = 0;
 	for (const t of wideningOrder(effective, profile.minTier, profile.maxTier)) {
-		const b = build(t);
+		// A session pin is absolute: price ceiling, quality floor and trust all
+		// relax so the pinned model is admitted; hard exclusions still apply.
+		const b = build(t, pinSlug === undefined ? 0 : 3);
 		if (b.candidates.length > 0) {
 			built = b;
 			chosenTier = t;
@@ -417,6 +452,11 @@ export function select(args: SelectArgs): Decision {
 	const first = candidates[0];
 	if (first === undefined) throw new Error(`no viable model: catalog exhausted across profile ${profile.id}`);
 	let chosen = first;
+	const pinnedCandidate = pinSlug === undefined ? undefined : candidates.find((c) => c.model.slug === pinSlug);
+	if (pinnedCandidate !== undefined) {
+		chosen = pinnedCandidate;
+		reasons.push(`pinned to ${pinSlug} by session override (/router pin)`);
+	}
 
 	// 4. Cache-aware switch decision. Staying prices the previous turn's prompt
 	//    at the warm model's cache-read rate; switching prices the full current
@@ -424,14 +464,19 @@ export function select(args: SelectArgs): Decision {
 	//    assume the whole prompt is written). Switch only when the saving
 	//    clears switchMargin.
 	let sticky = false;
-	if (warmSlug !== null && chosen.model.slug !== warmSlug) {
+	if (pinnedCandidate === undefined && warmSlug !== null && chosen.model.slug !== warmSlug) {
 		const warm = candidates.find((c) => c.model.slug === warmSlug);
 		if (warm !== undefined) {
 			const warmPrice = priceAt(warm.model, Math.max(1, state.lastPromptTokens));
 			const newPrice = priceAt(chosen.model, Math.max(1, effFeatures.promptTokens));
-			const stayWarm = state.lastPromptTokens * (warmPrice.cacheRead ?? warmPrice.prompt);
+			// A warm read is only as cheap as the cache is reliable: price the
+			// expected mix of hits and provider-side misses, per model.
+			const warmHit = cacheHitExpectation(warm.model.slug);
+			const newHit = cacheHitExpectation(chosen.model.slug);
+			const stayWarm = state.lastPromptTokens * (warmHit.rate * (warmPrice.cacheRead ?? warmPrice.prompt) + (1 - warmHit.rate) * warmPrice.prompt);
 			const switchCold = effFeatures.promptTokens * (newPrice.prompt + (newPrice.cacheWrite ?? 0));
-			const newWarm = effFeatures.promptTokens * (newPrice.cacheRead ?? newPrice.prompt);
+			const newWarm = effFeatures.promptTokens * (newHit.rate * (newPrice.cacheRead ?? newPrice.prompt) + (1 - newHit.rate) * newPrice.prompt);
+			const hitNote = warmHit.measured ? `, warm hit ${(warmHit.rate * 100).toFixed(0)}% over ${warmHit.samples}` : "";
 			// Amortise over the horizon: H turns of staying warm against one cold
 			// switch plus H−1 turns warm on the new model. H = 1 is the one-turn
 			// comparison, which kept a 25x-priced model warm for a 33-dispatch run
@@ -442,13 +487,13 @@ export function select(args: SelectArgs): Decision {
 			const over = horizon > 1 ? ` over ${horizon} turns` : "";
 			if (stayCost > switchCost * cfg.hysteresis.switchMargin) {
 				reasons.push(
-					`cache: switch ${warmSlug} → ${chosen.model.slug} (stay $${stayCost.toFixed(4)} > switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin}${over})`,
+					`cache: switch ${warmSlug} → ${chosen.model.slug} (stay $${stayCost.toFixed(4)} > switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin}${over}${hitNote})`,
 				);
 			} else {
 				chosen = warm;
 				sticky = true;
 				reasons.push(
-					`cache: keeping warm ${warmSlug} (stay $${stayCost.toFixed(4)} ≤ switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin}${over})`,
+					`cache: keeping warm ${warmSlug} (stay $${stayCost.toFixed(4)} ≤ switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin}${over}${hitNote})`,
 				);
 			}
 		}
@@ -459,8 +504,19 @@ export function select(args: SelectArgs): Decision {
 		perTurnUsd: profile.budget?.perTurnUsd ?? cfg.budget.perTurnUsd,
 		perConversationUsd: profile.budget?.perConversationUsd ?? cfg.budget.perConversationUsd,
 		perDayUsd: profile.budget?.perDayUsd ?? cfg.budget.perDayUsd,
+		perMonthUsd: profile.budget?.perMonthUsd ?? cfg.budget.perMonthUsd,
 		onExceeded: profile.budget?.onExceeded ?? cfg.budget.onExceeded,
 	};
+	// Month pacing: what is left of the month's target, spread over the days
+	// left, becomes a daily ceiling that tightens as the month runs ahead.
+	let paceNote = "";
+	if (budget.perMonthUsd !== undefined) {
+		const pace = monthPace(nowMs, budget.perMonthUsd, ledger?.spendSince(monthStartMs(nowMs), req.harnessId) ?? 0);
+		if (budget.perDayUsd === undefined || pace.dailyCapUsd < budget.perDayUsd) {
+			budget.perDayUsd = pace.dailyCapUsd;
+			paceNote = ` (month pacing: $${pace.spentUsd.toFixed(2)} of $${budget.perMonthUsd} spent, $${pace.dailyCapUsd.toFixed(2)}/day for ${pace.daysLeft} more days)`;
+		}
+	}
 	const daySpend = budget.perDayUsd !== undefined ? (ledger?.spendSince(nowMs - DAY_MS, req.harnessId) ?? 0) : 0;
 	const breach = (c: Candidate): string | null => {
 		if (budget.perTurnUsd !== undefined && c.forecast.coldUsd > budget.perTurnUsd) {
@@ -474,7 +530,7 @@ export function select(args: SelectArgs): Decision {
 			// identifies itself, so multiple harnesses sharing one router each get
 			// their own daily budget instead of one exhausting it for the others.
 			if (daySpend + c.forecast.coldUsd > budget.perDayUsd) {
-				return `24h spend $${daySpend.toFixed(4)} + cold forecast > per-day budget $${budget.perDayUsd}`;
+				return `24h spend $${daySpend.toFixed(4)} + cold forecast > per-day budget $${budget.perDayUsd.toFixed(2)}${paceNote}`;
 			}
 		}
 		return null;

package/src/router/types.ts

@@ -90,6 +90,26 @@ export interface Features {
 	questionCount: number;
 	/** Newest user content is a single short imperative sentence. */
 	isTerseInstruction: boolean;
+	/**
+	 * Where the prompt's bytes are. Recorded with every turn so the question
+	 * "what is the prompt made of, and how old is it?" can be answered from the
+	 * ledger before deciding what compaction should shrink next. Absent on rows
+	 * recorded before it existed.
+	 */
+	anatomy?: PromptAnatomy;
+}
+
+/** Prompt bytes by message role and by age, plus the tool-schema bytes beside them. */
+export interface PromptAnatomy {
+	messages: number;
+	systemBytes: number;
+	userBytes: number;
+	assistantBytes: number;
+	toolBytes: number;
+	/** Bytes of non-system messages in the OLDER half of the conversation (by message index). */
+	olderHalfBytes: number;
+	/** Bytes of tool results older than the newest 20 messages: what compaction can reach. */
+	staleToolBytes: number;
 }
 
 export type ClassificationSource = "heuristic" | "llm" | "sticky" | "forced" | "escalation";
@@ -105,6 +125,8 @@ export interface Classification {
 	reasons: string[];
 	/** Raw heuristic score before tier bucketing, 0-1. */
 	score: number;
+	/** Learned P(escalate) when `classifier.learnedModelPath` is set (advisory; see router/learned.ts). */
+	learnedRisk?: number;
 }
 
 /** A model that survived capability filtering, with its economics attached. */
@@ -303,6 +325,14 @@ export interface Router {
 	 */
 	route(
 		req: NormRequest,
-		opts: { attempt: number; escalateFrom?: Tier; excludeSlugs?: readonly string[] },
+		opts: {
+			attempt: number;
+			escalateFrom?: Tier;
+			excludeSlugs?: readonly string[];
+			/** Session override (/router tier): classify as this tier. */
+			forceTier?: Tier;
+			/** Session override (/router pin): route to this slug when it exists in the catalog. */
+			forceSlug?: string;
+		},
 	): Promise<Decision>;
 }

package/src/server/http.ts

@@ -3,8 +3,11 @@ import { dirname } from "node:path";
 import type { Server } from "bun";
 import { createProviders } from "./providers.ts";
 import { createBridgeFromConfig } from "../context/index.ts";
+import { createFeedbackStore, type Verdict } from "../cost/feedback.ts";
 import { createLedger } from "../cost/ledger.ts";
-import { buildUsageReport } from "../cost/report.ts";
+import { createSessionOverrides } from "./overrides.ts";
+import { TIER_ORDER, type Tier } from "../router/types.ts";
+import { baselinePrices, buildUsageReport } from "../cost/report.ts";
 import type { Ledger, ModelTrust } from "../cost/types.ts";
 import { createRouter } from "../router/index.ts";
 import { createConversationStore } from "../router/state.ts";
@@ -121,6 +124,18 @@ export function computeStats(ledger: Ledger, opts?: { windowDays?: number; nowMs
 	};
 }
 
+/** Days of included credits left at the last 7 days' burn (ledger, scaled by the calibration). */
+export function ollamaRunway(
+	meter: { usedUsd: number; creditsUsd: number } | null,
+	ledgerUsd7d: number,
+	factor: number,
+): { dailyBurnUsd: number; creditsLeftUsd: number; days: number | null } | null {
+	if (meter === null) return null;
+	const dailyBurnUsd = (ledgerUsd7d / 7) * factor;
+	const creditsLeftUsd = Math.max(0, meter.creditsUsd - meter.usedUsd);
+	return { dailyBurnUsd, creditsLeftUsd, days: dailyBurnUsd > 0 ? creditsLeftUsd / dailyBurnUsd : null };
+}
+
 function json(data: unknown, status = 200): Response {
 	return new Response(JSON.stringify(data), {
 		status,
@@ -173,11 +188,13 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	if (cfg.ledger.path !== ":memory:") mkdirSync(dirname(cfg.ledger.path), { recursive: true });
 	const db = openDb(cfg.ledger.path);
 	const ledger = createLedger(db, cfg);
-	const { upstream, catalog, ollama, ollamaUsage } = createProviders(cfg, db, log);
+	const { upstream, catalog, ollama, ollamaUsage, ollamaCostScale } = createProviders(cfg, db, log);
 	const conversations = createConversationStore(db);
 	const router = createRouter({ config: cfg, catalog, ledger, conversations, upstream });
 	const context = createBridgeFromConfig(cfg, db);
-	const turnDeps = { config: cfg, router, upstream, ledger, conversations, catalog, context };
+	const overrides = createSessionOverrides();
+	const feedback = createFeedbackStore(db);
+	const turnDeps = { config: cfg, router, upstream, ledger, conversations, catalog, context, overrides, ollamaCostScale };
 
 	// Hot reload: ranking knobs (tiers, filters, escalation, budgets, …) take
 	// effect on the next turn without a restart, because every consumer reads
@@ -377,13 +394,70 @@ export function startServer(cfg: RouterConfig): StartedServer {
 					const parsedDays = rawDays === null ? 7 : Number.parseInt(rawDays, 10);
 					const windowDays = Number.isInteger(parsedDays) ? Math.min(Math.max(parsedDays, 1), 365) : 7;
 					const harnessId = url.searchParams.get("harness") ?? "";
-					return json(buildUsageReport(db, { windowDays, harnessId }));
+					return json(buildUsageReport(db, { windowDays, harnessId, baselines: baselinePrices(cfg.report.baselines, (s) => catalog.find(s)) }));
 				}
 				if (req.method === "GET" && url.pathname === "/v1/router/decisions") {
 					const rawLimit = url.searchParams.get("limit");
 					const parsed = rawLimit === null ? 50 : Number.parseInt(rawLimit, 10);
 					const limit = Number.isInteger(parsed) ? Math.min(Math.max(parsed, 1), 1_000) : 50;
-					return json({ entries: ledger.recentEntries(limit) });
+					// ?session=<omp session id> narrows to one session (/router why).
+					const session = url.searchParams.get("session") ?? "";
+					const entries = session === "" ? ledger.recentEntries(limit) : (ledger.entriesForSession?.(session, limit) ?? []);
+					return json({ entries: entries.map((e) => ({ ...e, feedback: feedback.forLedgerId(e.id) })) });
+				}
+				if (url.pathname === "/v1/router/override") {
+					// Per-session pin / tier overrides from omp. GET shows, POST sets or clears.
+					if (req.method === "GET") {
+						const session = url.searchParams.get("session") ?? "";
+						return json(session === "" ? { overrides: overrides.list() } : { override: overrides.get(session) });
+					}
+					if (req.method === "POST") {
+						const body = (await req.json().catch(() => null)) as Record<string, unknown> | null;
+						const session = typeof body?.ompSessionId === "string" ? body.ompSessionId : "";
+						if (session === "") return wireErrorResponse({ status: 400, code: "invalid_request_error", message: "ompSessionId required" });
+						if (body?.clear === true) {
+							overrides.clear(session);
+							return json({ override: null });
+						}
+						const tier = body?.tier;
+						if (tier !== undefined && tier !== null && !(TIER_ORDER as readonly string[]).includes(String(tier))) {
+							return wireErrorResponse({ status: 400, code: "invalid_request_error", message: `unknown tier ${String(tier)}` });
+						}
+						const slug = body?.slug;
+						if (typeof slug === "string" && slug !== "" && catalog.find(slug) === undefined) {
+							return wireErrorResponse({ status: 404, code: "not_found", message: `no model ${slug} in the catalog` });
+						}
+						const turns = typeof body?.turns === "number" ? body.turns : undefined;
+						const set = overrides.set(session, {
+							...(tier === undefined ? {} : { tier: tier === null ? null : (String(tier) as Tier) }),
+							...(slug === undefined ? {} : { slug: typeof slug === "string" && slug !== "" ? slug : null }),
+							...(turns === undefined ? {} : { turns }),
+						});
+						return json({ override: set });
+					}
+				}
+				if (req.method === "POST" && url.pathname === "/v1/router/feedback") {
+					// A user verdict on the newest routed turn of an omp session.
+					const body = (await req.json().catch(() => null)) as Record<string, unknown> | null;
+					const session = typeof body?.ompSessionId === "string" ? body.ompSessionId : "";
+					const verdict = body?.verdict;
+					if (session === "" || (verdict !== "good" && verdict !== "bad")) {
+						return wireErrorResponse({ status: 400, code: "invalid_request_error", message: "ompSessionId and verdict (good|bad) required" });
+					}
+					const target =
+						typeof body?.ledgerId === "string"
+							? (ledger.recentEntries(1_000).find((e) => e.id === body.ledgerId) ?? null)
+							: (ledger.latestForSession?.(session) ?? null);
+					if (target === null) return wireErrorResponse({ status: 404, code: "not_found", message: "no routed turn for that session yet" });
+					const id = feedback.record({
+						ledgerId: target.id,
+						ompSessionId: session,
+						slug: target.servedSlug ?? target.slug,
+						tier: target.tier,
+						verdict: verdict as Verdict,
+						note: typeof body?.note === "string" ? body.note : "",
+					});
+					return json({ id, ledgerId: target.id, slug: target.servedSlug ?? target.slug, tier: target.tier, verdict });
 				}
 				if (req.method === "GET" && url.pathname === "/health") {
 					const snap = catalog.peek();
@@ -413,6 +487,9 @@ export function startServer(cfg: RouterConfig): StartedServer {
 										usage: ollamaUsage.peek(),
 										// The dashboard's dollar figure: plan share × included credits, when known.
 										meter: ollamaMeter(ollamaUsage.peek(), cfg.ollama.planCreditsUsd),
+										// Ledger vs meter, and how long the credits last at the recent burn.
+										calibration: ollamaUsage.calibration(),
+										runway: ollamaRunway(ollamaMeter(ollamaUsage.peek(), cfg.ollama.planCreditsUsd), ledger.providerSpendSince?.("ollama/", Date.now() - 7 * 86_400_000) ?? 0, ollamaUsage.calibration()?.factor ?? 1),
 										costBias: { configured: cfg.ollama.costBias, effective: catalog.ollamaBias?.() ?? cfg.ollama.costBias, biasUntilUsage: cfg.ollama.biasUntilUsage },
 									},
 						catalog: snap === null

package/src/server/overrides.ts

@@ -0,0 +1,83 @@
+/**
+ * Per-session routing overrides set from omp (`/router pin`, `/router tier`).
+ *
+ * Keyed by the omp session id the embed extension sends as `X-Omp-Session`,
+ * so an override never leaks into another session sharing the router.
+ * Process-local on purpose: an override is a user's momentary intent, not
+ * state to survive a restart. `turns` counts down per committed dispatch;
+ * 0 means until cleared or the entry expires.
+ */
+
+import type { Tier } from "../router/types.ts";
+
+export interface SessionOverride {
+	/** Model to route every turn to, when set. */
+	slug: string | null;
+	/** Tier to classify every turn as, when set. */
+	tier: Tier | null;
+	/** Dispatches left; 0 ⇒ unlimited. */
+	turnsLeft: number;
+	setAtMs: number;
+}
+
+export interface SessionOverrides {
+	get(ompSessionId: string): SessionOverride | null;
+	set(ompSessionId: string, override: { slug?: string | null; tier?: Tier | null; turns?: number }, nowMs?: number): SessionOverride;
+	clear(ompSessionId: string): void;
+	/** A committed dispatch used one turn of the override. */
+	consume(ompSessionId: string): void;
+	/** Every live override, for status. */
+	list(): Array<{ ompSessionId: string } & SessionOverride>;
+}
+
+/** Overrides older than this are forgotten: a session that idled a day is a new session. */
+export const OVERRIDE_TTL_MS = 12 * 60 * 60 * 1000;
+
+export function createSessionOverrides(): SessionOverrides {
+	const map = new Map<string, SessionOverride>();
+	const live = (id: string, nowMs: number): SessionOverride | null => {
+		const o = map.get(id);
+		if (o === undefined) return null;
+		if (nowMs - o.setAtMs > OVERRIDE_TTL_MS) {
+			map.delete(id);
+			return null;
+		}
+		return o;
+	};
+	return {
+		get(id) {
+			if (id === "") return null;
+			const o = live(id, Date.now());
+			return o !== null && (o.slug !== null || o.tier !== null) ? o : null;
+		},
+		set(id, over, nowMs = Date.now()) {
+			const prev = live(id, nowMs) ?? { slug: null, tier: null, turnsLeft: 0, setAtMs: nowMs };
+			const next: SessionOverride = {
+				slug: over.slug === undefined ? prev.slug : over.slug,
+				tier: over.tier === undefined ? prev.tier : over.tier,
+				turnsLeft: over.turns === undefined ? prev.turnsLeft : Math.max(0, Math.floor(over.turns)),
+				setAtMs: nowMs,
+			};
+			map.set(id, next);
+			return next;
+		},
+		clear(id) {
+			map.delete(id);
+		},
+		consume(id) {
+			const o = map.get(id);
+			if (o === undefined || o.turnsLeft === 0) return;
+			o.turnsLeft -= 1;
+			if (o.turnsLeft === 0) map.delete(id);
+		},
+		list() {
+			const now = Date.now();
+			const out: Array<{ ompSessionId: string } & SessionOverride> = [];
+			for (const [id] of map) {
+				const o = live(id, now);
+				if (o !== null) out.push({ ompSessionId: id, ...o });
+			}
+			return out;
+		},
+	};
+}

package/src/server/providers.ts

@@ -12,6 +12,7 @@ import type { CatalogSource } from "../catalog/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { createMultiUpstream } from "../upstream/multi.ts";
 import { createOllamaClient, type OllamaClient } from "../upstream/ollama.ts";
+import { createLedger } from "../cost/ledger.ts";
 import { createOllamaUsageSource, NO_USAGE, type OllamaUsageSource } from "../upstream/ollama-usage.ts";
 import { createOpenRouterClient } from "../upstream/openrouter.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
@@ -24,31 +25,38 @@ export interface Providers {
 	ollama: OllamaClient | null;
 	/** Plan usage reader; inert without a key. */
 	ollamaUsage: OllamaUsageSource;
+	/** Multiplier that brings the ledger's Ollama estimate in line with the plan meter; 1 until calibrated. */
+	ollamaCostScale: () => number;
 }
 
 export function createProviders(cfg: RouterConfig, db: Database, log: Logger = createLogger(cfg.logLevel)): Providers {
 	const openrouter = createOpenRouterClient(cfg);
 	const openrouterCatalog = createCatalog(cfg, openrouter, db);
-	if (!cfg.ollama.enabled) return { upstream: openrouter, catalog: openrouterCatalog, ollama: null, ollamaUsage: NO_USAGE };
+	if (!cfg.ollama.enabled) return { upstream: openrouter, catalog: openrouterCatalog, ollama: null, ollamaUsage: NO_USAGE, ollamaCostScale: () => 1 };
 	// Ollama Cloud is a second upstream ranked in the same catalog: `ollama/…`
 	// slugs dispatch to it, everything else to OpenRouter.
 	const ollama = createOllamaClient(cfg);
 	// Plan usage lives on ollama.com whichever base URL dispatches; it needs the
 	// key, so the daemon path without `/login ollama-cloud` keeps a static bias.
+	const ledgerForCalibration = createLedger(db, cfg);
 	const ollamaUsage = createOllamaUsageSource({
 		apiKey: cfg.ollama.apiKey,
 		pollMs: cfg.ollama.usagePollMs,
 		timeoutMs: Math.min(cfg.ollama.timeoutMs, 15_000),
 		log,
+		// Each poll records the meter beside the ledger's Ollama total, so the
+		// estimate can be scaled to what ollama.com actually bills.
+		calibration: { db, ledgerUsd: () => ledgerForCalibration.providerSpendSince?.("ollama/", 0) ?? 0, planCreditsOverrideUsd: cfg.ollama.planCreditsUsd },
 	});
 	return {
 		upstream: createMultiUpstream(openrouter, ollama),
-		catalog: createCompositeCatalog(openrouterCatalog, createOllamaCatalog(cfg.ollama, log), ollama, {
+		catalog: createCompositeCatalog(openrouterCatalog, createOllamaCatalog(cfg.ollama, log, fetch, db), ollama, {
 			costBias: cfg.ollama.costBias,
 			biasUntilUsage: cfg.ollama.biasUntilUsage,
 			usage: ollamaUsage,
 		}),
 		ollama,
 		ollamaUsage,
+		ollamaCostScale: () => ollamaUsage.calibration()?.factor ?? 1,
 	};
 }