auto-model-router 0.2.7 → 0.2.9

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.2.7",
+    "version": "0.2.9",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.2.7",
+      "version": "0.2.9",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/docs/context-optimization.md

@@ -55,10 +55,12 @@ These are hard; the design is shaped by them.
   result without its call, nor an assistant tool_call without its result, nor
   reorder the pair.
 - **Never touch:** system/developer messages (they carry the system prompt and the
-  agentdox-injected block), the **volatile tail** (newest user-authored run, or the
-  trailing tool-result run of the current loop — the same window
-  `features.ts`/`cache-control.ts` treat as fresh), and image parts (they are
-  capability-relevant; see Edge cases).
+  agentdox-injected block), the **protected tail** (newest user-authored run, or the
+  trailing tool-result run of the current loop — the same window `features.ts`
+  treats as fresh), and image parts (they are capability-relevant; see Edge cases).
+  Note that `cache-control.ts` deliberately does **not** treat that tail as fresh:
+  a conversation is append-only, so the tail is exactly what the *next* turn will
+  read back out of the cache, and it gets a breakpoint (see Prompt cache below).
 - **Determinism.** `auto-model-router explain` replays a past decision offline.
   Phase 1 is a pure function of `(messages, target budget, model window)` →
   replayable. Phase 2 breaks this unless the summary is **pinned and persisted**
@@ -67,10 +69,19 @@ These are hard; the design is shaped by them.
   The governing law is already stated for the agentdox bridge
   (`src/context/bridge.ts`): *the same bytes are re-injected verbatim and the cache
   survives; a refresh rides on a cache miss that was happening anyway.* Compaction
-  obeys it — Phase 1 rules are **stable** (identical input → identical elision each
-  turn), so a message elided last turn is elided byte-identically this turn and the
-  prefix does not churn; Phase 2 summaries are pinned per conversation and refreshed
-  only when the cache is already cold.
+  obeys it in two ways: rules are **stable** (identical input → identical elision
+  each turn) *and* the truncation set is **monotone** (rule 3 below: oldest-first,
+  so it only extends forward and never rewrites an already-cached prefix). Phase 2
+  summaries are pinned per conversation and refreshed only when the cache is
+  already cold.
+- **Breakpoints must be reproducible.** A `cache_control` breakpoint only pays off
+  when a later turn asks to read the exact same byte prefix, so
+  `planCacheBreakpoints` places them where the next turn will place them again:
+  the system prefix, byte **milestones** at fixed multiples of
+  `cache.milestoneTokens` (default 20k) measured over *post-compaction* sizes, and
+  the **tail**. A boundary at "roughly 75% of history" — the pre-v0.2.9 behaviour —
+  drifts by one index per appended message, so every turn wrote a fresh cache entry
+  and read none of them.
 
 ## Precedent to reuse
 
@@ -184,8 +195,19 @@ A pure function `compact(messages, target, protectFrom) → { messages, saved, n
    fetch is authoritative.
 3. **Truncate large stale results** (`maxToolResultBytes`): remaining tool results
    outside the protected window whose content exceeds `maxToolResultBytes` are
-   reduced to `keepHeadBytes` + breadcrumb + `keepTailBytes`. Applied to the
-   **largest/oldest first** until under `target` or exhausted.
+   reduced to `keepHeadBytes` + breadcrumb + `keepTailBytes`. Applied **oldest
+   first** until under `target` or exhausted.
+
+   Oldest-first is a **prompt-cache requirement**, not an aesthetic. The selected
+   set is then always an index-ordered prefix of the eligible results, so across
+   turns it only ever extends forward: an existing edit keeps its index and keep
+   bytes, and new edits land after every previous one — leaving the cached prefix
+   byte-identical. Selecting largest-first instead inserts new edits at arbitrary
+   early indices on later turns, rewriting history the upstream had already
+   cached. Measured under largest-first: 61% cache read (bimodal 44%/90%, with
+   `cachedTokens` pinned at the system prefix on half the requests) against
+   76–82% on comparable pre-compaction sessions. `test/compaction.test.ts`
+   ("the edit set only ever extends forward") pins the property.
 4. **Age-drop assistant reasoning:** reasoning fields on assistant messages outside
    the protected window are dropped. (Largely redundant with the model-driven
    `stripAssistantReasoning`; matters only for reasoning-replay authors.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/config/defaults.ts

@@ -144,6 +144,10 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// Anthropic allows 4 breakpoints; OpenRouter translates for other vendors.
 		maxBreakpoints: 4,
 		minPromptTokens: 2_048,
+		// One slot for the system prefix, one for the tail, leaving two milestones
+		// live at 4 breakpoints. 20k spacing keeps them coarse enough that a
+		// milestone survives many turns of appended tool output.
+		milestoneTokens: 20_000,
 	},
 	context: {
 		// Off until an agentdox URL + token are configured. Enabling this changes

package/src/config/schema.ts

@@ -127,6 +127,7 @@ const cache = z.strictObject({
 	injectBreakpoints: z.boolean().optional(),
 	maxBreakpoints: z.number().int().positive().optional(),
 	minPromptTokens: z.number().int().nonnegative().optional(),
+	milestoneTokens: z.number().int().positive().optional(),
 });
 
 const context = z.strictObject({

package/src/config/types.ts

@@ -286,6 +286,13 @@ export interface CacheConfig {
 	maxBreakpoints: number;
 	/** Skip injection below this prompt-token estimate; small prompts cannot cache. */
 	minPromptTokens: number;
+	/**
+	 * Spacing of the stable mid-history breakpoints, in prompt tokens. Boundaries
+	 * land at fixed multiples of this size, so the same prefix recurs turn after
+	 * turn and each turn reads what the last one wrote. Smaller = finer recovery
+	 * after a history rewrite, at the cost of more breakpoint slots.
+	 */
+	milestoneTokens: number;
 }
 
 export interface BudgetConfig {

package/src/cost/ledger.ts

@@ -117,6 +117,13 @@ const TRUST_SELECT = `COUNT(*) AS attempts,
  * body streams once it starts. Errored/aborted and non-streaming rows (null
  * ttft) are excluded; throughput additionally requires a positive completion
  * count and elapsed time.
+ *
+ * Aggregated over a RECENT WINDOW (LATENCY_WINDOW_ROWS newest rows per slug),
+ * NOT all history: a model that degrades — e.g. deepseek-v4-flash collapsing
+ * from ~18 tok/s to ~7 — must move its score fast, or the penalty is drowned by
+ * hundreds of historical good rows and never demotes it (observed live: it kept
+ * 100% of coding at ~53s/turn despite latencyWeight=0.75). Trust (reliability)
+ * stays all-time; latency (volatile) is recency-weighted.
  */
 const LATENCY_SELECT = `COUNT(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL THEN 1 END) AS samples,
 		AVG(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND error IS NULL THEN ttft_ms END) AS ttft_ms,
@@ -127,6 +134,14 @@ const LATENCY_SELECT = `COUNT(CASE WHEN ttft_ms IS NOT NULL AND ttft_ms > 0 AND
 			AND json_extract(usage, '$.completionTokens') > 0
 			THEN latency_ms - ttft_ms END) AS elapsed_ms_sum`;
 
+/**
+ * Recent-rows window for latency stats: recent enough to react to a degrading
+ * model, wide enough to stay stable for a busy one. Rows are taken newest-first
+ * and then filtered by LATENCY_SELECT, so recent aborts naturally shrink the
+ * qualifying sample count (and can drop a model below latencyMinSamples).
+ */
+export const LATENCY_WINDOW_ROWS = 100;
+
 /**
  * Recovers the `UpstreamErrorKind` from the text turn.ts stored.
  *
@@ -231,8 +246,12 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 	const trustStmt = db.query(`SELECT ${TRUST_SELECT} FROM ledger WHERE slug = ?`);
 	const trustHarnessStmt = db.query(`SELECT ${TRUST_SELECT} FROM ledger WHERE slug = ? AND harness_id = ?`);
 	const allTrustStmt = db.query(`SELECT slug, ${TRUST_SELECT} FROM ledger GROUP BY slug`);
-	const latencyStmt = db.query(`SELECT ${LATENCY_SELECT} FROM ledger WHERE slug = ?`);
-	const latencyHarnessStmt = db.query(`SELECT ${LATENCY_SELECT} FROM ledger WHERE slug = ? AND harness_id = ?`);
+	const latencyStmt = db.query(
+		`SELECT ${LATENCY_SELECT} FROM (SELECT * FROM ledger WHERE slug = ? ORDER BY created_at_ms DESC LIMIT ${LATENCY_WINDOW_ROWS})`,
+	);
+	const latencyHarnessStmt = db.query(
+		`SELECT ${LATENCY_SELECT} FROM (SELECT * FROM ledger WHERE slug = ? AND harness_id = ? ORDER BY created_at_ms DESC LIMIT ${LATENCY_WINDOW_ROWS})`,
+	);
 	const ratioStmt = db.query("SELECT est_bytes, actual_tokens, samples FROM token_calibration WHERE tokenizer = ?");
 	const recentStmt = db.query("SELECT * FROM ledger ORDER BY created_at_ms DESC LIMIT ?");
 	const cacheMetaStmt = db.query("SELECT fetched_at_ms FROM catalog_cache WHERE id = 1");

package/src/router/cache-control.ts

@@ -2,15 +2,39 @@
  * Cache-breakpoint placement (Anthropic-style `cache_control: ephemeral`;
  * OpenRouter translates these to OpenAI/Google cache primitives, so one
  * mechanism covers every target). Returns message indices to mark.
+ *
+ * Placement is chosen for REUSE ACROSS TURNS, not for a single request. A
+ * breakpoint only pays off when a LATER turn asks to read the exact same byte
+ * prefix, so every boundary here must be one the next turn will reproduce:
+ *
+ *  - the system prefix, which never moves;
+ *  - byte MILESTONES at fixed multiples of `cache.milestoneTokens`, which land
+ *    on the same message every turn for as long as the prefix is unchanged
+ *    (a boundary at "roughly 75% of history" drifts with every appended
+ *    message, so it writes a fresh entry each turn and never reads one);
+ *  - the tail, so the whole of this turn's prompt becomes the entry the NEXT
+ *    turn reads. A conversation is append-only: nothing already in the array
+ *    can change later, so there is no "volatile tail" to keep out of the
+ *    cache. Walking back over an agent loop's trailing tool run instead left
+ *    everything the loop had accumulated permanently uncached.
+ *
+ * Milestones are measured over POST-compaction sizes, so the boundaries match
+ * the bytes actually dispatched.
  */
 
 import type { CatalogModel } from "../catalog/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { priceAt } from "../cost/forecast.ts";
 import { estimateTokens } from "../tokens/estimate.ts";
-import type { NormMessage, NormRequest } from "../wire/types.ts";
+import type { CompactionEdit, NormRequest } from "../wire/types.ts";
+import { compactedBytes } from "./compaction.ts";
 
-export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg: RouterConfig): number[] {
+export function planCacheBreakpoints(
+	req: NormRequest,
+	model: CatalogModel,
+	cfg: RouterConfig,
+	compactionPlan: readonly CompactionEdit[] = [],
+): number[] {
 	if (!cfg.cache.injectBreakpoints) return [];
 	const promptTokens = estimateTokens(req.promptBytes, model.tokenizer, null);
 	// Small prompts cannot amortize cache-write cost.
@@ -19,6 +43,8 @@ export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg:
 	if (priceAt(model, Math.max(1, promptTokens)).cacheRead === undefined) return [];
 
 	const messages = req.messages;
+	if (messages.length === 0) return [];
+
 	const picks: number[] = [];
 
 	// 1. End of the last system message: the most stable, usually largest prefix.
@@ -30,28 +56,33 @@ export function planCacheBreakpoints(req: NormRequest, model: CatalogModel, cfg:
 		}
 	}
 
-	// 2. End of the last message before the volatile tail — the newest
-	//    user-authored content, or the trailing tool-result run of an agent
-	//    loop. Caches everything the model has already seen, leaving only the
-	//    fresh tail uncached.
-	const tail = messages[messages.length - 1];
-	if (tail !== undefined) {
-		let pred: (m: NormMessage) => boolean;
-		if (tail.role === "user") pred = (m) => m.role === "user";
-		else if (tail.role === "tool") pred = (m) => m.role === "tool" || (m.role === "assistant" && m.toolCalls.length > 0);
-		// An assistant tail has no fresh human content; the whole history is prefix.
-		else pred = () => false;
-		let i = messages.length - 1;
-		while (i >= 0) {
-			const m = messages[i];
-			if (m === undefined || !pred(m)) break;
-			i--;
+	// 2. The tail: everything this turn sent, cached for the next turn to read.
+	picks.push(messages.length - 1);
+
+	// 3. Stable byte milestones through the history, newest first so the slots
+	//    left over by 1 and 2 cover the largest readable prefixes.
+	const editByIndex = new Map<number, CompactionEdit>();
+	for (const e of compactionPlan) editByIndex.set(e.index, e);
+	const bytesPerToken = req.promptBytes / Math.max(1, promptTokens);
+	const milestoneBytes = Math.max(1, Math.floor(cfg.cache.milestoneTokens * bytesPerToken));
+	const milestones: number[] = [];
+	let cumulative = 0;
+	let nextMilestone = milestoneBytes;
+	for (let i = 0; i < messages.length - 1; i++) {
+		const m = messages[i];
+		if (m === undefined) continue;
+		cumulative += compactedBytes(m.textBytes, editByIndex.get(i));
+		if (cumulative >= nextMilestone) {
+			milestones.push(i);
+			// Skip past every milestone this message already crossed, so one huge
+			// message cannot claim a run of adjacent boundaries.
+			while (cumulative >= nextMilestone) nextMilestone += milestoneBytes;
 		}
-		if (i >= 0) picks.push(i);
 	}
-
-	// 3. Stable prefix boundary at roughly 75% of history.
-	if (messages.length > 1) picks.push(Math.floor((messages.length - 1) * 0.75));
+	for (let i = milestones.length - 1; i >= 0; i--) {
+		const idx = milestones[i];
+		if (idx !== undefined) picks.push(idx);
+	}
 
 	// Dedupe preserving priority order, cap, return ascending indices.
 	const seen = new Set<number>();

package/src/router/compaction.ts

@@ -26,6 +26,17 @@ const EMPTY: CompactionResult = { edits: [], savedBytes: 0 };
 /** Approximate byte cost of an elision breadcrumb; savings are net of it. */
 const BREADCRUMB_BYTES = 120;
 
+/**
+ * Byte size a message ends up with once `edit` is applied — the size that
+ * actually reaches the upstream. Cache-breakpoint placement walks these rather
+ * than the raw `textBytes`, so its boundaries match the dispatched bytes.
+ */
+export function compactedBytes(originalBytes: number, edit: CompactionEdit | undefined): number {
+	if (edit === undefined) return originalBytes;
+	const kept = edit.mode === "stub" ? BREADCRUMB_BYTES : edit.keepHead + edit.keepTail + BREADCRUMB_BYTES;
+	return Math.min(originalBytes, kept);
+}
+
 /**
  * First string value in a tool call's argument JSON — a schema-agnostic proxy
  * for the resource a call operates on (a `path`, `id`, `query`, ...). Used to
@@ -73,9 +84,18 @@ interface ToolResult {
 /**
  * Plans compaction for a turn's messages toward `targetBytes` of total prompt.
  * Duplicate and superseded elisions (pure stale-data wins) are always applied;
- * large-result truncation (more lossy) runs largest-first only until the target
+ * large-result truncation (more lossy) runs OLDEST-first only until the target
  * is met. `promptBytes` is the whole prompt (messages + system + tool schemas),
  * so the target is compared against the real dispatched size.
+ *
+ * Oldest-first is a prompt-cache requirement, not a preference. The truncated
+ * set is then always an index-ordered PREFIX of the eligible results, so as a
+ * conversation grows and the target tightens the set only ever EXTENDS FORWARD:
+ * an edit already made keeps the same index and the same keep bytes, and a new
+ * edit lands after every previous one. Selecting largest-first instead inserts
+ * fresh edits at arbitrarily early indices on later turns, rewriting history
+ * the upstream had already cached and collapsing cache reads to the system
+ * prefix (measured: 61% cache read, bimodal, vs 76-82% before compaction).
  */
 export function planCompaction(
 	messages: readonly NormMessage[],
@@ -145,11 +165,11 @@ export function planCompaction(
 		}
 	}
 
-	// Rule 3: truncate large stale results, largest first, until under target.
+	// Rule 3: truncate large stale results, OLDEST first, until under target.
+	// `tools` is already in message order, so the filter alone yields that order
+	// and the selected set stays an extend-forward prefix across turns.
 	const keepBudget = cfg.keepHeadBytes + cfg.keepTailBytes + BREADCRUMB_BYTES;
-	const truncatable = tools
-		.filter((t) => !done.has(t.index) && t.bytes > cfg.maxToolResultBytes && t.bytes > keepBudget)
-		.sort((a, b) => b.bytes - a.bytes || a.index - b.index);
+	const truncatable = tools.filter((t) => !done.has(t.index) && t.bytes > cfg.maxToolResultBytes && t.bytes > keepBudget);
 	for (const t of truncatable) {
 		if (promptBytes - saved <= targetBytes) break;
 		edits.push({ index: t.index, mode: "truncate", keepHead: cfg.keepHeadBytes, keepTail: cfg.keepTailBytes, note: `large ${t.name || "tool"} result` });

package/src/router/select.ts

@@ -390,8 +390,9 @@ export function select(args: SelectArgs): Decision {
 		if (fallbacks.length >= 2) break;
 	}
 
-	// 7. Cache breakpoints.
-	const cacheBreakpointMessageIndices = planCacheBreakpoints(req, chosen.model, cfg);
+	// 7. Cache breakpoints, measured over post-compaction sizes so the
+	//    boundaries match the bytes that actually get dispatched.
+	const cacheBreakpointMessageIndices = planCacheBreakpoints(req, chosen.model, cfg, compactionPlan);
 
 	// 8. Guarded probe: only tiers configured for probing, and only when a
 	//    strictly higher tier exists inside the profile envelope to escalate into.

package/test/cache-control.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+
+import { normalizeCatalogModel } from "../src/catalog/openrouter-catalog.ts";
+import type { CatalogModel } from "../src/catalog/types.ts";
+import { loadConfig } from "../src/config/load.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+import { priceAt } from "../src/cost/forecast.ts";
+import { planCacheBreakpoints } from "../src/router/cache-control.ts";
+import { planCompaction } from "../src/router/compaction.ts";
+import { parseChatRequest } from "../src/wire/openai/request.ts";
+import type { NormRequest } from "../src/wire/types.ts";
+
+const FIXTURE = (await Bun.file("test/fixtures/openrouter-models.json").json()) as { data: unknown[] };
+const MODELS: CatalogModel[] = FIXTURE.data.map(normalizeCatalogModel).filter((m): m is CatalogModel => m !== null);
+// Breakpoints are only planned for models that publish a cache-read price.
+const CACHING = MODELS.find((m) => priceAt(m, 100_000).cacheRead !== undefined);
+if (CACHING === undefined) throw new Error("fixture has no model with a published cache-read price");
+const MODEL: CatalogModel = CACHING;
+
+const BASE = loadConfig({});
+function cfg(over: Partial<RouterConfig["cache"]> = {}): RouterConfig {
+	return { ...BASE, cache: { ...BASE.cache, ...over } };
+}
+
+const RESULT_BYTES = 8_000;
+const result = (turn: number): string => `result ${turn}:${"x".repeat(RESULT_BYTES)}`;
+
+/** A tool-loop conversation: system, one user ask, then `turns` call/result pairs. */
+function loop(turns: number): NormRequest {
+	const messages: Record<string, unknown>[] = [
+		{ role: "system", content: `You are a coding agent.${"!".repeat(4_000)}` },
+		{ role: "user", content: "find the bug" },
+	];
+	for (let t = 0; t < turns; t++) {
+		messages.push({
+			role: "assistant",
+			content: null,
+			tool_calls: [{ id: `c${t}`, type: "function", function: { name: "read", arguments: `{"path":"f${t}.ts"}` } }],
+		});
+		messages.push({ role: "tool", tool_call_id: `c${t}`, content: result(t) });
+	}
+	return parseChatRequest({ model: "auto", messages }, new Headers());
+}
+
+describe("planCacheBreakpoints", () => {
+	test("marks the tail so the next turn can read this turn's whole prompt", () => {
+		const req = loop(12);
+		const picks = planCacheBreakpoints(req, MODEL, cfg());
+		expect(picks).toContain(req.messages.length - 1);
+	});
+
+	test("marks the system prefix", () => {
+		const req = loop(12);
+		const picks = planCacheBreakpoints(req, MODEL, cfg());
+		expect(picks).toContain(0);
+	});
+
+	test("mid-history boundaries are stable as the conversation grows", () => {
+		// Uncapped so the comparison is about placement, not slot eviction.
+		const uncapped = cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 });
+		const mid = (turns: number): number[] => {
+			const req = loop(turns);
+			const tail = req.messages.length - 1;
+			return planCacheBreakpoints(req, MODEL, uncapped).filter((i) => i !== 0 && i !== tail);
+		};
+		const early = mid(10);
+		expect(early.length).toBeGreaterThan(1);
+		for (const turns of [11, 12, 13, 20]) {
+			// Every boundary the earlier turn wrote is still a boundary later, so
+			// the later turn reads what the earlier one paid to write.
+			expect(mid(turns)).toEqual(expect.arrayContaining(early));
+		}
+	});
+
+	test("boundaries are spaced by the milestone size, not by message position", () => {
+		const req = loop(30);
+		const tail = req.messages.length - 1;
+		const coarse = planCacheBreakpoints(req, MODEL, cfg({ maxBreakpoints: 64, milestoneTokens: 20_000 })).filter(
+			(i) => i !== 0 && i !== tail,
+		);
+		const fine = planCacheBreakpoints(req, MODEL, cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 })).filter(
+			(i) => i !== 0 && i !== tail,
+		);
+		expect(fine.length).toBeGreaterThan(coarse.length);
+	});
+
+	test("keeps the system prefix and the tail when slots are scarce", () => {
+		const req = loop(30);
+		const picks = planCacheBreakpoints(req, MODEL, cfg({ maxBreakpoints: 2, milestoneTokens: 4_000 }));
+		expect(picks).toEqual([0, req.messages.length - 1]);
+	});
+
+	test("milestones follow post-compaction sizes", () => {
+		const req = loop(30);
+		const tail = req.messages.length - 1;
+		const plan = planCompaction(req.messages, BASE.compaction, req.promptBytes * 0.3, req.promptBytes);
+		expect(plan.edits.length).toBeGreaterThan(0);
+		const options = cfg({ maxBreakpoints: 64, milestoneTokens: 4_000 });
+		const raw = planCacheBreakpoints(req, MODEL, options).filter((i) => i !== 0 && i !== tail);
+		const compacted = planCacheBreakpoints(req, MODEL, options, plan.edits).filter((i) => i !== 0 && i !== tail);
+		// Shrinking early results pushes each byte milestone later in the history.
+		expect(compacted.length).toBeLessThan(raw.length);
+		expect(Math.min(...compacted)).toBeGreaterThan(Math.min(...raw));
+	});
+
+	test("injects nothing below the minimum prompt size, or when disabled", () => {
+		const small = parseChatRequest({ model: "auto", messages: [{ role: "user", content: "hi" }] }, new Headers());
+		expect(planCacheBreakpoints(small, MODEL, cfg())).toEqual([]);
+		expect(planCacheBreakpoints(loop(12), MODEL, cfg({ injectBreakpoints: false }))).toEqual([]);
+	});
+});

package/test/compaction.test.ts

@@ -99,6 +99,43 @@ describe("planCompaction", () => {
 		const b = planCompaction(msgs, CFG, 1, 10_000);
 		expect(a).toEqual(b);
 	});
+
+	// The prompt-cache contract: an edit, once made, keeps its index and its keep
+	// bytes for the rest of the conversation, and every later edit lands AFTER
+	// it. Anything else rewrites already-cached history and forces a full
+	// re-read of the prefix on the next turn.
+	test("the edit set only ever extends forward as the conversation grows", () => {
+		// Sizes GROW with age-descending order (newest results are the biggest), so
+		// a size-ordered planner selects newest-first and its later additions move
+		// BACKWARD into already-cached history. Equal-sized results would make
+		// every ordering identical and the assertions vacuous.
+		const loop = (pairs: number): NormMessage[] => {
+			const msgs: NormMessage[] = [user("go")];
+			for (let i = 0; i < pairs; i++) {
+				const content = `R${i}:${"x".repeat(200 + i * 40)}`;
+				msgs.push(asst(`c${i}`, "read", `{"path":"f${i}.ts"}`), toolMsg(`c${i}`, "read", content));
+			}
+			return msgs;
+		};
+		let previous: number[] = [];
+		for (let pairs = 4; pairs <= 24; pairs++) {
+			const msgs = loop(pairs);
+			const promptBytes = msgs.reduce((n, m) => n + m.textBytes, 0);
+			// A target the plan can hit with a handful of edits: this is where the
+			// selection ORDER decides which results get truncated. A saturating
+			// target would truncate everything and hide the difference.
+			const indices = planCompaction(msgs, CFG, Math.floor(promptBytes * 0.8), promptBytes).edits.map((e) => e.index);
+			// Nothing already compacted may be dropped...
+			expect(indices).toEqual(expect.arrayContaining(previous));
+			// ...and anything new lands after every existing edit.
+			const added = indices.filter((i) => !previous.includes(i));
+			if (previous.length > 0 && added.length > 0) {
+				expect(Math.min(...added)).toBeGreaterThan(Math.max(...previous));
+			}
+			previous = indices;
+		}
+		expect(previous.length).toBeGreaterThan(4);
+	});
 });
 
 describe("renderUpstreamBody applies compaction", () => {

package/test/failover.test.ts

@@ -68,7 +68,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 },
+		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, 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" },

package/test/trust-attribution.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import { loadConfig } from "../src/config/load.ts";
-import { createLedger } from "../src/cost/ledger.ts";
+import { createLedger, LATENCY_WINDOW_ROWS } from "../src/cost/ledger.ts";
 import { EMPTY_USAGE, type LedgerEntry } from "../src/cost/types.ts";
 import { openDb } from "../src/util/sqlite.ts";
 
@@ -198,6 +198,22 @@ describe("latency signal", () => {
 		expect(l?.tokensPerSec).toBeCloseTo(100, 5);
 		expect(l?.samples).toBe(2);
 	});
+
+	test("throughput and ttft track a recent window, not the lifetime average", () => {
+		// Old rows are fast; the recent window is slow. Latency must reflect the
+		// recent (slow) behaviour so a degraded model is penalised, not masked by
+		// its history. Lifetime blend here would be ~57 tok/s; the window is 10.
+		const rows: Array<Partial<LedgerEntry>> = [];
+		let t = 1;
+		for (let i = 0; i < 50; i++)
+			rows.push({ createdAtMs: t++, ttftMs: 200, latencyMs: 1200, usage: { ...EMPTY_USAGE, completionTokens: 1000 } });
+		for (let i = 0; i < LATENCY_WINDOW_ROWS; i++)
+			rows.push({ createdAtMs: t++, ttftMs: 4000, latencyMs: 14000, usage: { ...EMPTY_USAGE, completionTokens: 100 } });
+		const l = latencyOf(rows);
+		expect(l?.samples).toBe(LATENCY_WINDOW_ROWS);
+		expect(l?.tokensPerSec).toBeCloseTo(10, 0);
+		expect(l?.ttftMs).toBeCloseTo(4000, 5);
+	});
 });
 
 describe("v4 migration", () => {

package/test/turn.test.ts

@@ -68,7 +68,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 },
+		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, 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" },