auto-model-router 0.3.3 → 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;
 }
 
 /**
@@ -102,6 +108,26 @@ function wideningOrder(tier: Tier, minTier: Tier, maxTier: Tier): Tier[] {
 	return out;
 }
 
+/** Evidence that an upgrade will stick: the conversation is failing or asked for deep reasoning. */
+function hardSignal(f: Features): boolean {
+	const reasoning: string = f.requestedReasoning ?? "";
+	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[] = [];
@@ -161,6 +187,42 @@ export function select(args: SelectArgs): Decision {
 	// exploration (2c) and candidate building (3) so both agree on the term.
 	const cacheWarm = state.cacheWarmSlug !== null && nowMs - state.cacheWarmAtMs <= cfg.hysteresis.cacheWarmTtlMs;
 
+	// 2a. Cache-aware upgrade confirmation. A low-confidence heuristic upgrade
+	//     from a warm model waits one turn; the next turn's classification
+	//     confirms or forgets it. Measured on 7 days of live traffic: 65 of 67
+	//     moderate→hard upgrades bounced back within 3 turns, 50 of them below
+	//     0.6 confidence, and each paid a cold hard-tier read of a ~120k prompt
+	//     ($17.90 in total against $0.23 for staying warm). Step 4's stay/switch
+	//     comparison never sees these — the warm cheap model is below the new
+	//     tier's floor, so it is not a candidate there. Escalations, explicit
+	//     high reasoning and failing tool loops bypass the wait: those are the
+	//     upgrades that stick.
+	let upgradeDeferred: Tier | null = null;
+	const confirmBelow = cfg.hysteresis.confirmUpgradesBelowConfidence;
+	if (
+		confirmBelow > 0 &&
+		cls.source === "heuristic" &&
+		classification.confidence < confirmBelow &&
+		state.currentTier !== null &&
+		state.currentSlug !== null &&
+		tierIdx(effective) > tierIdx(clampTier(state.currentTier)) &&
+		cacheWarm &&
+		state.cacheWarmSlug === state.currentSlug &&
+		(args.excludeSlugs === undefined || args.excludeSlugs.length === 0) &&
+		!hardSignal(features)
+	) {
+		const held = clampTier(state.currentTier);
+		if (state.upgradeDeferredTier !== undefined && state.upgradeDeferredTier !== null) {
+			reasons.push(`upgrade ${held} → ${effective} confirmed: classified above ${held} on consecutive turns`);
+		} else {
+			reasons.push(
+				`upgrade ${held} → ${effective} deferred one turn: heuristic confidence ${classification.confidence.toFixed(2)} < ${confirmBelow} with ${state.currentSlug} warm`,
+			);
+			upgradeDeferred = effective;
+			effective = held;
+		}
+	}
+
 	// 2b. Context compaction: shrink stale tool output before dispatch when the
 	//     prompt exceeds the token budget (or would overflow the profile window).
 	//     Deterministic and content-only (never removes a message), so downstream
@@ -287,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 =
@@ -300,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,
@@ -308,7 +383,7 @@ export function select(args: SelectArgs): Decision {
 			task: classification.task,
 			snapshot,
 			ledger,
-			cfg,
+			cfg: buildCfg,
 			expectedCompletionTokens: EXPECTED_COMPLETION_TOKENS,
 			warmSlug,
 			relaxLevel,
@@ -322,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;
@@ -375,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
@@ -382,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
@@ -400,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})`,
 				);
 			}
 		}
@@ -417,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) {
@@ -432,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;
@@ -531,5 +629,6 @@ export function select(args: SelectArgs): Decision {
 		reasons,
 		explored,
 		budgetDowngraded,
+		upgradeDeferred,
 	};
 }

package/src/router/state.ts

@@ -32,6 +32,7 @@ interface Row {
 	context_fetched_at_ms: number;
 	compaction_plan: string | null;
 	compaction_plan_tokens: number;
+	upgrade_deferred_tier: string | null;
 	updated_at_ms: number;
 }
 
@@ -53,6 +54,7 @@ function toState(row: Row): ConversationState {
 		contextFetchedAtMs: row.context_fetched_at_ms,
 		compactionPlan: row.compaction_plan === null ? null : (JSON.parse(row.compaction_plan) as CompactionEdit[]),
 		compactionPlanTokens: row.compaction_plan_tokens,
+		upgradeDeferredTier: row.upgrade_deferred_tier as Tier | null,
 		updatedAtMs: row.updated_at_ms,
 	};
 }
@@ -71,10 +73,10 @@ export function createConversationStore(db: Database): ConversationStore {
 		INSERT INTO conversations (
 			key, session_id, turn, current_slug, current_tier, sticky_until_turn,
 			last_prompt_tokens, cache_warm_slug, cache_warm_at_ms,
-			context_version, context_fetched_at_ms, compaction_plan, compaction_plan_tokens, updated_at_ms
+			context_version, context_fetched_at_ms, compaction_plan, compaction_plan_tokens, upgrade_deferred_tier, updated_at_ms
 		) VALUES ($key, $sessionId, $turn, $currentSlug, $currentTier, $stickyUntilTurn,
 			$lastPromptTokens, $cacheWarmSlug, $cacheWarmAtMs,
-			$contextVersion, $contextFetchedAtMs, $compactionPlan, $compactionPlanTokens, $updatedAtMs)
+			$contextVersion, $contextFetchedAtMs, $compactionPlan, $compactionPlanTokens, $upgradeDeferredTier, $updatedAtMs)
 		ON CONFLICT(key) DO UPDATE SET
 			session_id = excluded.session_id,
 			turn = excluded.turn,
@@ -88,6 +90,7 @@ export function createConversationStore(db: Database): ConversationStore {
 			context_fetched_at_ms = excluded.context_fetched_at_ms,
 			compaction_plan = excluded.compaction_plan,
 			compaction_plan_tokens = excluded.compaction_plan_tokens,
+			upgrade_deferred_tier = excluded.upgrade_deferred_tier,
 			updated_at_ms = excluded.updated_at_ms
 	`);
 	// Read-modify-write in JS lost money: an aborted or failed dispatch is still
@@ -137,6 +140,7 @@ export function createConversationStore(db: Database): ConversationStore {
 				$lastPromptTokens: state.lastPromptTokens,
 				$compactionPlan: state.compactionPlan === null ? null : JSON.stringify(state.compactionPlan),
 				$compactionPlanTokens: state.compactionPlanTokens ?? 0,
+				$upgradeDeferredTier: state.upgradeDeferredTier ?? null,
 				$cacheWarmSlug: state.cacheWarmSlug,
 				$cacheWarmAtMs: state.cacheWarmAtMs,
 				$contextVersion: state.contextVersion,

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. */
@@ -186,6 +208,13 @@ export interface ConversationState {
 	compactionPlanTokens?: number;
 	/** When that block was fetched, for the staleness TTL. */
 	contextFetchedAtMs: number;
+	/**
+	 * The tier a low-confidence upgrade was deferred to on the previous turn
+	 * (`hysteresis.confirmUpgradesBelowConfidence`), or null. One-turn memory:
+	 * every turn overwrites it, so a second consecutive upgrade classification
+	 * confirms the switch and anything else forgets it.
+	 */
+	upgradeDeferredTier?: Tier | null;
 	updatedAtMs: number;
 }
 
@@ -270,6 +299,8 @@ export interface Decision {
 	explored: Exploration | null;
 	/** Budget guard forced a cheaper tier than the classifier asked for. */
 	budgetDowngraded: boolean;
+	/** A low-confidence upgrade to this tier was deferred one turn to keep the warm model. */
+	upgradeDeferred: Tier | null;
 }
 
 /** Why a guarded probe rejected an attempt. */
@@ -294,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