auto-model-router 0.2.32 → 0.3.0

package/src/cost/report.ts

@@ -0,0 +1,340 @@
+/**
+ * Usage analytics over the ledger, for `/router report` in omp and the
+ * `auto-model-router report` CLI (and `GET /v1/router/report`).
+ *
+ * Everything here is SQL over the `ledger` table the router already writes;
+ * nothing is sampled or estimated beyond what the rows carry. Costs are the
+ * ledger's own rule: reported when the provider gave one, else the
+ * usage-priced figure the orchestrator computed, else the forecast.
+ */
+
+import type { Database } from "bun:sqlite";
+
+export interface ReportTotals {
+	dispatches: number;
+	conversations: number;
+	spendUsd: number;
+	/** Cached prompt tokens over all prompt tokens, 0-1. */
+	cacheHitRate: number;
+	promptTokens: number;
+	completionTokens: number;
+	escalations: number;
+	failovers: number;
+	errors: number;
+	aborted: number;
+	/** Turns that switched model mid-conversation. */
+	modelSwitches: number;
+}
+
+export interface ReportRow {
+	key: string;
+	dispatches: number;
+	spendUsd: number;
+	/** Share of window spend, 0-1. */
+	share: number;
+	cacheHitRate: number;
+	avgPromptTokens: number;
+	/** Mean time to first token, ms, over streamed non-error rows; null without samples. */
+	avgTtftMs: number | null;
+	/** Completion tokens per second after first token; null without samples. */
+	tokensPerSec: number | null;
+	escalations: number;
+	errors: number;
+}
+
+export interface ModelRow extends ReportRow {
+	provider: string;
+	/** Dispatch counts per tier, e.g. `{ trivial: 12, moderate: 3 }`. */
+	tiers: Record<string, number>;
+}
+
+export interface DayRow {
+	/** UTC calendar day, `YYYY-MM-DD`. */
+	day: string;
+	dispatches: number;
+	spendUsd: number;
+	cacheHitRate: number;
+}
+
+export interface UsageReport {
+	generatedAtMs: number;
+	windowDays: number;
+	sinceMs: number;
+	/** Restricted to one harness when given; empty ⇒ all. */
+	harnessId: string;
+	totals: ReportTotals;
+	providers: ReportRow[];
+	models: ModelRow[];
+	tiers: ReportRow[];
+	days: DayRow[];
+}
+
+const USD = "COALESCE(reported_usd, predicted_usd)";
+const PT = "json_extract(usage, '$.promptTokens')";
+const CT = "json_extract(usage, '$.cachedTokens')";
+const COMP = "json_extract(usage, '$.completionTokens')";
+const PROVIDER = "CASE WHEN slug LIKE 'ollama/%' THEN 'ollama' ELSE 'openrouter' END";
+const STREAMED = "ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL";
+
+const ROW_SELECT = `
+	COUNT(*) AS dispatches,
+	COALESCE(SUM(${USD}), 0) AS spend,
+	COALESCE(SUM(${PT}), 0) AS prompt_tokens,
+	COALESCE(SUM(${CT}), 0) AS cached_tokens,
+	COALESCE(AVG(${PT}), 0) AS avg_prompt_tokens,
+	AVG(CASE WHEN ${STREAMED} THEN ttft_ms END) AS ttft_ms,
+	SUM(CASE WHEN ${STREAMED} AND latency_ms > ttft_ms AND ${COMP} > 0 THEN ${COMP} END) AS ctok_sum,
+	SUM(CASE WHEN ${STREAMED} AND latency_ms > ttft_ms AND ${COMP} > 0 THEN latency_ms - ttft_ms END) AS elapsed_ms,
+	SUM(CASE WHEN escalation_signal IS NOT NULL THEN 1 ELSE 0 END) AS escalations,
+	SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) AS errors`;
+
+interface RawRow {
+	key: string;
+	dispatches: number;
+	spend: number;
+	prompt_tokens: number;
+	cached_tokens: number;
+	avg_prompt_tokens: number;
+	ttft_ms: number | null;
+	ctok_sum: number | null;
+	elapsed_ms: number | null;
+	escalations: number;
+	errors: number;
+}
+
+function toRow(r: RawRow, windowSpend: number): ReportRow {
+	return {
+		key: r.key,
+		dispatches: r.dispatches,
+		spendUsd: r.spend,
+		share: windowSpend > 0 ? r.spend / windowSpend : 0,
+		cacheHitRate: r.prompt_tokens > 0 ? r.cached_tokens / r.prompt_tokens : 0,
+		avgPromptTokens: Math.round(r.avg_prompt_tokens),
+		avgTtftMs: r.ttft_ms === null ? null : Math.round(r.ttft_ms),
+		tokensPerSec: r.elapsed_ms !== null && r.elapsed_ms > 0 && r.ctok_sum !== null ? (r.ctok_sum * 1000) / r.elapsed_ms : null,
+		escalations: r.escalations,
+		errors: r.errors,
+	};
+}
+
+/**
+ * Builds the report for the last `windowDays`. `harnessId` narrows to one
+ * harness (the `X-Omp-Harness` header); empty means everything.
+ */
+export function buildUsageReport(db: Database, opts: { windowDays: number; harnessId?: string; nowMs?: number }): UsageReport {
+	const nowMs = opts.nowMs ?? Date.now();
+	const windowDays = Math.max(1, opts.windowDays);
+	const sinceMs = nowMs - windowDays * 86_400_000;
+	const harnessId = opts.harnessId ?? "";
+	const where = harnessId === "" ? "created_at_ms >= $since" : "created_at_ms >= $since AND harness_id = $harness";
+	const bind = harnessId === "" ? { $since: sinceMs } : { $since: sinceMs, $harness: harnessId };
+
+	const t = db
+		.query(
+			`SELECT COUNT(*) AS dispatches,
+				COUNT(DISTINCT conversation_key) AS conversations,
+				COALESCE(SUM(${USD}), 0) AS spend,
+				COALESCE(SUM(${PT}), 0) AS prompt_tokens,
+				COALESCE(SUM(${CT}), 0) AS cached_tokens,
+				COALESCE(SUM(${COMP}), 0) AS completion_tokens,
+				SUM(CASE WHEN escalation_signal IS NOT NULL THEN 1 ELSE 0 END) AS escalations,
+				SUM(CASE WHEN instr(reasons, 'failover:') > 0 THEN 1 ELSE 0 END) AS failovers,
+				SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) AS errors,
+				SUM(CASE WHEN error = 'request aborted' THEN 1 ELSE 0 END) AS aborted
+			 FROM ledger WHERE ${where}`,
+		)
+		.get(bind) as {
+		dispatches: number;
+		conversations: number;
+		spend: number;
+		prompt_tokens: number;
+		cached_tokens: number;
+		completion_tokens: number;
+		escalations: number | null;
+		failovers: number | null;
+		errors: number | null;
+		aborted: number | null;
+	};
+
+	// Model switches: consecutive non-wasted rows of one conversation on
+	// different slugs. Computed in JS over a slim projection; the window is
+	// bounded, and SQLite window functions would make the query less portable.
+	const seq = db
+		.query(`SELECT conversation_key AS ck, slug FROM ledger WHERE ${where} AND wasted = 0 ORDER BY conversation_key, created_at_ms`)
+		.all(bind) as { ck: string; slug: string }[];
+	let switches = 0;
+	for (let i = 1; i < seq.length; i++) {
+		const a = seq[i - 1]!;
+		const b = seq[i]!;
+		if (a.ck === b.ck && a.slug !== b.slug) switches++;
+	}
+
+	const windowSpend = t.spend;
+	const providers = (
+		db.query(`SELECT ${PROVIDER} AS key, ${ROW_SELECT} FROM ledger WHERE ${where} GROUP BY key ORDER BY spend DESC`).all(bind) as RawRow[]
+	).map((r) => toRow(r, windowSpend));
+
+	const modelRows = db
+		.query(`SELECT COALESCE(served_slug, slug) AS key, ${ROW_SELECT} FROM ledger WHERE ${where} GROUP BY key ORDER BY spend DESC`)
+		.all(bind) as RawRow[];
+	const tierMix = db
+		.query(`SELECT COALESCE(served_slug, slug) AS key, tier, COUNT(*) AS n FROM ledger WHERE ${where} GROUP BY key, tier`)
+		.all(bind) as { key: string; tier: string; n: number }[];
+	const mixByModel = new Map<string, Record<string, number>>();
+	for (const m of tierMix) {
+		const rec = mixByModel.get(m.key) ?? {};
+		rec[m.tier] = m.n;
+		mixByModel.set(m.key, rec);
+	}
+	const models: ModelRow[] = modelRows.map((r) => ({
+		...toRow(r, windowSpend),
+		provider: r.key.startsWith("ollama/") ? "ollama" : "openrouter",
+		tiers: mixByModel.get(r.key) ?? {},
+	}));
+
+	const tiers = (
+		db.query(`SELECT tier AS key, ${ROW_SELECT} FROM ledger WHERE ${where} GROUP BY key ORDER BY spend DESC`).all(bind) as RawRow[]
+	).map((r) => toRow(r, windowSpend));
+
+	const days = (
+		db
+			.query(
+				`SELECT date(created_at_ms / 1000, 'unixepoch') AS day, COUNT(*) AS dispatches, COALESCE(SUM(${USD}), 0) AS spend,
+					COALESCE(SUM(${PT}), 0) AS prompt_tokens, COALESCE(SUM(${CT}), 0) AS cached_tokens
+				 FROM ledger WHERE ${where} GROUP BY day ORDER BY day`,
+			)
+			.all(bind) as { day: string; dispatches: number; spend: number; prompt_tokens: number; cached_tokens: number }[]
+	).map((d) => ({
+		day: d.day,
+		dispatches: d.dispatches,
+		spendUsd: d.spend,
+		cacheHitRate: d.prompt_tokens > 0 ? d.cached_tokens / d.prompt_tokens : 0,
+	}));
+
+	return {
+		generatedAtMs: nowMs,
+		windowDays,
+		sinceMs,
+		harnessId,
+		totals: {
+			dispatches: t.dispatches,
+			conversations: t.conversations,
+			spendUsd: t.spend,
+			cacheHitRate: t.prompt_tokens > 0 ? t.cached_tokens / t.prompt_tokens : 0,
+			promptTokens: t.prompt_tokens,
+			completionTokens: t.completion_tokens,
+			escalations: t.escalations ?? 0,
+			failovers: t.failovers ?? 0,
+			errors: t.errors ?? 0,
+			aborted: t.aborted ?? 0,
+			modelSwitches: switches,
+		},
+		providers,
+		models,
+		tiers,
+		days,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Rendering (shared by the omp command and the CLI)
+// ---------------------------------------------------------------------------
+
+const usd = (v: number): string => (v >= 1 ? `$${v.toFixed(2)}` : `$${v.toFixed(4)}`);
+const pct = (v: number): string => `${(v * 100).toFixed(0)}%`;
+const num = (v: number): string => v.toLocaleString("en-US");
+const ms = (v: number | null): string => (v === null ? "–" : v >= 1000 ? `${(v / 1000).toFixed(1)}s` : `${v}ms`);
+const tps = (v: number | null): string => (v === null ? "–" : `${v.toFixed(0)} tok/s`);
+
+/** One aligned table of a report: header row, then data rows. */
+export interface ReportTable {
+	/** Stable id: `providers` | `models` | `tiers` | `days`. */
+	id: string;
+	title: string;
+	headers: string[];
+	rows: string[][];
+}
+
+/** Everything a renderer needs, already formatted: summary lines and tables. */
+export interface ReportView {
+	/** `last 7d · harness omp · 2026-09-06 14:18Z`. */
+	heading: string;
+	summary: string[];
+	tables: ReportTable[];
+}
+
+/**
+ * Column-aligns a table into fixed-width lines: header, rule, rows. The first
+ * column is left-aligned, the rest right-aligned. Cells are plain text, so
+ * the caller can style whole lines without breaking the alignment.
+ */
+export function formatTable(headers: string[], rows: string[][]): string[] {
+	const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+	const line = (cells: string[]): string => cells.map((c, i) => (i === 0 ? c.padEnd(widths[i]!) : c.padStart(widths[i]!))).join("  ");
+	return [line(headers), line(widths.map((w) => "-".repeat(w))), ...rows.map(line)];
+}
+
+/** Formats a report into summary lines and tables, shared by every renderer. */
+export function reportView(r: UsageReport, opts: { maxModels?: number } = {}): ReportView {
+	const maxModels = opts.maxModels ?? 12;
+	const t = r.totals;
+	const heading = `last ${r.windowDays}d${r.harnessId === "" ? "" : ` · harness ${r.harnessId}`} · ${new Date(r.generatedAtMs).toISOString().slice(0, 16).replace("T", " ")}Z`;
+	const summary = [
+		`spend ${usd(t.spendUsd)} over ${num(t.dispatches)} dispatches in ${num(t.conversations)} conversations · ${usd(t.dispatches > 0 ? t.spendUsd / t.dispatches : 0)}/dispatch`,
+		`prompt ${num(t.promptTokens)} tok (cache hit ${pct(t.cacheHitRate)}) · completion ${num(t.completionTokens)} tok · switches ${num(t.modelSwitches)} · escalations ${num(t.escalations)} · failovers ${num(t.failovers)} · errors ${num(t.errors)} (${num(t.aborted)} aborted)`,
+	];
+	const tables: ReportTable[] = [];
+	if (r.providers.length > 0) {
+		tables.push({
+			id: "providers",
+			title: "providers",
+			headers: ["provider", "dispatches", "spend", "share", "cache", "ttft", "speed", "esc", "err"],
+			rows: r.providers.map((p) => [p.key, num(p.dispatches), usd(p.spendUsd), pct(p.share), pct(p.cacheHitRate), ms(p.avgTtftMs), tps(p.tokensPerSec), num(p.escalations), num(p.errors)]),
+		});
+	}
+	if (r.models.length > 0) {
+		tables.push({
+			id: "models",
+			title: `models (top ${Math.min(maxModels, r.models.length)} of ${r.models.length} by spend)`,
+			headers: ["model", "dispatches", "spend", "share", "cache", "ttft", "speed", "tiers"],
+			rows: r.models.slice(0, maxModels).map((m) => [
+				m.key,
+				num(m.dispatches),
+				usd(m.spendUsd),
+				pct(m.share),
+				pct(m.cacheHitRate),
+				ms(m.avgTtftMs),
+				tps(m.tokensPerSec),
+				Object.entries(m.tiers)
+					.sort((a, b) => b[1] - a[1])
+					.map(([k, v]) => `${k}:${v}`)
+					.join(" "),
+			]),
+		});
+	}
+	if (r.tiers.length > 0) {
+		tables.push({
+			id: "tiers",
+			title: "tiers",
+			headers: ["tier", "dispatches", "spend", "share", "cache", "avg prompt", "esc"],
+			rows: r.tiers.map((x) => [x.key, num(x.dispatches), usd(x.spendUsd), pct(x.share), pct(x.cacheHitRate), num(x.avgPromptTokens), num(x.escalations)]),
+		});
+	}
+	if (r.days.length > 1) {
+		tables.push({
+			id: "days",
+			title: "by day (UTC)",
+			headers: ["day", "dispatches", "spend", "cache"],
+			rows: r.days.map((d) => [d.day, num(d.dispatches), usd(d.spendUsd), pct(d.cacheHitRate)]),
+		});
+	}
+	return { heading, summary, tables };
+}
+
+/** Plain-text rendering: fixed-width tables, no markup, fits a TUI panel. */
+export function renderUsageReport(r: UsageReport, opts: { maxModels?: number } = {}): string {
+	const v = reportView(r, opts);
+	const out: string[] = [`auto-model-router · ${v.heading}`, "", ...v.summary];
+	for (const t of v.tables) out.push("", t.title, ...formatTable(t.headers, t.rows));
+	return out.join("\n");
+}

package/src/cost/types.ts

@@ -5,9 +5,14 @@
  *  - **predicted**: our arithmetic over the catalog, computed *before* dispatch.
  *    Drives routing and budget enforcement.
  *  - **reported**: `usage.cost` returned by OpenRouter, authoritative after the
- *    fact. Drives the ledger, `stats`, and prediction-error calibration.
+ *    fact. Drives the ledger, `stats`, and prediction-error calibration. A
+ *    provider that returns usage but no cost (Ollama) has its ACTUAL tokens
+ *    priced at the catalog rate and recorded here — still after the fact, and
+ *    still not the forecast.
  */
 
+import type { CatalogModel } from "../catalog/types.ts";
+
 /** Token counts for one upstream generation. */
 export interface UsageCounts {
 	/** Total prompt tokens, *including* `cachedTokens` (OpenAI/OpenRouter convention). */
@@ -135,6 +140,12 @@ export interface LedgerEntry {
 	error: string | null;
 	/** Prompt tokens removed by compaction before dispatch. 0 when none. NULL before v12. */
 	promptTokensSaved: number;
+	/**
+	 * The catalog model that served, for the cost split. The ledger can price
+	 * OpenRouter slugs from its own cached catalog payload; a model from another
+	 * provider (Ollama) exists only in memory, so the orchestrator hands it over.
+	 */
+	priceModel?: CatalogModel;
 }
 
 /** Rolling blended rate used to keep omp's cost display honest. */
@@ -183,6 +194,18 @@ export interface ModelLatency {
 	tokensPerSec: number;
 }
 
+export interface LedgerSignals {
+	trust: ModelTrust | null;
+	latency: ModelLatency | null;
+}
+
+/** Measured price of a probe escalation: what the retry billed per prompt token of the failed turn. */
+export interface EscalationCost {
+	usdPerPromptToken: number;
+	samples: number;
+	windowDays: number;
+}
+
 export interface Ledger {
 	record(entry: LedgerEntry): void;
 	/** Total reported (or predicted, when reported is null) spend for a conversation. */
@@ -203,6 +226,15 @@ export interface Ledger {
 	 * how fast the body streams once it starts.
 	 */
 	latency(slug: string, harnessId?: string): ModelLatency | null;
+	/** Batch trust and latency for one candidate set; one query per signal kind. Optional — callers can fall back to per-slug calls. */
+	signals?(slugs: readonly string[], harnessId?: string): Map<string, LedgerSignals>;
+	/**
+	 * What an escalated retry actually bills per prompt token, measured over
+	 * the last `windowDays` of attempt > 0 rows. Null until enough escalated
+	 * attempts exist to measure. Optional so fakes need not implement it; the
+	 * escalation-cost term in candidate scoring is inert without it.
+	 */
+	escalationCost?(windowDays: number): EscalationCost | null;
 	/** Observed chars-per-token ratio for a tokenizer family; null until calibrated. */
 	tokenRatio(tokenizer: string): number | null;
 	recentEntries(limit: number): LedgerEntry[];

package/src/index.ts

@@ -12,6 +12,7 @@ import { parseArgv } from "./cli/args.ts";
 import { configCommand } from "./cli/config-cmd.ts";
 import { explainCommand } from "./cli/explain.ts";
 import { modelsCommand } from "./cli/models.ts";
+import { reportCommand } from "./cli/report.ts";
 import { serveCommand } from "./cli/serve.ts";
 import { statsCommand } from "./cli/stats.ts";
 
@@ -21,6 +22,7 @@ Usage: auto-model-router <command> [options]
 
   serve      Run the router as a standalone process (for non-omp harnesses)
   stats      Show routed spend, per-model share, and escalation rates
+  report     Usage analytics: providers, models, tiers, cost, speed, cache hit rate
   models     Show what each complexity tier would consider, and why
   explain    Route a saved request without dispatching it, and explain the decision
   config     Interactive wizard over the router's own config.yml
@@ -33,6 +35,7 @@ Global options:
 
   serve    --port <n>  --host <addr>  --log <level>
   stats    --days <n>  --json
+  report   --days <n>  --harness <id>  --json
   models   --tier <trivial|simple|moderate|hard>  --limit <n>  --json
   explain  --file <request.json>  --json          (reads stdin when --file is absent)
   config   --print  --write  --path <models.yml>  --config <router-config.yml>
@@ -67,14 +70,8 @@ async function main(): Promise<number> {
 		case "stats":
 			await statsCommand(args);
 			return 0;
-		case "models":
-
-		case "serve":
-			// Resolves once listening; the server itself keeps the loop alive.
-			await serveCommand(args);
-			return 0;
-		case "stats":
-			await statsCommand(args);
+		case "report":
+			await reportCommand(args);
 			return 0;
 		case "models":
 			await modelsCommand(args);

package/src/router/candidates.ts

@@ -7,12 +7,20 @@
 import type { CatalogModel, CatalogSnapshot } from "../catalog/types.ts";
 import type { FilterConfig, QualityAxis, RouterConfig } from "../config/types.ts";
 import { forecast, priceAt } from "../cost/forecast.ts";
-import type { Ledger, ModelLatency } from "../cost/types.ts";
+import type { Ledger, LedgerSignals, ModelLatency } from "../cost/types.ts";
 import type { NormRequest } from "../wire/types.ts";
 import { effectivePriceCeiling, effectiveQualityFloor, tierPlanFor } from "./tier-plan.ts";
 import type { Candidate, Features, Rejection, TaskType, Tier } from "./types.ts";
 
 export interface BuildCandidatesArgs {
+	/** Pre-fetched trust/latency signals for all candidate slugs. When provided, buildCandidates uses these instead of per-slug ledger calls. */
+	signals?: Map<string, LedgerSignals>;
+	/**
+	 * Measured cost of an escalated retry per prompt token (from
+	 * `Ledger.escalationCost`). With `filters.escalationCostWeight` > 0 a
+	 * model's measured escalation rate is priced at this; absent ⇒ term inert.
+	 */
+	escalationUsdPerPromptToken?: number;
 	req: NormRequest;
 	features: Features;
 	tier: Tier;
@@ -68,6 +76,16 @@ function resolveQuality(model: CatalogModel, axis: QualityAxis): { score: number
 /** Neutral trust prior for models our ledger has never observed. */
 const UNMEASURED_TRUST = 0.9;
 
+/**
+ * Prior on the escalation rate, as pseudo-counts: an unobserved model is
+ * assumed to escalate ESCALATION_PRIOR times in ESCALATION_PRIOR_N attempts
+ * (0.25%), so a new cheap model is not priced out before it has been tried,
+ * and a model with a handful of attempts is pulled toward that rather than
+ * toward 0% or 100%.
+ */
+const ESCALATION_PRIOR = 0.05;
+const ESCALATION_PRIOR_N = 20;
+
 /** Excess-ratio cap so one very slow model cannot be penalised into oblivion. */
 const LATENCY_EXCESS_CAP = 3;
 
@@ -230,8 +248,14 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
+		// Use pre-fetched signals when available (batch lookup, one query per
+		// signal kind for the entire candidate set instead of one per model).
+		// Falls back to per-slug calls when signals is not provided (e.g. tests).
+		const signals = args.signals;
 		const trust =
-			ledger?.trust(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null;
+			signals?.get(slug)?.trust ??
+			ledger?.trust(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ??
+			null;
 		if (!relaxTrust && trust !== null && trust.attempts >= filters.minTrustSamples && trust.successRate < filters.minTrust) {
 			rejected.push({
 				slug,
@@ -249,7 +273,9 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		// cold-start turns to accumulate samples. Relaxed with trust in rescue.
 		const needLatency = filters.latencyWeight > 0 || filters.maxExpectedWaitMs !== undefined;
 		const latency = needLatency
-			? (ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null)
+			? (signals?.get(slug)?.latency ??
+				ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ??
+				null)
 			: null;
 		if (
 			!relaxTrust &&
@@ -295,7 +321,25 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		// for slowness (TTFT over the reference). qualityExponent 0 makes this
 		// "cheapest above the floor"; the floor does the quality work.
 		const latencyMult = latencyMultiplier(latency, filters, expectedCompletionTokens);
-		const effectiveUsd = (fc.expectedUsd / Math.max(trustScore, 0.5)) * latencyMult;
+		// Escalation-cost term: the trust divisor prices a failure as a retry of
+		// THIS model, but a probe escalation re-dispatches the whole prompt on
+		// the next tier's model — measured at ~700x a cheap model's own turn cost.
+		// Price the measured rate at what an escalated retry actually bills.
+		const escalationRate =
+			trust !== null && trust.attempts > 0
+				? (trust.escalations + ESCALATION_PRIOR) / (trust.attempts + ESCALATION_PRIOR_N)
+				: ESCALATION_PRIOR / ESCALATION_PRIOR_N;
+		const escalationUsd =
+			filters.escalationCostWeight > 0 && args.escalationUsdPerPromptToken !== undefined
+				? filters.escalationCostWeight * escalationRate * args.escalationUsdPerPromptToken * features.promptTokens
+				: 0;
+		// Provider bias: an Ollama plan's included credits are money already
+		// spent, so an operator may value them below list price in ranking. The
+		// ledger still records list price.
+		// The snapshot carries the LIVE bias (credit-aware); the static config
+		// value is the fallback for snapshots built without one.
+		const providerBias = snapshot.providerBias?.[model.provider] ?? (model.provider === "ollama" ? cfg.ollama.costBias : 1);
+		const effectiveUsd = (fc.expectedUsd / Math.max(trustScore, 0.5) + escalationUsd) * latencyMult * providerBias;
 		// Score is assigned in a SECOND PASS below: both qualityNormalization and
 		// capabilityFloorUsd are properties of the candidate SET, not of one
 		// model, so no per-model value can be computed here. Placeholder only.
@@ -310,6 +354,10 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 				: `trust ${trustScore.toFixed(2)} over ${trust.attempts} attempts`,
 			`expected $${fc.expectedUsd.toFixed(6)}`,
 		];
+		if (escalationUsd > 0) {
+			reasons.push(`escalation risk +$${escalationUsd.toFixed(6)} (rate ${(escalationRate * 100).toFixed(2)}% × measured retry cost)`);
+		}
+		if (providerBias !== 1) reasons.push(`provider bias ×${providerBias} (ollama.costBias, plan credits remaining)`);
 		if (latencyMult > 1 && latency !== null) {
 			reasons.push(
 				`latency penalty ×${latencyMult.toFixed(2)} (ttft ${Math.round(latency.ttftMs)}ms, ${latency.tokensPerSec.toFixed(0)} tok/s over ${latency.samples} samples)`,

package/src/router/classify.ts

@@ -23,7 +23,11 @@ import type { Classification, Features, TaskType, Tier } from "./types.ts";
  *  - Failure signals cost money twice: a cheap model that flounders gets
  *    escalated and the turn is paid for twice. So a failed tool result, a
  *    repeated tool call, complexity keywords, and an explicit reasoning
- *    request carry the dominant POSITIVE weights.
+ *    request carry the dominant POSITIVE weights — on a FRESH turn. On a
+ *    tool-result continuation the failed-tool and circular-call weights are
+ *    damped by `classifier.mechanicalRetryFactor` (0.2 shipped), because a
+ *    mechanical retry loop was buying the hard tier for work that never
+ *    needed it; there they are a nudge, not a driver.
  */
 const BASE = 0.3;
 const W_TOOL_CONTINUATION = -0.28; // dominant negative
@@ -31,8 +35,8 @@ const W_COMPLEXITY_KEYWORD = 0.1;
 const CAP_COMPLEXITY = 0.3;
 const W_TRIVIALITY_KEYWORD = -0.09;
 const CAP_TRIVIALITY = -0.27;
-const W_TOOL_FAILED = 0.26; // dominant positive: retry loops are expensive
-const W_CIRCULAR_LOOP = 0.24; // a re-issued (circular) tool call: the model is stuck
+const W_TOOL_FAILED = 0.26; // dominant positive on a fresh turn; damped on continuations
+const W_CIRCULAR_LOOP = 0.24; // a re-issued (circular) tool call: the model is stuck; damped on continuations
 const W_TERSE = -0.1;
 const W_CODE_BLOCK = 0.04;
 const CAP_CODE = 0.08;
@@ -118,8 +122,25 @@ export function scoreHeuristic(f: Features, cfg: RouterConfig): Classification {
 		Math.max(f.trivialityKeywords.length * W_TRIVIALITY_KEYWORD, CAP_TRIVIALITY),
 		`triviality keywords [${f.trivialityKeywords.join(", ")}]`,
 	);
-	if (f.lastToolFailed) add(W_TOOL_FAILED, "last tool result failed");
-	if (f.circularToolCall) add(W_CIRCULAR_LOOP, "circular tool call (re-issued a prior call; stuck)");
+	// Stuck-loop signals on a tool-result continuation are damped: a retry after
+	// a failed call is the MOST mechanical turn there is (no new user intent,
+	// same prompt prefix, the harness just re-asks), and the flat weight let an
+	// automated retry loop buy the hard tier ($7.02 of one measured day vs $0.19
+	// for the same rows as moderate picks). A circular call measured the same
+	// way: hard escalations driven by it NEVER shortened the loop (chains from
+	// hard and from moderate both averaged 5.74 turns) — the loop ends when the
+	// underlying state changes, not because a pricier model re-read the same
+	// result. Off a continuation (a fresh user turn, the failure the human just
+	// saw) both keep their full weight: that genuinely changes what the turn
+	// needs.
+	const factor = cfg.classifier.mechanicalRetryFactor;
+	const damped = f.isToolResultContinuation && factor < 1;
+	const damp = (w: number): number => (damped ? w * factor : w);
+	const dampNote = damped ? ` (mechanical retry, damped x${factor})` : "";
+	if (f.lastToolFailed) add(damp(W_TOOL_FAILED), `last tool result failed${dampNote}`);
+	if (f.circularToolCall) {
+		add(damp(W_CIRCULAR_LOOP), damped ? `circular tool call${dampNote}` : "circular tool call (re-issued a prior call; stuck)");
+	}
 	const rw = reasoningWeight(f.requestedReasoning, cfg);
 	if (rw > 0) add(rw, `client requested reasoning=${f.requestedReasoning ?? ""}`);
 	if (f.isTerseInstruction) add(W_TERSE, "terse instruction");
@@ -137,7 +158,13 @@ export function scoreHeuristic(f: Features, cfg: RouterConfig): Classification {
 			`autonomous loop depth ${f.toolLoopDepth} (sustained task)`,
 		);
 	}
-	if (f.hasImages) add(W_IMAGES, "image input");
+	// Only an image the human JUST supplied is visual work. A screenshot that
+	// entered the conversation long ago rides along in every later mechanical
+	// continuation (measured: 5,603 of ~9,000 heuristic rows in a week carried
+	// one, and 339 of them sat a tier higher on this +0.04 alone). Capability —
+	// the served model must still accept image input — is enforced separately
+	// on `req.hasImages` in candidate selection, exactly as `classifyTask` does.
+	if (f.hasNewImage) add(W_IMAGES, "new image input");
 	if (f.toolCount > 0) add(W_TOOLS_OFFERED, `${f.toolCount} tools offered`);
 
 	score = Math.min(1, Math.max(0, score));

package/src/router/features.ts

@@ -170,9 +170,21 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 		}
 	}
 
+	// The tool run to judge for failure: the trailing run on a continuation, or
+	// the run that sits immediately behind the newest user turn — the failure
+	// the human just saw and is now responding to. The classifier weights the
+	// two differently (a mechanical retry is damped, a user-visible failure is
+	// not), so the second case has to be detectable here or that branch is dead.
 	let lastToolFailed = false;
+	let failureScanFrom = -1;
 	if (isToolResultContinuation) {
-		scanResults: for (let i = messages.length - 1; i >= 0; i--) {
+		failureScanFrom = messages.length - 1;
+	} else if (tail?.role === "user") {
+		const start = trailingRunStart(messages, (m) => m.role === "user");
+		if (messages[start - 1]?.role === "tool") failureScanFrom = start - 1;
+	}
+	if (failureScanFrom >= 0) {
+		scanResults: for (let i = failureScanFrom; i >= 0; i--) {
 			const m = messages[i];
 			if (m === undefined || m.role !== "tool") break;
 			for (const re of TOOL_FAILURE_MARKERS) {