auto-model-router 0.2.16 → 0.2.20

package/src/context/bridge.ts

@@ -38,6 +38,8 @@ export interface BridgeOptions {
 	memoryLimit: number;
 	docsLimit: number;
 	sessionLimit: number;
+	/** Character budget for the project brief rendered first in the block; 0 omits it. */
+	briefChars: number;
 	/** Record settled turns back into agentdox sessions. */
 	recordTurns: boolean;
 	/** Bound on queued write-backs; excess is dropped rather than grown unbounded. */
@@ -81,7 +83,7 @@ function appendFragment(prior: string, next: string): string {
 }
 
 export function createContextBridge(opts: BridgeOptions): ContextBridge {
-	const { client, store, log, maxStalenessMs, maxBlockChars, memoryLimit, docsLimit, sessionLimit, recordTurns, maxQueue } = opts;
+	const { client, store, log, maxStalenessMs, maxBlockChars, memoryLimit, docsLimit, sessionLimit, briefChars, recordTurns, maxQueue } = opts;
 
 	// Serialized write-back queue. Session appends for one conversation must
 	// stay ordered, and agentdox is a local service — one worker is plenty.
@@ -119,7 +121,7 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 				return { ...pinned, fetchedAtMs: input.pinnedFetchedAtMs };
 			}
 
-			const raw = await client.assemble(input.scope, input.query, { memoryLimit, docsLimit, sessionLimit });
+			const raw = await client.assemble(input.scope, input.query, { memoryLimit, docsLimit, sessionLimit, briefChars });
 			if (raw === null) {
 				// agentdox unreachable or empty. Keep serving the pinned block if we
 				// have one: stale shared context beats none, and re-using it also

package/src/context/index.ts

@@ -30,6 +30,7 @@ export function createBridgeFromConfig(cfg: RouterConfig, db: Database): Context
 		memoryLimit: c.memoryLimit,
 		docsLimit: c.docsLimit,
 		sessionLimit: c.sessionLimit,
+		briefChars: c.briefChars,
 		recordTurns: c.recordTurns,
 		maxQueue: c.maxQueue,
 	});

package/src/cost/types.ts

@@ -124,7 +124,12 @@ export interface LedgerEntry {
 	/** Time to first content token, ms. */
 	ttftMs: number | null;
 	finishReason: string | null;
-	/** Tokens billed but discarded because the attempt was aborted and retried. */
+	/**
+	 * Attempt superseded by a retry or escalation. NOT a cost figure: by design
+	 * these rows never carry reported_usd, so "wasted spend" sums to $0.00.
+	 * The meaningful waste measure is retry spend — rows with attempt > 0 that
+	 * DID bill. Kept for compatibility; do not read it as money.
+	 */
 	wasted: boolean;
 	upstreamGenerationId: string | null;
 	error: string | null;

package/src/router/candidates.ts

@@ -134,6 +134,8 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 
 	const candidates: Candidate[] = [];
 	const rejected: Rejection[] = [];
+	// Carries the trust/latency-adjusted cost into the second scoring pass.
+	const effectiveUsdBySlug = new Map<string, number>();
 
 	for (const model of snapshot.models) {
 		const slug = model.slug;
@@ -231,6 +233,20 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
+		// Every candidate is priced COLD, deliberately, and this has been measured
+		// rather than assumed. Two reasons:
+		//  1. `coldUsd` feeds the budget guard in select.ts, and a budget must
+		//     survive a cache miss.
+		//  2. Discounting the warm slug here only ever LOWERS its effective cost,
+		//     so it can only make the warm model win more often — and the warm
+		//     model is already either the cheapest candidate or kept by the
+		//     dedicated stay-vs-switch comparison in select.ts step 4, which does
+		//     price staying at `cacheRead` against switching at cold+`cacheWrite`.
+		//     So the ranking change has no headroom to alter an outcome.
+		// Verified with tools/replay.ts: scoring the warm candidate at hit rates
+		// 0.5 / 0.8 / 0.95 changed 0 of 897 decisions, and 0 of 702 on the subset
+		// whose conversations ran the expensive model. Cache economics belong in
+		// the switch decision, not in candidate scoring — do not "fix" this.
 		const fc = forecast(model, {
 			promptTokens: features.promptTokens,
 			completionTokens: expectedCompletionTokens,
@@ -249,7 +265,10 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 				: null;
 		const latencyMult = latencyMultiplier(latency, filters, expectedCompletionTokens);
 		const effectiveUsd = (fc.expectedUsd / Math.max(trustScore, 0.5)) * latencyMult;
-		const score = Math.pow(qualityScore / 100, tierCfg.qualityExponent) / Math.max(effectiveUsd, 1e-9);
+		// 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.
+		const score = 0;
 
 		const reasons: string[] = [
 			quality === null
@@ -267,6 +286,30 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		}
 		if (pinned) reasons.push("pinned into tier");
 		candidates.push({ model, forecast: fc, qualityScore, trustScore, score, reasons });
+		effectiveUsdBySlug.set(slug, effectiveUsd);
+	}
+
+	// Second pass: both new tier modes need the whole set.
+	//  - qualityNormalization rescales quality to the set's own [worst, best]
+	//    range, so the exponent operates on a full 0-1 spread instead of the
+	//    raw index's compressed 69-78 band.
+	//  - capabilityFloorUsd ignores the ratio entirely and takes the highest
+	//    quality candidate affordable within the cap.
+	const qualities = candidates.map((c) => c.qualityScore);
+	const qMin = qualities.length > 0 ? Math.min(...qualities) : 0;
+	const qMax = qualities.length > 0 ? Math.max(...qualities) : 0;
+	const qSpread = qMax - qMin;
+	const normalize = tierCfg.qualityNormalization === true && qSpread > 0;
+	for (const c of candidates) {
+		const effectiveUsd = effectiveUsdBySlug.get(c.model.slug) ?? c.forecast.expectedUsd;
+		// Normalised quality is unitless in [0,1]: the set's cheapest-quality
+		// model scores 0, its best scores 1. A single-model set has no spread,
+		// so it keeps the raw path (guarded by qSpread > 0).
+		const q = normalize ? (c.qualityScore - qMin) / qSpread : c.qualityScore / 100;
+		c.score = Math.pow(q, tierCfg.qualityExponent) / Math.max(effectiveUsd, 1e-9);
+		if (normalize) {
+			c.reasons.push(`quality normalised ${q.toFixed(3)} within set [${qMin}, ${qMax}]`);
+		}
 	}
 
 	candidates.sort((a, b) => {
@@ -285,5 +328,28 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		if (b.model.slug === warmSlug) return 1;
 		return a.model.slug < b.model.slug ? -1 : 1;
 	});
+
+	// Capability-floor mode: the top tier's job is "best model the work needs",
+	// which quality-per-dollar cannot express — a bargain model always wins the
+	// ratio however weak it is. Promote the highest-quality candidate whose
+	// forecast turn cost fits the cap to the front. Strictly an upgrade: when
+	// nothing is affordable, or the ranked winner is already the best quality,
+	// the order is untouched.
+	const floorUsd = tierCfg.capabilityFloorUsd;
+	if (floorUsd !== undefined && candidates.length > 1) {
+		let best: Candidate | undefined;
+		for (const c of candidates) {
+			if (c.forecast.coldUsd > floorUsd) continue;
+			if (best === undefined || c.qualityScore > best.qualityScore) best = c;
+		}
+		if (best !== undefined && best !== candidates[0]) {
+			const idx = candidates.indexOf(best);
+			candidates.splice(idx, 1);
+			candidates.unshift(best);
+			best.reasons.push(
+				`capability floor: highest quality ${best.qualityScore} within $${floorUsd}/turn (cold $${best.forecast.coldUsd.toFixed(4)})`,
+			);
+		}
+	}
 	return { candidates, rejected };
 }

package/src/server/http.ts

@@ -167,7 +167,7 @@ function isLoopbackHostHeader(hostHeader: string | null): boolean {
 export function startServer(cfg: RouterConfig): StartedServer {
 	const log = createLogger(cfg.logLevel);
 
-	mkdirSync(dirname(cfg.ledger.path), { recursive: true });
+	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 = createOpenRouterClient(cfg);
@@ -258,7 +258,14 @@ export function startServer(cfg: RouterConfig): StartedServer {
 		runTurn(normReq, sink, turnDeps, req.signal)
 			.catch((err: unknown) => {
 				log.error("turn failed", { error: err instanceof Error ? err.message : String(err) });
-				return Promise.resolve(sink.error(toWireError(err))).catch(() => {});
+				// sink.error() is SYNCHRONOUS: it runs before Promise.resolve wraps
+				// anything, so a throw out of it escapes this .catch() handler and
+				// becomes an unhandled rejection that kills the process. Wrap it.
+				try {
+					Promise.resolve(sink.error(toWireError(err))).catch(() => {});
+				} catch {
+					// Stream already gone; the response cannot carry the error.
+				}
 			})
 			.finally(() => {
 				// Release the concurrency slot when the turn settles, not when the

package/src/wire/openai/sink.ts

@@ -26,12 +26,25 @@ export function createStreamingSink(virtualModel: string): { sink: ResponseSink;
 		},
 	});
 	const send = (bytes: Uint8Array): void => {
-		if (!closed) controller?.enqueue(bytes);
+		if (closed) return;
+		try {
+			controller?.enqueue(bytes);
+		} catch {
+			// The runtime can close the controller under us — a client cancelling
+			// the stream (reader.cancel()) is not exceptional and nothing above us
+			// observes it. Mark closed and drop the write; measured to throw
+			// ERR_INVALID_STATE synchronously on Bun 1.x otherwise.
+			closed = true;
+		}
 	};
 	const close = (): void => {
 		if (!closed) {
 			closed = true;
-			controller?.close();
+			try {
+				controller?.close();
+			} catch {
+				// Already closed by the runtime; nothing left to do.
+			}
 		}
 	};
 

package/test/context-bridge.test.ts

@@ -55,6 +55,7 @@ function mkBridge(client: AgentDoxClient, over: Partial<BridgeOpts> = {}) {
 		memoryLimit: 8,
 		docsLimit: 2,
 		sessionLimit: 6,
+		briefChars: 0,
 		recordTurns: true,
 		maxQueue: 64,
 		...over,
@@ -102,12 +103,12 @@ describe("context bridge refresh policy", () => {
 		// especially: docs are WHOLE documents and were left unbounded, and a single
 		// ashlands note-doc measured 41,921 chars — over the whole cap by itself.
 		// The REST endpoint also ignores snake_case limit keys, which silently reads
-		// as unbounded, so pin that all three limits actually reach the client.
+		// as unbounded, so pin that all four limits actually reach the client.
 		const client = mkClient();
-		const { bridge, db } = mkBridge(client, { memoryLimit: 5, docsLimit: 1, sessionLimit: 2 });
+		const { bridge, db } = mkBridge(client, { memoryLimit: 5, docsLimit: 1, sessionLimit: 2, briefChars: 9000 });
 		try {
 			await bridge.resolve(input());
-			expect(client.lastLimits).toEqual({ memoryLimit: 5, docsLimit: 1, sessionLimit: 2 });
+			expect(client.lastLimits).toEqual({ memoryLimit: 5, docsLimit: 1, sessionLimit: 2, briefChars: 9000 });
 		} finally {
 			db.close();
 		}
@@ -244,6 +245,7 @@ describe("context bridge refresh policy", () => {
 				memoryLimit: 8,
 				docsLimit: 2,
 				sessionLimit: 6,
+				briefChars: 0,
 				recordTurns: true,
 				maxQueue: 64,
 			};

package/test/failover.test.ts

@@ -69,7 +69,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
-		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, recordTurns: false, maxQueue: 64 },
+		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true },
 		budget: { onExceeded: "downgrade" },
 		profiles: [],

package/test/http-resilience.test.ts

@@ -0,0 +1,58 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+import { startServer, type StartedServer } from "../src/server/http.ts";
+
+describe("HTTP server resilience against dead streams", () => {
+	let handle: StartedServer;
+	let baseUrl: string;
+
+	beforeAll(() => {
+		const cfg: RouterConfig = {
+			...DEFAULT_CONFIG,
+			server: { host: "127.0.0.1", port: 0 },
+			ledger: { ...DEFAULT_CONFIG.ledger, path: ":memory:" },
+			context: { ...DEFAULT_CONFIG.context, enabled: false },
+			logLevel: "silent",
+		};
+		handle = startServer(cfg);
+		baseUrl = `http://127.0.0.1:${handle.server.port}`;
+	});
+	afterAll(async () => {
+		await handle.stop();
+	});
+
+	test("server answers /v1/models cleanly initially", async () => {
+		const res = await fetch(`${baseUrl}/v1/models`);
+		expect(res.status).toBe(200);
+		const json = (await res.json()) as { data: unknown[] };
+		expect(Array.isArray(json.data)).toBe(true);
+	});
+
+	test("cancelling a streaming /v1/chat/completions client does not crash the server", async () => {
+		const res = await fetch(`${baseUrl}/v1/chat/completions`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				model: "auto",
+				stream: true,
+				messages: [{ role: "user", content: "hello" }],
+			}),
+		});
+
+		// Immediately cancel the reader mid-stream (simulates client disconnect)
+		const reader = res.body?.getReader();
+		expect(reader).toBeDefined();
+		await reader?.cancel("client abruptly dropped");
+
+		// Allow microtasks and I/O ticks to settle without real wall-clock delays
+		await new Promise<void>((resolve) => {
+			setImmediate(() => resolve());
+		});
+		// and answers subsequent requests cleanly.
+		const modelsRes = await fetch(`${baseUrl}/v1/models`);
+		expect(modelsRes.status).toBe(200);
+		const json = (await modelsRes.json()) as { data: unknown[] };
+		expect(Array.isArray(json.data)).toBe(true);
+	});
+});

package/test/tier-plan.test.ts

@@ -354,3 +354,94 @@ describe("adaptive price ceilings", () => {
 		expect(on.rejected.some((r) => r.slug === "a/4" && r.reason === "over_price_ceiling")).toBe(true);
 	});
 });
+
+describe("quality normalization and capability floor (benchmark findings 4/6)", () => {
+	const req = parseChatRequest(
+		{
+			model: "auto",
+			tools: [{ type: "function", function: { name: "read", description: "Read", parameters: { type: "object", properties: {} } } }],
+			messages: [{ role: "user", content: "implement nested transaction savepoints" }],
+		},
+		new Headers(),
+	);
+	const features = extractFeatures(req, 100);
+
+	// The real catalog's shape: quality in a narrow band, price spanning ~100x.
+	// `hard` has a quality floor of 72, so cheap/1 is deliberately below it —
+	// it must be rejected, and mid/2 is the cheapest ELIGIBLE model, the one
+	// raw quality-per-dollar ranking picks at any sane exponent.
+	const spread = snapshot(
+		models([
+			["cheap/1", 70, 0.05],
+			["mid/2", 74, 1.0],
+			["good/3", 76, 3.0],
+			["best/4", 78, 5.0],
+		]),
+	);
+
+	const run = (tierOverride: Partial<(typeof BASE)["tiers"]["hard"]>) =>
+		buildCandidates({
+			req,
+			features,
+			tier: "hard",
+			task: "coding",
+			snapshot: spread,
+			ledger: null,
+			cfg: { ...BASE, tiers: { ...BASE.tiers, hard: { ...BASE.tiers.hard, ...tierOverride } } },
+			expectedCompletionTokens: 512,
+			warmSlug: null,
+		});
+
+	test("raw scoring at the shipped exponent picks the cheapest ELIGIBLE model", () => {
+		const { candidates, rejected } = run({ qualityExponent: 3 });
+		expect(candidates[0]?.model.slug).toBe("mid/2");
+		// cheap/1 is under the hard floor of 72 and never competes.
+		expect(rejected.some((r) => r.slug === "cheap/1" && r.reason === "below_quality_floor")).toBe(true);
+	});
+
+	test("normalization lets a single-digit exponent buy the best model, which raw cannot", () => {
+		// Raw at the same exponent still cannot reach it: that is the defect.
+		expect(run({ qualityExponent: 12 }).candidates[0]?.model.slug).toBe("mid/2");
+		// Normalised, the same 12 selects the top-quality model.
+		const normalised = run({ qualityExponent: 12, qualityNormalization: true });
+		expect(normalised.candidates[0]?.model.slug).toBe("best/4");
+		expect(normalised.candidates[0]?.reasons.some((r) => r.includes("quality normalised"))).toBe(true);
+	});
+
+	test("normalization is monotone in the exponent: higher never picks a weaker model", () => {
+		let lastQuality = 0;
+		for (const qualityExponent of [1, 4, 8, 12, 20]) {
+			const top = run({ qualityExponent, qualityNormalization: true }).candidates[0];
+			expect(top).toBeDefined();
+			expect(top?.qualityScore ?? 0).toBeGreaterThanOrEqual(lastQuality);
+			lastQuality = top?.qualityScore ?? 0;
+		}
+	});
+
+	test("capability floor takes the best model inside the cap, ignoring the ratio", () => {
+		// mid/2 costs ~$0.0016 and good/3 ~$0.0049, so this cap admits both but
+		// excludes best/4 (~$0.0082). The ranked winner is mid/2 (cheapest).
+		const cap = 0.005;
+		const capped = run({ capabilityFloorUsd: cap });
+		const top = capped.candidates[0];
+		expect(top).toBeDefined();
+		expect(top?.forecast.coldUsd ?? 1).toBeLessThanOrEqual(cap);
+		// It must be the highest-quality affordable one, not the cheapest: good/3.
+		expect(top?.model.slug).toBe("good/3");
+		expect(top?.reasons.some((r) => r.includes("capability floor"))).toBe(true);
+	});
+
+	test("capability floor is strictly an upgrade: an unaffordable cap changes nothing", () => {
+		const base = run({}).candidates.map((c) => c.model.slug);
+		// A cap below every candidate's cost promotes nobody.
+		const tiny = run({ capabilityFloorUsd: 1e-9 }).candidates.map((c) => c.model.slug);
+		expect(tiny).toEqual(base);
+	});
+
+	test("both modes stay inert by default, so shipped behaviour is unchanged", () => {
+		const shipped = run({});
+		expect(shipped.candidates[0]?.model.slug).toBe("mid/2");
+		expect(shipped.candidates.every((c) => !c.reasons.some((r) => r.includes("normalised")))).toBe(true);
+		expect(shipped.candidates.every((c) => !c.reasons.some((r) => r.includes("capability floor")))).toBe(true);
+	});
+});

package/test/turn.test.ts

@@ -70,7 +70,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1 },
 		exploration: { enabled: false, rates: {}, stickyPolicy: "never", holdTurns: { enabled: false, values: [2, 3, 4] } },
 		cache: { injectBreakpoints: true, maxBreakpoints: 4, minPromptTokens: 1024, milestoneTokens: 20_000 },
-		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, recordTurns: false, maxQueue: 64 },
+		context: { enabled: false, baseUrl: "", token: "", defaultScope: "", timeoutMs: 3_000, maxStalenessMs: 900_000, maxBlockChars: 24_000, memoryLimit: 8, docsLimit: 2, sessionLimit: 6, briefChars: 0, recordTurns: false, maxQueue: 64 },
 		compaction: { enabled: false, budgetTokens: 40_000, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true },
 		budget: { onExceeded: "downgrade" },
 		profiles: [],

package/test/wire-sink.test.ts

@@ -70,6 +70,37 @@ describe("createStreamingSink", () => {
 			{ error: { message: "boom", type: "server_error", code: "upstream_error" } },
 		]);
 	});
+
+	test("chunk, error, and finish survive a client-cancelled body without throwing", async () => {
+		const { sink, response } = createStreamingSink("auto");
+		const reader = response.body?.getReader();
+		expect(reader).toBeDefined();
+		// Client disconnects mid-stream: reader cancels, controller closes.
+		await reader?.cancel("client closed connection");
+
+		// None of these may throw ERR_INVALID_STATE:
+		expect(() => {
+			sink.chunk(
+				chunk({
+					id: "gen-cancelled",
+					model: "openai/gpt-5.5",
+					choices: [{ index: 0, delta: { content: "trailing" }, finish_reason: null }],
+				}),
+			);
+		}).not.toThrow();
+
+		expect(() => {
+			sink.finish(SUMMARY);
+		}).not.toThrow();
+
+		// Repeated calls (e.g. error after chunk on dead stream) must also stay safe:
+		const { sink: sink2, response: response2 } = createStreamingSink("auto");
+		const reader2 = response2.body?.getReader();
+		await reader2?.cancel();
+		expect(() => {
+			sink2.error({ status: 500, code: "server_error", message: "late failure" });
+		}).not.toThrow();
+	});
 });
 
 describe("createBufferedSink", () => {

package/tools/replay.ts

@@ -26,20 +26,29 @@
  *  - `explorationDraw` keys on `conversationKey:turn`, both recorded, so
  *    exploration reproduces deterministically and cancels out in a diff.
  *
+ * Conversation state is reconstructed from the PRECEDING recorded dispatch in
+ * the same conversation — prior slug, prior tier, cache warmth, cumulative
+ * spend — rather than simulated, so cache-warmth behaviour is exercised. Rows
+ * are replayed chronologically for that reason.
+ *
  * WHAT IT DOES NOT MODEL — read this before trusting a conclusion
  *  - `messages` are not recorded, so compaction cannot be re-planned. Replay
  *    forces `compaction.enabled=false` and feeds the POST-compaction prompt
  *    size (`usage.promptTokens`), i.e. the prompt selection actually saw.
- *  - Conversation state is not recoverable historically (only the current row
- *    survives), so replay uses a neutral state: no sticky tier, no warm cache,
- *    no accumulated spend. Hysteresis, cache-warmth tie-breaks and the
- *    per-conversation budget guard are therefore NOT exercised.
+ *  - `stickyUntilTurn` was never persisted per turn, so the hysteresis hold
+ *    window is absent. This is the main residual gap.
  *  - `requestedReasoning` is the one `Features` field the ledger omits; it
  *    replays as undefined.
+ *  - Module constants are not config, so things like CAP_AUTONOMOUS_LOOP cannot
+ *    be A/B'd via `--set` — only `RouterConfig` paths can.
  *
- * Because of those gaps, the report leads with a FIDELITY figure: how often the
- * baseline variant reproduces the model that actually served. Low fidelity means
- * the unmodelled parts dominate and any delta below is weak evidence.
+ * Because of those gaps the report leads with a FIDELITY figure. Read it with
+ * care: it conflates replay error with genuine code change, since replay always
+ * runs CURRENT code against rows served by whatever code was live then. Measured
+ * on rows served by matching code it is 90% model / 77% tier; across older
+ * history it drops to ~55%, and that drop is the shipped classifier changes
+ * showing up, not the tool being wrong. Isolate a population with `--where` when
+ * measuring one change.
  */
 
 import { Database } from "bun:sqlite";
@@ -106,7 +115,11 @@ function withOverrides(cfg: RouterConfig, sets: readonly string[]): RouterConfig
 			node = child as Record<string, unknown>;
 		}
 		const leaf = path[path.length - 1];
-		if (leaf === undefined || !(leaf in node)) throw new Error(`--set path not found: ${entry}`);
+		if (leaf === undefined) throw new Error(`--set expects a key, got: ${entry}`);
+		// An absent leaf is legitimate and required: optional config fields are
+		// simply missing until set (exactOptionalPropertyTypes), and introducing
+		// one is exactly what a variant does. A wrong PARENT path still throws,
+		// in the walk above, which is what catches typos.
 		node[leaf] = value;
 	}
 	return next;
@@ -124,6 +137,7 @@ interface Row {
 	usage: string;
 	reported_usd: number | null;
 	predicted_usd: number;
+	created_at_ms: number;
 }
 
 /** Rebuilds the classifier input. The ledger stores 20 of 21 Features fields. */
@@ -164,26 +178,48 @@ function requestOf(row: Row, f: Features): NormRequest {
 	};
 }
 
-/** Neutral state: no sticky tier, no warm cache, no prior spend. See header. */
-function stateOf(row: Row): ConversationState {
+/**
+ * Conversation state reconstructed from the PRECEDING recorded dispatch in the
+ * same conversation, not simulated.
+ *
+ * A neutral state cannot validate anything that depends on cache warmth — every
+ * candidate looks cold, so a warm-cache change shows zero effect. But the
+ * ledger does carry what the previous dispatch actually did, so warmth is
+ * recoverable: `cacheWarmSlug` is the slug it served, `lastPromptTokens` its
+ * prompt size. Deriving state from the RECORDED outcome rather than the
+ * replayed one also stops replay error compounding down a conversation.
+ *
+ * Still not modelled: `stickyUntilTurn`, which was never persisted per turn, so
+ * the hysteresis hold window remains absent.
+ */
+function stateOf(row: Row, prior: PriorTurn | undefined): ConversationState {
 	return {
 		key: row.conversation_key,
 		sessionId: `omp-${row.conversation_key}`,
 		turn: row.turn,
-		currentSlug: null,
-		currentTier: null,
+		currentSlug: prior?.slug ?? null,
+		currentTier: (prior?.tier as Tier | undefined) ?? null,
 		stickyUntilTurn: 0,
 		escalations: 0,
-		spentUsd: 0,
-		lastPromptTokens: 0,
-		cacheWarmSlug: null,
-		cacheWarmAtMs: 0,
+		spentUsd: prior?.spentUsd ?? 0,
+		lastPromptTokens: prior?.promptTokens ?? 0,
+		cacheWarmSlug: prior?.cachedTokens !== undefined && prior.cachedTokens > 0 ? prior.slug : null,
+		cacheWarmAtMs: prior?.atMs ?? 0,
 		contextVersion: null,
 		contextFetchedAtMs: 0,
-		updatedAtMs: 0,
+		updatedAtMs: prior?.atMs ?? 0,
 	};
 }
 
+interface PriorTurn {
+	slug: string | null;
+	tier: string;
+	promptTokens: number;
+	cachedTokens: number;
+	spentUsd: number;
+	atMs: number;
+}
+
 /**
  * Re-prices a decision against the tokens the turn ACTUALLY used, via the real
  * `computeCost` so price tiers, the cache split and reasoning/request fees are
@@ -224,14 +260,18 @@ const bySlug = new Map(snapshot.models.map((m) => [m.slug, m]));
 const ledger = createLedger(db, cfgA);
 
 const predicate = args.where === "" ? "" : ` AND (${args.where})`;
-const rows = db
-	.query(
-		`SELECT id, conversation_key, turn, requested_model, harness_id, served_slug, tier, features, usage, reported_usd, predicted_usd
-		 FROM ledger
-		 WHERE features IS NOT NULL AND wasted = 0${predicate}
-		 ORDER BY created_at_ms DESC LIMIT ?`,
-	)
-	.all(args.limit) as Row[];
+// Newest-first to honour --limit, then flipped to chronological so each row can
+// see the dispatch that preceded it in its conversation.
+const rows = (
+	db
+		.query(
+			`SELECT id, conversation_key, turn, requested_model, harness_id, served_slug, tier, features, usage, reported_usd, predicted_usd, created_at_ms
+			 FROM ledger
+			 WHERE features IS NOT NULL AND wasted = 0${predicate}
+			 ORDER BY created_at_ms DESC LIMIT ?`,
+		)
+		.all(args.limit) as Row[]
+).reverse();
 
 if (rows.length === 0) {
 	console.error("no rows matched; widen --where or --limit");
@@ -253,7 +293,7 @@ interface Outcome {
 	usd: number;
 }
 
-function run(cfg: RouterConfig, row: Row, usage: UsageCounts): Outcome {
+function run(cfg: RouterConfig, row: Row, usage: UsageCounts, prior: PriorTurn | undefined): Outcome {
 	const f = featuresOf(row, usage.promptTokens);
 	const req = requestOf(row, f);
 	const decision: Decision = select({
@@ -261,7 +301,7 @@ function run(cfg: RouterConfig, row: Row, usage: UsageCounts): Outcome {
 		features: f,
 		classification: scoreHeuristic(f, cfg),
 		profile: profileOf(cfg, row.requested_model),
-		state: stateOf(row),
+		state: stateOf(row, prior),
 		snapshot,
 		ledger,
 		cfg,
@@ -285,11 +325,24 @@ let comparable = 0;
 const flips: { id: string; tier: string; from: string; to: string; delta: number }[] = [];
 const bump = (m: Map<string, number>, k: string) => m.set(k, (m.get(k) ?? 0) + 1);
 
+// Carries the RECORDED outcome of each conversation's previous dispatch forward,
+// so cache warmth and the prior slug are real rather than assumed absent.
+const priorByConv = new Map<string, PriorTurn>();
+
 for (const row of rows) {
 	const u = JSON.parse(row.usage) as UsageCounts;
 	if (!(u.promptTokens > 0)) continue;
-	const a = run(cfgA, row, u);
-	const b = run(cfgB, row, u);
+	const prior = priorByConv.get(row.conversation_key);
+	const a = run(cfgA, row, u, prior);
+	const b = run(cfgB, row, u, prior);
+	priorByConv.set(row.conversation_key, {
+		slug: row.served_slug,
+		tier: row.tier,
+		promptTokens: u.promptTokens,
+		cachedTokens: u.cachedTokens,
+		spentUsd: (prior?.spentUsd ?? 0) + (row.reported_usd ?? row.predicted_usd),
+		atMs: row.created_at_ms,
+	});
 	bump(tallyA, a.slug);
 	bump(tallyB, b.slug);
 	bump(tierA, a.tier);