auto-model-router 0.1.3 → 0.2.0

package/src/eval/run.ts

@@ -0,0 +1,126 @@
+/**
+ * Runs the eval suite against models via a text completer, aggregating each
+ * model's grades into a raw mean per axis. IO is injected as `Completer` so the
+ * runner is unit-testable with a canned model and never touches the network in
+ * tests. A completion that throws is folded in as an empty reply (grade 0) — a
+ * model that errors on a turn genuinely failed it.
+ */
+
+import type { QualityAxis } from "../config/types.ts";
+import type { Judge } from "./judge.ts";
+import { EVAL_TASKS, JUDGED_TASKS, type EvalTask, type JudgedTask } from "./tasks.ts";
+
+export interface ChatMessage {
+	role: "system" | "user" | "assistant";
+	content: string;
+}
+
+export type Completer = (slug: string, messages: ChatMessage[]) => Promise<string>;
+
+export interface AxisScore {
+	/** Sum of grades over this axis's tasks. */
+	sum: number;
+	/** Task count on this axis. */
+	n: number;
+}
+
+export interface EvalResult {
+	slug: string;
+	axes: Record<QualityAxis, AxisScore>;
+	/** Tasks whose completion threw (dispatch failure). Excluded from `axes`. */
+	errors: number;
+}
+
+function messagesFor(task: { system?: string; user: string }): ChatMessage[] {
+	const msgs: ChatMessage[] = [];
+	if (task.system !== undefined) msgs.push({ role: "system", content: task.system });
+	msgs.push({ role: "user", content: task.user });
+	return msgs;
+}
+
+export interface RunEvalArgs {
+	slugs: readonly string[];
+	complete: Completer;
+	/** Objective, deterministically-graded tasks. Defaults to the built-in suite. */
+	tasks?: readonly EvalTask[];
+	/** Open-ended tasks scored by `judge`. Ignored unless `judge` is supplied. */
+	judged?: readonly JudgedTask[];
+	/** LLM judge for the open-ended tasks. Absent ⇒ judged tasks are skipped entirely. */
+	judge?: Judge;
+	/** How many models to score at once. Default 4; bounded so upstream is not flooded. */
+	concurrency?: number;
+	/** Called as each model finishes, for progress logging. */
+	onProgress?: (result: EvalResult, done: number, total: number) => void;
+}
+
+async function scoreModel(slug: string, args: RunEvalArgs): Promise<EvalResult> {
+	const tasks = args.tasks ?? EVAL_TASKS;
+	const judge = args.judge;
+	const judged = judge !== undefined ? (args.judged ?? JUDGED_TASKS) : [];
+	const axes: Record<QualityAxis, AxisScore> = {
+		coding: { sum: 0, n: 0 },
+		intelligence: { sum: 0, n: 0 },
+		agentic: { sum: 0, n: 0 },
+	};
+	let errors = 0;
+	type Outcome = { axis: QualityAxis; grade: number; ok: boolean };
+	// A THROW (or an unscorable judge reply) means the turn produced no usable
+	// observation — NOT a score of 0, which would poison an anchor whose model is
+	// merely unavailable. Such turns are tallied as errors and excluded.
+	const objective: Outcome[] = await Promise.all(
+		tasks.map(async (task) => {
+			try {
+				const text = await args.complete(slug, messagesFor(task));
+				return { axis: task.axis, grade: task.grade(text), ok: true };
+			} catch {
+				return { axis: task.axis, grade: 0, ok: false };
+			}
+		}),
+	);
+	const judgedOutcomes: Outcome[] =
+		judge === undefined
+			? []
+			: await Promise.all(
+					judged.map(async (task) => {
+						try {
+							const answer = await args.complete(slug, messagesFor(task));
+							const score = await judge(task, answer);
+							return score === null ? { axis: task.axis, grade: 0, ok: false } : { axis: task.axis, grade: score, ok: true };
+						} catch {
+							return { axis: task.axis, grade: 0, ok: false };
+						}
+					}),
+				);
+	for (const o of [...objective, ...judgedOutcomes]) {
+		if (!o.ok) {
+			errors += 1;
+			continue;
+		}
+		axes[o.axis].sum += o.grade;
+		axes[o.axis].n += 1;
+	}
+	return { slug, axes, errors };
+}
+
+export async function runEval(args: RunEvalArgs): Promise<EvalResult[]> {
+	const total = args.slugs.length;
+	const concurrency = Math.max(1, args.concurrency ?? 4);
+	const results: EvalResult[] = new Array(total);
+	let next = 0;
+	let done = 0;
+	// A fixed pool of workers pulls the next model index until the list is drained,
+	// so at most `concurrency` models are in flight at once.
+	const worker = async (): Promise<void> => {
+		for (;;) {
+			const i = next++;
+			if (i >= total) return;
+			const slug = args.slugs[i]!;
+			const r = await scoreModel(slug, args);
+			results[i] = r;
+			done += 1;
+			args.onProgress?.(r, done, total);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(concurrency, total) }, worker));
+	return results;
+}

package/src/eval/tasks.ts

@@ -0,0 +1,272 @@
+/**
+ * The curated eval suite: small, representative coding-agent turns with fully
+ * deterministic graders. Not ledger replay — the ledger stores no prompts — but
+ * an on-distribution stand-in: instruction-following, structured output, tool
+ * selection, and checkable answers, the things a tier gate actually cares about.
+ *
+ * Each task is tagged with the quality AXIS it exercises, so a model's raw score
+ * on an axis is the mean grade over that axis's tasks. Add tasks freely; the
+ * runner and calibration are agnostic to the count.
+ */
+
+import type { QualityAxis } from "../config/types.ts";
+import { answerScore, extractJson, jsonField, multiAnswerCoverage, tokenCoverage } from "./grade.ts";
+
+export interface EvalTask {
+	id: string;
+	axis: QualityAxis;
+	system?: string;
+	user: string;
+	/** Deterministic proxy grade in [0, 1]. */
+	grade: (output: string) => number;
+}
+
+/** An open-ended task with no deterministic grader; scored 0-1 by an LLM judge. */
+export interface JudgedTask {
+	id: string;
+	axis: QualityAxis;
+	system?: string;
+	user: string;
+	/** Optional strong answer given to the judge as a reference. */
+	reference?: string;
+}
+
+const JSON_ONLY = "Reply with ONLY the requested content and no prose, code fences, or explanation.";
+
+export const EVAL_TASKS: readonly EvalTask[] = [
+	// ---- coding: does it produce correct, well-formed code/answers ----
+	{
+		id: "coding/sum-fn",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "Write a TypeScript function `sum(a: number, b: number): number` that returns their sum.",
+		grade: (o) => tokenCoverage(o, ["function sum", "a + b"]) === 1 ? 1 : tokenCoverage(o, ["sum", "a + b"]),
+	},
+	{
+		id: "coding/sort-output",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "What is the result of `[3, 1, 2].sort((a, b) => a - b)`? Reply with only the array.",
+		grade: (o) => answerScore(o, "[1, 2, 3]") === 1 ? 1 : answerScore(o, "[1,2,3]"),
+	},
+	{
+		id: "coding/map-double",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "Complete this to double each element: `const doubled = nums.map(n => ___)`. Reply with only the lambda body that replaces ___.",
+		grade: (o) => tokenCoverage(o, ["n", "*", "2"]),
+	},
+	{
+		id: "coding/primes-json",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "Reply with only a JSON array of the first five prime numbers.",
+		grade: (o) => {
+			const j = extractJson(o);
+			return Array.isArray(j) && JSON.stringify(j) === JSON.stringify([2, 3, 5, 7, 11]) ? 1 : 0;
+		},
+	},
+
+	// ---- intelligence: reasoning + constraint following ----
+	{
+		id: "intel/decimal-compare",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: "Which is larger, 9.11 or 9.9? Reply with just the number.",
+		grade: (o) => answerScore(o, "9.9"),
+	},
+	{
+		id: "intel/syllogism",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: "If all Bloops are Razzies and all Razzies are Lazzies, are all Bloops Lazzies? Reply yes or no.",
+		grade: (o) => answerScore(o, "yes"),
+	},
+	{
+		id: "intel/arith-json",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: 'Reply with only a JSON object {"answer": n} where n = 2 + 2 * 3.',
+		grade: (o) => (jsonField(extractJson(o), "answer") === 8 ? 1 : 0),
+	},
+	{
+		id: "intel/bat-ball",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: "A bat and a ball cost $1.10 together. The bat costs $1.00 more than the ball. How many cents does the ball cost? Reply with just the number.",
+		grade: (o) => answerScore(o, "5"),
+	},
+
+	// ---- agentic: tool selection + structured output (as text, since complete() returns text) ----
+	{
+		id: "agentic/single-tool",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: 'Tools: read_file(path). To read src/main.ts, emit only the JSON call: {"tool": <name>, "args": {"path": <path>}}.',
+		grade: (o) => {
+			const j = extractJson(o);
+			return jsonField(j, "tool") === "read_file" && jsonField(jsonField(j, "args"), "path") === "src/main.ts" ? 1 : 0;
+		},
+	},
+	{
+		id: "agentic/tool-choice",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: 'Tools: read_file(path), write_file(path, content). To save the text "hello" into out.txt, emit only the JSON call {"tool": <name>, "args": {...}}.',
+		grade: (o) => {
+			const j = extractJson(o);
+			if (jsonField(j, "tool") !== "write_file") return 0;
+			const args = jsonField(j, "args");
+			const pathOk = jsonField(args, "path") === "out.txt";
+			const content = jsonField(args, "content");
+			const contentOk = typeof content === "string" && content.includes("hello");
+			return pathOk && contentOk ? 1 : 0;
+		},
+	},
+	{
+		id: "agentic/tool-sequence",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: 'Tools: list_dir(path), read_file(path). Emit only a JSON array of the two calls, in order: first list the "src" directory, then read "src/a.ts". Each element is {"tool": <name>, "args": {"path": <path>}}.',
+		grade: (o) => {
+			const j = extractJson(o);
+			if (!Array.isArray(j) || j.length !== 2) return 0;
+			const first = jsonField(j[0], "tool") === "list_dir" && jsonField(jsonField(j[0], "args"), "path") === "src";
+			const second = jsonField(j[1], "tool") === "read_file" && jsonField(jsonField(j[1], "args"), "path") === "src/a.ts";
+			return first && second ? 1 : 0;
+		},
+	},
+	{
+		id: "agentic/exact-token",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: "Reply with EXACTLY the word ACK and nothing else.",
+		grade: (o) => answerScore(o, "ack"),
+	},
+
+	// ---- harder / partial-credit: spread models by HOW MANY parts they get right ----
+	{
+		id: "coding/trace-multi",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "Give the result of each expression, one per line, in order:\n(1) [1,2,3,4].reduce((a,b)=>a+b,0)\n(2) 'hello'.length\n(3) [5,3,8].sort()[0]\n(4) Object.keys({a:1,b:2}).length\n(5) parseInt('0x1F',16)",
+		grade: (o) => multiAnswerCoverage(o, ["10", "5", "3", "2", "31"]),
+	},
+	{
+		id: "coding/float-eq",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "In JavaScript, what does `0.1 + 0.2 === 0.3` evaluate to? Reply true or false.",
+		grade: (o) => answerScore(o, "false"),
+	},
+	{
+		id: "coding/regex-exec",
+		axis: "coding",
+		system: JSON_ONLY,
+		user: "What does `/\\d+/.exec('ab12cd34')[0]` return? Reply with only the value.",
+		grade: (o) => answerScore(o, "12"),
+	},
+	{
+		id: "intel/multi-arith",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: "Answer each, one per line, in order:\n(1) 17 * 23\n(2) 100 - 37\n(3) 2^10\n(4) the 13th prime number\n(5) GCD(48, 36)",
+		grade: (o) => multiAnswerCoverage(o, ["391", "63", "1024", "41", "12"]),
+	},
+	{
+		id: "intel/units",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: "How many minutes are in 3.5 hours? Reply with just the number.",
+		grade: (o) => answerScore(o, "210"),
+	},
+	{
+		id: "intel/order",
+		axis: "intelligence",
+		system: JSON_ONLY,
+		user: "Tom is older than Jane. Jane is older than Sue. Who is the youngest? Reply with just the name.",
+		grade: (o) => answerScore(o, "sue"),
+	},
+	{
+		id: "agentic/arg-synth",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: 'Tool: search(query, limit). Emit only the JSON call to search for "router config" limited to 5 results: {"tool": <name>, "args": {"query": <q>, "limit": <n>}}.',
+		grade: (o) => {
+			const j = extractJson(o);
+			const args = jsonField(j, "args");
+			const q = jsonField(args, "query");
+			return jsonField(j, "tool") === "search" && typeof q === "string" && q.toLowerCase().includes("router config") && jsonField(args, "limit") === 5 ? 1 : 0;
+		},
+	},
+	{
+		id: "agentic/conditional",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: 'Tools: read_file(path), create_file(path). If a file "x" exists, read it; otherwise create it. Assume it does NOT exist. Emit only the JSON call {"tool": <name>, "args": {"path": <path>}}.',
+		grade: (o) => {
+			const j = extractJson(o);
+			return jsonField(j, "tool") === "create_file" && jsonField(jsonField(j, "args"), "path") === "x" ? 1 : 0;
+		},
+	},
+	{
+		id: "agentic/three-step",
+		axis: "agentic",
+		system: JSON_ONLY,
+		user: 'Tools: list_dir(path), read_file(path), write_file(path, content). Emit only a JSON array of three calls, in order: (1) list "src", (2) read "src/config.ts", (3) write "note.txt" with content "done". Each element is {"tool": <name>, "args": {...}}.',
+		grade: (o) => {
+			const j = extractJson(o);
+			if (!Array.isArray(j)) return 0;
+			const want = [
+				{ tool: "list_dir", key: "path", val: "src" },
+				{ tool: "read_file", key: "path", val: "src/config.ts" },
+				{ tool: "write_file", key: "path", val: "note.txt" },
+			];
+			let hit = 0;
+			for (let i = 0; i < want.length; i++) {
+				const step = j[i];
+				const w = want[i]!;
+				if (jsonField(step, "tool") === w.tool && jsonField(jsonField(step, "args"), w.key) === w.val) hit += 1;
+			}
+			return hit / want.length;
+		},
+	},
+];
+
+/**
+ * Open-ended tasks graded by an LLM judge. Deliberately harder and answer-free,
+ * so quality (not just pass/fail) varies and the judge can separate models the
+ * objective proxies pin at the ceiling.
+ */
+export const JUDGED_TASKS: readonly JudgedTask[] = [
+	{
+		id: "coding/debounce",
+		axis: "coding",
+		user: "Implement `debounce(fn, ms)` in TypeScript that delays calls, so only the last call within a quiet window runs. Preserve `this` and the latest arguments, and type it generically. Explain any edge case you handle.",
+	},
+	{
+		id: "coding/bugfix-explain",
+		axis: "coding",
+		user: "This function is wrong:\n\nfunction median(xs) {\n  xs.sort();\n  const m = xs.length / 2;\n  return xs[m];\n}\n\nRewrite it correctly for an array of numbers and explain every bug you fixed.",
+	},
+	{
+		id: "intel/concurrency-tradeoff",
+		axis: "intelligence",
+		user: "Explain the tradeoff between optimistic and pessimistic concurrency control. Give a concrete workload where each is the right choice, and say why.",
+	},
+	{
+		id: "intel/latency-diagnosis",
+		axis: "intelligence",
+		user: "A web service's p99 latency spiked 10x while p50 stayed flat. List the three most likely causes and, for each, one concrete measurement that would confirm or rule it out.",
+	},
+	{
+		id: "agentic/debug-plan",
+		axis: "agentic",
+		user: "You must fix a failing test in a repo you have never seen, with tools read_file, search, edit_file, run. Describe the exact sequence of tool actions you would take BEFORE editing anything, and why each step precedes the next.",
+	},
+	{
+		id: "agentic/locate-error",
+		axis: "agentic",
+		user: "Given only list_dir, read_file, and run, plan the concrete steps to locate the source of a runtime error 'TypeError: undefined is not a function' in an unfamiliar JS project. Be specific about what you run and what you look for at each step.",
+	},
+];

package/src/index.ts

@@ -33,7 +33,6 @@ Global options:
 
   serve    --port <n>  --host <addr>  --log <level>
   stats    --days <n>  --json
-  stats    --days <n>  --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>

package/src/router/candidates.ts

@@ -9,7 +9,7 @@ import type { QualityAxis, RouterConfig } from "../config/types.ts";
 import { forecast, priceAt } from "../cost/forecast.ts";
 import type { Ledger } from "../cost/types.ts";
 import type { NormRequest } from "../wire/types.ts";
-import { effectiveQualityFloor, tierPlanFor } from "./tier-plan.ts";
+import { effectivePriceCeiling, effectiveQualityFloor, tierPlanFor } from "./tier-plan.ts";
 import type { Candidate, Features, Rejection, TaskType, Tier } from "./types.ts";
 
 export interface BuildCandidatesArgs {
@@ -92,10 +92,17 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 	//  - the TASK floor is a capability requirement (vision needs a model that
 	//    can actually see), so adaptive relaxation must never lower it.
 	const taskFloor = taskCfg.minQuality ?? 0;
-	const adaptiveTierFloor = cfg.adaptiveTierFloors
-		? effectiveQualityFloor(tierCfg.minQuality, tier, effectiveAxis, tierPlanFor(snapshot, cfg))
-		: tierCfg.minQuality;
+	const plan = cfg.adaptiveTierFloors || cfg.adaptivePriceCeilings ? tierPlanFor(snapshot, cfg) : null;
+	const adaptiveTierFloor =
+		cfg.adaptiveTierFloors && plan !== null
+			? effectiveQualityFloor(tierCfg.minQuality, tier, effectiveAxis, plan)
+			: tierCfg.minQuality;
 	const qualityFloor = Math.max(taskFloor, adaptiveTierFloor);
+	// Input-price ceiling: catalog-derived band when adaptive, else the fixed config.
+	const priceCeiling =
+		cfg.adaptivePriceCeilings && plan !== null
+			? effectivePriceCeiling(tierCfg.maxInputPerMtok, tier, plan, true)
+			: tierCfg.maxInputPerMtok;
 	const taskPins = taskCfg.prefer ?? [];
 	let images = 0;
 	if (req.hasImages) for (const m of req.messages) images += m.images;
@@ -171,11 +178,11 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		// push a model over the ceiling exactly when conversations get long.
 		// Catalog prices are per-token; ceilings are per million tokens.
 		const price = priceAt(model, Math.max(1, features.promptTokens));
-		if (!relaxPrice && tierCfg.maxInputPerMtok !== undefined && price.prompt * 1e6 > tierCfg.maxInputPerMtok) {
+		if (!relaxPrice && priceCeiling !== undefined && price.prompt * 1e6 > priceCeiling) {
 			rejected.push({
 				slug,
 				reason: "over_price_ceiling",
-				detail: `input $${(price.prompt * 1e6).toFixed(2)}/Mtok > ceiling $${tierCfg.maxInputPerMtok}`,
+				detail: `input $${(price.prompt * 1e6).toFixed(2)}/Mtok > ceiling $${priceCeiling.toFixed(2)}`,
 			});
 			continue;
 		}

package/src/router/explore.ts

@@ -0,0 +1,59 @@
+/**
+ * Exploration primitives.
+ *
+ * Two experiments share one rule: the draw must be a pure function of the
+ * turn's identity, never `Math.random()`. Every stage of this pipeline is
+ * deterministic so `auto-model-router explain` can replay a past decision
+ * offline, and a random draw would silently break that. Hashing also keeps a
+ * draw stable across the failover retries of a single turn.
+ */
+
+import type { RouterConfig } from "../config/types.ts";
+import { sha256Hex } from "../util/hash.ts";
+
+/** Deterministic uniform draw in [0,1) from an arbitrary seed string. */
+export function explorationDraw(seed: string): number {
+	// 8 hex chars = 32 bits of the digest, divided by 2^32.
+	return Number.parseInt(sha256Hex(seed).slice(0, 8), 16) / 0x1_0000_0000;
+}
+
+/** The hold length in force for a conversation, and whether it was drawn. */
+export interface HoldChoice {
+	turns: number;
+	/**
+	 * The randomised arm this conversation was assigned, or null when hold
+	 * exploration is off. Recorded on every turn of the conversation, not only
+	 * the ones the hold actually affects, so the comparison between arms is a
+	 * clean intention-to-treat one.
+	 */
+	arm: number | null;
+}
+
+/**
+ * Resolves how long to hold a tier after this turn.
+ *
+ * Only the POST-ESCALATION hold is randomised. That is the one that governs
+ * expensive spend -- a turn escalates once and the hold then bills the next
+ * several turns at the escalated tier -- and leaving the ordinary hold alone
+ * keeps the experiment narrow enough to read.
+ *
+ * The arm is drawn from the conversation key alone, so it is constant for the
+ * life of a conversation. A length that changed mid-hold would measure
+ * nothing.
+ */
+export function resolveHoldTurns(cfg: RouterConfig, conversationKey: string, escalated: boolean): HoldChoice {
+	const hx = cfg.exploration.holdTurns;
+	const exploring = cfg.exploration.enabled && hx.enabled && hx.values.length > 0;
+
+	const arm = exploring ? drawArm(hx.values, conversationKey) : null;
+	if (!escalated) return { turns: cfg.hysteresis.holdTurns, arm };
+	return { turns: arm ?? cfg.hysteresis.holdTurnsAfterEscalation, arm };
+}
+
+function drawArm(values: readonly number[], conversationKey: string): number | null {
+	const draw = explorationDraw(`hold:${conversationKey}`);
+	// Math.min guards the draw === 1 boundary, which the division cannot
+	// produce today but would if the bit width ever changed.
+	const idx = Math.min(Math.floor(draw * values.length), values.length - 1);
+	return values[idx] ?? null;
+}

package/src/router/select.ts

@@ -10,6 +10,7 @@ import type { CatalogSnapshot } from "../catalog/types.ts";
 import type { ProfileConfig, RouterConfig } from "../config/types.ts";
 import { priceAt } from "../cost/forecast.ts";
 import type { Ledger } from "../cost/types.ts";
+import { explorationDraw } from "./explore.ts";
 import type { NormRequest, ReasoningLevel } from "../wire/types.ts";
 import { planCacheBreakpoints } from "./cache-control.ts";
 import { buildCandidates } from "./candidates.ts";
@@ -19,6 +20,7 @@ import {
 	type Classification,
 	type ConversationState,
 	type Decision,
+	type Exploration,
 	type Features,
 	type ProbePlan,
 	type Rejection,
@@ -141,14 +143,61 @@ export function select(args: SelectArgs): Decision {
 		}
 	}
 
+	// Whether a usable warm prompt cache exists right now. Shared by
+	// exploration (2c) and candidate building (3) so both agree on the term.
+	const cacheWarm = state.cacheWarmSlug !== null && nowMs - state.cacheWarmAtMs <= cfg.hysteresis.cacheWarmTtlMs;
+
+	// 2c. Epsilon-greedy exploration: on a small deterministic fraction of
+	//     turns, route one tier BELOW the tier we would otherwise use, so the
+	//     ledger witnesses whether the cheaper tier would have sufficed.
+	//
+	//     Escalation is what makes this safe rather than reckless: if the
+	//     cheaper tier flounders, the probe rejects the attempt and the turn
+	//     escalates, so a bad draw costs one wasted cheap attempt rather than
+	//     a failed turn.
+	//
+	//     Sticky turns are explored only once their cache has gone cold. The
+	//     hold exists to protect a warm cache, so exploring while one is live
+	//     would destroy precisely what the hold is for; once it has expired
+	//     the objection lapses. This matters more than it sounds: most
+	//     expensive turns reach their tier by hold rather than by
+	//     classification, so excluding held turns confines exploration to the
+	//     cheapest boundary in the system.
+	//
+	//     Still skipped on forced escalations (the probe already proved the
+	//     cheaper tier failed) and on failover retries, where a second
+	//     confound is not wanted.
+	//
+	//     This deliberately bypasses maxDowngradePerTurn by one tier: that
+	//     limiter guards against a noisy classification, not against a probe
+	//     that is sampled on purpose and escalates when it is wrong.
+	let explored: Exploration | null = null;
+	const ex = cfg.exploration;
+	const stickyAllows =
+		cls.source !== "sticky" ||
+		ex.stickyPolicy === "always" ||
+		(ex.stickyPolicy === "cold-cache" && !cacheWarm);
+	const tierRate = ex.rates[effective] ?? 0;
+	if (
+		ex.enabled &&
+		tierRate > 0 &&
+		stickyAllows &&
+		classification.source !== "escalation" &&
+		(args.excludeSlugs === undefined || args.excludeSlugs.length === 0)
+	) {
+		const target = tierAt(Math.max(tierIdx(effective) - 1, minI));
+		if (target !== null && target !== effective && explorationDraw(`explore:${req.conversationKey}:${state.turn}`) < tierRate) {
+			const held = cls.source === "sticky" ? `, held tier (${cacheWarm ? "warm" : "cold"} cache)` : "";
+			reasons.push(`exploration: deliberately routing ${effective} → ${target} (rate ${tierRate}${held})`);
+			explored = { from: effective, to: target };
+			effective = target;
+		}
+	}
 	// 3. Candidates for the effective tier; widen one tier upward, then
 	//    downward, and only fail when the whole profile envelope is exhausted.
 	// The task type selects the quality axis and capability filters; the tier
 	// still bounds cost (task selects, tier budgets).
-	const warmSlug =
-		state.cacheWarmSlug !== null && nowMs - state.cacheWarmAtMs <= cfg.hysteresis.cacheWarmTtlMs
-			? state.cacheWarmSlug
-			: null;
+	const warmSlug = cacheWarm ? state.cacheWarmSlug : null;
 	const build = (t: Tier, relaxLevel = 0): { candidates: Candidate[]; rejected: Rejection[] } =>
 		buildCandidates({
 			req,
@@ -360,6 +409,7 @@ export function select(args: SelectArgs): Decision {
 		considered: candidates,
 		rejected: resolved.rejected,
 		reasons,
+		explored,
 		budgetDowngraded,
 	};
 }